내가 프로젝트에서 사용하는 개발 방식 - IDAD (Issue-Driven Agent Development)

내가 프로젝트에서 사용하는 개발 방식 - IDAD (Issue-Driven Agent Development)

AI 코딩 에이전트를 프로젝트에 사용하기 시작하면서 개발 방식이 조금씩 바뀌었습니다.

처음에는 단순히 “AI에게 코드를 작성하게 한다” 정도로 생각했습니다. 하지만 실제 프로젝트에 적용해보니 중요한 것은 AI에게 코드를 얼마나 잘 쓰게 하느냐가 아니었으며 가장 중요한 것은 AI가 무엇을 기준으로 코드를 작성하게 할 것인가였습니다. 

이러한 방식으로 인해 스펙 주도 개발이 유행하였고, 대부분의 개발자가 이 기준을 스펙으로 진행하고 있습니다.

하지만 저는 프로젝트에서 이 기준을 이슈로 잡아 진행하고 있으며 이 방식을 개인적으로 IDAD(Issue-Driven Agent Development)라고 부릅니다.

말 그대로, 이슈를 중심으로 AI 에이전트가 개발을 수행하는 방식입니다.

진행중인 SpecGuard 프로젝트에서 IDAD, 즉 이슈 기반으로 개발을 진행하는 모습

---

왜 이슈가 중요해졌을까

기존 개발 방식에서는 이슈가 사람을 위한 작업 관리 도구에 가까웠습니다.

이슈 확인
  ↓
사람이 요구사항 해석
  ↓
사람이 코드 작성
  ↓
테스트
  ↓
PR 생성
  ↓
리뷰

 

하지만 AI 코딩 에이전트를 사용하면 이슈의 역할이 달라집니다.

이슈는 더 이상 단순한 할 일 목록이 아닙니다. AI 에이전트가 읽는 작업 지시서가 됩니다.

Issue
  ↓
Agent Context
  ↓
Branch
  ↓
Implementation
  ↓
Pull Request
  ↓
Review
  ↓
Merge

 

즉, 이슈는 다음 역할을 하게 됩니다.

역할	설명
문제 정의	무엇을 해결해야 하는지 알려준다
범위 제한	어디까지 수정할 수 있는지 정한다
맥락 제공	AI가 참고해야 할 코드, 문서, 로그를 제공한다
완료 기준	어떤 상태가 되면 끝난 것인지 정한다
리뷰 기준	PR이 제대로 작성되었는지 판단하는 기준이 된다

제가 IDAD에서 가장 중요하게 보는 점은 이것입니다.

이슈가 좋아야 AI가 좋은 코드를 작성할 수 있다.

AI 에이전트는 이슈에 적힌 내용을 기준으로 움직입니다.
이슈가 모호하면 AI는 빈칸을 추측으로 채웁니다.
그리고 추측으로 작성된 코드는 리뷰 비용을 크게 늘립니다.

---

IDAD란 무엇인가?

제가 말하는 IDAD는 간단합니다.

이슈를 AI 에이전트가 실행할 수 있는 작업 단위를 만들고,
AI가 그 이슈를 기준으로 구현을 진행하고,
사람은 PR에서 이슈 충족 여부를 검증하는 개발 방식

기존 이슈 기반 개발과 비슷해 보일 수 있지만 차이가 있습니다.

기존 이슈는 주로 사람을 위한 설명이었습니다.
하지만 IDAD에서 이슈는 AI가 바로 작업할 수 있어야 합니다.

그래서 IDAD의 이슈에는 단순히 “무엇을 한다”만 적지 않고 아래와 같은 내용이 들어가야 합니다.

## 문제
현재 어떤 문제가 있는가?

## 목표
이 이슈가 완료되면 무엇이 가능해야 하는가?

## 변경 범위
수정해도 되는 영역은 어디인가?

## 제외 범위
이번 작업에서 건드리지 말아야 할 영역은 어디인가?

## 완료 조건
어떤 조건을 만족하면 완료로 볼 수 있는가?

## 검증 방법
어떤 테스트, 명령, 화면 확인으로 검증할 것인가?

## 참고 맥락
관련 PR, 문서, 스펙, 로그, 오류 메시지는 무엇인가?

 

이 정도는 있어야 AI 에이전트가 안정적으로 작업할 수 있습니다.

---

내가 사용하는 IDAD 흐름

제가 프로젝트에서 사용하는 흐름은 대략 이렇습니다.

1. 이슈를 작성한다
2. 문제, 목표, 범위, 완료 조건, 검증 방법을 적는다
3. AI 에이전트에게 이슈 기준으로 작업을 요청한다
4. AI 에이전트가 관련 파일을 탐색한다
5. 최소 변경으로 구현한다
6. 테스트 또는 수동 검증을 수행한다
7. 이슈 번호와 연결된 PR을 만든다
8. 사람이 PR을 리뷰한다
9. 이슈 충족 여부와 범위 초과 여부를 확인한다

 

여기서 핵심은 이슈 하나가 하나의 목적만 가져야 한다는 점입니다.

예를 들어 이런 이슈는 좋지 않습니다.

회원가입 개선

 

이런식으로 작성된 이슈에서 동작할 수 있는 경우의 수는 너무나 넓습니다.
AI는 이메일 검증을 고칠 수도 있고, 비밀번호 정책을 바꿀 수도 있고, UI를 수정할 수도 있고, API 응답까지 건드릴 수도 있습니다.

반면 이런 이슈는 더 좋습니다.

회원가입 시 이메일 중복 오류 메시지를 명확하게 수정한다

 

이슈의 목적이 분명합니다. 수정 범위도 제한하기 쉽고, 리뷰할 때도 “이 PR이 이 이슈를 해결했는가?”를 판단하기 쉽습니다.

---

좋은 IDAD 이슈 예시

제가 선호하는 이슈 형태는 아래와 같습니다.

## 문제
회원가입 화면에서 이미 등록된 이메일을 입력하면 일반적인 오류 메시지만 표시된다.
사용자는 왜 회원가입이 실패했는지 명확히 알기 어렵다.

## 목표
이메일 중복 오류 발생 시 사용자가 원인을 명확히 알 수 있도록 메시지를 개선한다.

## 변경 범위
- 회원가입 화면의 오류 메시지 표시 로직
- 이메일 중복 오류 응답 처리 로직

## 제외 범위
- DB 스키마 변경 없음
- 회원가입 API 응답 필드 추가 없음
- 이메일 인증 로직 변경 없음
- 관리자 기능 변경 없음

## 완료 조건
- 중복 이메일로 회원가입 시도 시 "이미 사용 중인 이메일입니다." 메시지를 표시한다.
- 신규 이메일 회원가입은 기존과 동일하게 정상 동작한다.
- 다른 회원가입 오류 메시지는 기존과 동일하게 유지한다.

## 검증 방법
- 중복 이메일로 회원가입 시도
- 신규 이메일로 회원가입 시도
- 기존 회원가입 테스트 통과 확인

 

이렇게 작성하면 AI가 해야 할 일과 하지 말아야 할 일이 명확해집니다.

제가 IDAD에서 특히 중요하게 보는 항목은 제외 범위입니다.
AI 에이전트는 관련 코드를 넓게 수정하려는 경향이 있기 때문에 이번 이슈에서 건드리지 말아야 할 영역을 명확히 적어야 합니다.

---

Issue-Driven Agent Developemnt의 장단점

IDAD의 장점

제가 IDAD를 쓰면서 느낀 장점은 크게 다섯 가지입니다.

장점	설명
도입 비용이 낮다	대부분의 프로젝트는 이미 이슈 기반으로 일하고 있다
작업 단위가 작아진다	AI가 처리하기 좋은 단위로 일을 쪼갤 수 있다
추적성이 좋아진다	이슈, 브랜치, 커밋, PR, 리뷰가 연결된다
운영 업무에 강하다	버그 수정, 문서 보완, 테스트 추가에 적합하다
병렬 처리가 쉽다	여러 이슈를 여러 에이전트가 나누어 처리할 수 있다

특히 추적성은 실제 프로젝트에서 꽤 중요합니다.

Issue #128
  ↓
feature/issue-128-fix-email-error-message
  ↓
Commit
  ↓
Pull Request
  ↓
Review
  ↓
Merge

 

나중에 “이 코드는 왜 들어왔지?”라고 확인해야 할 때가 있습니다.
그때 PR만 보는 것보다, 원래 이슈까지 연결되어 있으면 판단이 훨씬 쉬워집니다. 또한 여러 이슈들을 여러 에이전트가 병렬 처리가 가능하기에 개발 속도가 굉장히 빨리지는 것을 체감할 수 있었습니다.

 

IDAD의 단점

물론 IDAD가 모든 문제를 해결하는 것은 아닙니다.

가장 큰 단점은 이슈가 명세보다 약하다는 점입니다. 일반적인 이슈에는 다음 내용이 충분히 들어가지 않는 경우가 많습니다.

누락되기 쉬운 내용	예시
API 계약	요청 필드, 응답 필드, 상태 코드
예외 처리	실패 시 어떤 응답을 반환할 것인가
권한	누가 이 기능을 사용할 수 있는가
상태 전이	어떤 상태에서 어떤 상태로 변경 가능한가
데이터 소유권	어떤 사용자가 어떤 데이터를 소유하는가
장애 처리	재시도, 타임아웃, 롤백 기준

이런 내용이 빠진 상태에서 AI가 구현하면 겉으로는 동작하는 코드가 나올 수 있지만 시스템의 계약을 위반할 수 있습니다.

예를 들어 API 응답 필드를 마음대로 추가하거나, 권한 검증을 누락하거나, 기존 상태 전이 규칙을 깨는 코드가 만들어질 수 있습니다. 

---

그래서 SDD와는 무엇이 다르고 언제, 어떻게 사용해야 하는가?

AI 시대의 개발 방식으로 SDD, 즉 Spec-Driven Development도 자주 언급됩니다. 제가 보는 IDAD와 SDD의 차이는 이렇습니다.

기준	SDDI	IDAD
중심	스펙	이슈
목적	구현 전 요구사항과 계약을 명확히 고정	이슈 단위로 변경을 빠르게 실행
강점	API, 권한, 예외, 상태, 검증 기준을 구조화	기존 백로그와 PR 흐름에 자연스럽게 연결
적합한 작업	신규 기능, API, 보안, 결제, 권한 변경	버그 수정, 작은 기능, 문서, 테스트, 운영성 개선
검증 위치	구현 전 스펙 검증	PR 단계에서 이슈 충족 여부 검증
속도	상대적으로 느리지만 안정적	빠르지만 이슈 품질에 민감
실패 방식	스펙이 약하면 구현 전 차단 가능	이슈가 약하면 AI가 추측으로 구현할 수 있음

간단히 말하면 이렇게 정리할 수 있습니다.

SDD
= 무엇을 만들지 명확해질 때까지 구현하지 않는다.

IDAD
= 이슈를 실행 가능한 단위로 정리하고, 그 범위 안에서 구현한다.

 

둘 중 하나가 항상 더 좋다고 보지는 않습니다. 작업의 성격에 따라 다르게 써야 합니다.

현재 저는 A 프로젝트는 SDD 방식으로, B 프로젝트는 IDAD 방식을 사용하며 AI 에이전트를 활용한 여러 개발 방식을 사용해보고, 테스트하고, 실험해보고 있습니다. 현재까지의 상황으로는 서로 명백히 장단점과 성격이 다르기 때문에 큰 특이사항이 없다면 다음 프로젝트에서는 SDD+IDAD 방식으로 함께 사용하 개발을 진행하려 합니다.

오히려 같이 사용했을 때 더 좋은 퍼포먼스가 나올 것으로 생각합니다.

 

SDD와 IDAD를 무슨 기준으로 진행하는가?

제가 프로젝트에서 기준으로 삼는 방식은 단순합니다.

작고 명확한 변경
  → IDAD로 처리

계약과 리스크가 큰 변경
  → SDD로 전환

 

조금 더 구체적으로 나누면 다음과 같습니다.

작업 유형	적합한 방식	이유
문구 수정	IDAD	영향 범위가 작다
UI 버그 수정	IDAD	변경 범위를 제한하기 쉽다
테스트 추가	IDAD	기대 동작이 이미 존재한다
문서 보완	IDAD	위험도가 낮다
기존 기능의 작은 확장	IDAD	맥락이 이미 있다
신규 API 설계	SDD	요청/응답 계약이 필요하다
인증/권한 변경	SDD	보안 리스크가 크다
결제/정산	SDD	실패 비용이 높다
데이터 모델 변경	SDD	장기 영향이 크다
외부 시스템 연동	SDD	장애 처리와 재시도 정책이 필요하다

즉, IDAD는 모든 변경을 가볍게 처리하기 위한 방식이 아닙니다.
오히려 가벼운 변경과 무거운 변경을 빠르게 구분하기 위한 방식에 가깝습니다.

 

위험도에 따른 운영 기준

제가 IDAD를 운영할 때는 이슈를 위험도에 따라 구분합니다.

위험도	예시	처리 방식
낮음	문구 수정, 문서 보완, 테스트 이름 변경, 작은 UI 버그	IDAD로 바로 처리
중간	기존 기능의 작은 확장, 내부 로직 수정, 단일 화면 변경	IDAD로 처리하되 완료 조건과 검증 방법을 명확히 작성
높음	API 계약 변경, 권한 변경, 데이터 모델 변경, 결제/보안 관련 작업	이슈에서 스펙 작성을 요구하고 SDD로 전환

이 기준을 두면 AI 에이전트에게 맡겨도 되는 작업과, 먼저 사람이 설계해야 하는 작업을 구분할 수 있습니다.

---

IDAD를 사용할 때 지키는 규칙

제가 IDAD를 사용할 때 중요하게 보는 규칙은 다음과 같습니다.

 

1. 이슈 하나는 하나의 목적만 가진다

좋지 않은 이슈입니다.

대시보드 개선

 

좋은 이슈입니다.

대시보드 최근 주문 목록의 빈 상태 메시지를 추가한다

 

AI에게 맡길수록 작업 단위는 더 작고 명확해야 합니다.

 

2. 완료 조건은 검증 가능해야 한다

좋지 않은 완료 조건입니다.

사용성이 좋아진다.

 

좋은 완료 조건입니다.

비밀번호 형식이 올바르지 않을 때 INVALID_PASSWORD_FORMAT 메시지를 표시한다.

 

완료 조건은 테스트하거나 화면에서 확인할 수 있어야 합니다.

 

3. 검증 방법을 반드시 적는다

이슈에는 최소한 하나 이상의 검증 방법이 있어야 합니다.

검증 방식	예시
테스트 명령	npm test, ./gradlew test
수동 확인 경로	회원가입 화면 → 이메일 입력 → 가입 시도
기대 응답	HTTP 400, EMAIL_ALREADY_EXISTS
화면 기준	특정 오류 메시지 표시
로그 기준	특정 에러 로그가 발생하지 않음

검증 방법이 없으면 PR 리뷰에서 완료 여부를 판단하기 어렵습니다.

 

4. 제외 범위를 적는다

제가 가장 중요하게 보는 규칙 중 하나입니다.

이번 이슈에서는 DB 스키마를 변경하지 않는다.
API 응답 필드는 추가하지 않는다.
인증 로직은 수정하지 않는다.
관리자 화면은 변경하지 않는다.

 

AI 에이전트가 코드를 잘 작성하더라도, 범위를 넘어서면 좋은 변경이 아닙니다.

 

5. PR은 반드시 이슈와 연결한다

PR 설명에는 최소한 아래 내용이 있어야 합니다.

## 해결한 이슈
- Close #128

## 변경 내용
- 이메일 중복 오류 메시지 처리 로직 수정

## 검증 결과
- 중복 이메일 회원가입 시 오류 메시지 확인
- 신규 이메일 회원가입 정상 동작 확인
- 기존 테스트 통과

## 제외한 범위
- API 응답 필드 변경 없음
- DB 스키마 변경 없음

 

PR 리뷰는 단순히 코드 스타일을 보는 과정이 아닙니다.
IDAD에서는 PR이 원래 이슈를 정확히 해결했는지 확인해야 합니다.

---

IDAD의 안티패턴

제가 피하려고 하는 안티패턴은 다음과 같습니다.

안티패턴	문제
제목만 있는 이슈를 AI에게 넘긴다	AI가 대부분을 추측하게 된다
여러 기능을 하나의 이슈에 섞는다	변경 범위가 커지고 리뷰가 어려워진다
완료 조건 없이 “개선”만 요청한다	완료 여부를 판단할 수 없다
API 계약 변경을 이슈만으로 처리한다	요청/응답 계약이 깨질 수 있다
권한 변경을 스펙 없이 구현한다	보안 문제가 생길 수 있다
실패 케이스를 정의하지 않는다	정상 케이스만 동작하는 코드가 나올 수 있다
PR 리뷰에서 이슈 충족 여부를 보지 않는다	AI가 범위를 벗어나도 놓치기 쉽다

이런 방식은 IDAD라기보다는 단순히 AI에게 일을 던지는 것에 가깝습니다.

IDAD의 핵심은 AI를 많이 쓰는 것이 아닙니다.
AI가 실행할 수 있을 만큼 작업 기준을 명확하게 만드는 것입니다.

---

IDAD의 핵심

제가 IDAD를 사용하면서 내린 결론은 단순합니다.

AI 에이전트는 좋은 도구이지만, 좋은 입력이 없으면 좋은 결과를 만들기 어렵습니다.

AI에게 바로 코드를 맡기는 것보다 중요한 것은, 먼저 기준을 세우는 것입니다.

Issue = 작업의 입구
Spec  = 위험한 변경의 기준
PR    = 구현 결과의 검증 지점

 

가벼운 작업은 IDAD로 빠르게 처리하고 위험한 작업은 SDD로 전환해 먼저 스펙을 세우며 PR에서는 이슈와 스펙을 기준으로 구현 결과를 검증합니다.

---

마무리

IDAD는 AI에게 단순히 코드를 작성하게 하는 방식이 아닙니다. 이슈를 AI가 실행 가능한 작업 단위로 만들고, 그 이슈를 기준으로 구현과 리뷰를 연결하는 방식입니다.

정리하면 이렇습니다.

작고 명확한 변경
  → IDAD로 빠르게 처리한다

계약과 리스크가 큰 변경
  → SDD로 검증한 뒤 구현한다

 

AI 시대의 개발 생산성은 코드를 얼마나 빨리 작성하느냐만으로 결정되지 않으며 오히려 더 중요한 것은 어떤 입력을 기준으로 코드를 작성하게 하느냐입니다. 

서로 완전히 다른 개발 방식이 아니라, 서로의 장단점을 보완해줄 수 있는 방식이라고 생각하고 있습니다.

IDAD는 이슈로 정리하는 방식입니다.
SDD 스펙으로 검증하는 방식입니다.

둘의 공통점은 하나입니다.

AI에게 코드를 맡기기 전에, 사람이 먼저 기준을 세운다.