Issue-driven development workflow with TDD, parallel code review, and quality gates. Use when the user assigns an issue, asks to work on a feature, or says "이슈 작업 시작", "{feature} 작업해줘", or references a specific feature issue file. Orchestrates the full cycle from branch creation through merge.
이슈 파일을 기반으로 브랜치 생성 → TDD 계획 수립 → 구현 → 병렬 리뷰 → 수정 → 품질 검증 → 병합까지의 전체 사이클을 자동 수행한다.
모든 산출물은 Issues/{feature}/ 디렉토리에 생성한다. 피쳐 디렉토리명은 이슈 파일명에서 .md를 제외한 값이다.
| 순서 | 파일 | 내용 | 생성 단계 |
|---|---|---|---|
| 0 | 00_issue.md | 원본 이슈 문서 | Phase 0 |
| 1 | 01_plan.md | TDD 기반 개발 계획서 | Phase 1 |
| 2 | 02_review_implementation.md | 기능 구현 및 테스트 리뷰 | Phase 3 |
| 3 | 03_review_security.md | 성능 및 보안 리뷰 | Phase 3 |
| 4 | 04_review_architecture.md | 아키텍처 및 코드 스타일 리뷰 | Phase 3 |
| 5 | 05_review_synthesis.md |
| 종합 리뷰 및 액션 아이템 |
| Phase 4 |
| 6 | 06_fixes.md | 리뷰 반영 수정 기록 | Phase 5 |
| 7 | 07_summary.md | 전체 작업 요약 | Phase 7 |
아래 구간에서는 메인 에이전트가 동일 역할을 대신 수행하는 것을 금지한다. 산출물은 지정된 Task(subagent)의 반환값을 기준으로만 작성한다.
01_plan.md의 본문(개발 범위, TDD Step, 파일 계획 등)을 직접 작성·요약·재작성하는 것.Task(subagent_type: generalPurpose)를 먼저 호출하고, 그 응답 전문(아래 검증 가능한 흔적에 맞는 형식 포함)을 01_plan.md에 저장한 뒤에만 Phase 2로 진행한다.Task를 호출할 때 claude-4.6-opus-max-thinking외 다른 모델을 사용하는 것.02_review_*.md, 03_review_*.md, 04_review_*.md 내용을 직접 작성하는 것.Task를 정확히 3번 병렬 호출한 뒤, 각 Task 응답을 해당 파일에 저장한다. 3번이 아니면 파일을 쓰지 않는다.Task를 호출할 때 auto외 다른 모델을 사용하는 것.05_review_synthesis.md를 직접 작성하는 것.Task(subagent_type: generalPurpose + review-synthesizer 프롬프트) 응답을 저장한 뒤에만 Phase 5로 진행한다.05_review_synthesis.md가 Phase 4 게이트를 통과한 파일일 때만 수행한다.Subagent가 만든 문서는 파일 최상단에 YAML 프론트 매터 한 블록을 두어 출처를 남긴다. 메인 에이전트는 Task 프롬프트에 반드시 아래 형식을 출력하라고 명시한다.
공통 키(모든 해당 파일):
| 키 | 필수 | 설명 |
|---|---|---|
issue_driven_dev.source | 예 | 항상 문자열 subagent |
issue_driven_dev.phase | 예 | plan | review | synthesis |
issue_driven_dev.subagent_type | 예 | Task에 사용한 subagent_type 값 (문자열) |
issue_driven_dev.feature | 예 | Issues/{feature}/의 {feature} 디렉터리명과 동일 |
리뷰 전용(02/03/04):
| 키 | 필수 | 설명 |
|---|---|---|
issue_driven_dev.review_kind | 예 | implementation | security | architecture (02/03/04와 일치) |
01_plan.md 예시 (파일 맨 앞)---
issue_driven_dev:
source: subagent
phase: plan
subagent_type: generalPurpose
feature: "{feature-directory-name}"
---
02 / 03 / 04 예시 (각 파일 맨 앞)---
issue_driven_dev:
source: subagent
phase: review
subagent_type: code-reviewer
feature: "{feature-directory-name}"
review_kind: implementation
---
03은 subagent_type: security-reviewer, review_kind: security.
04는 subagent_type: code-reviewer, review_kind: architecture.
05_review_synthesis.md 예시 (파일 맨 앞)---
issue_driven_dev:
source: subagent
phase: synthesis
subagent_type: generalPurpose
feature: "{feature-directory-name}"
---
검증: PR·셀프체크 시 위 프론트 매터 존재 및 review_kind·파일명 일치를 확인하면, Subagent 생략 여부를 기계적으로 걸러내기 쉽다.
Issues/{issue-file}.md)docs/README.mdIssues/STATUS.md에서 해당 이슈 상태를 🔄 진행 중으로 변경.md 제외한 값)git checkout -b {feature-name}
Issues/{feature}/ 디렉토리 생성Issues/{feature}/00_issue.md로 복사Task 도구 사용 — 모델: claude-4.6-opus-max-thinking
subagent_type: "generalPurpose" 로 계획 수립 에이전트를 실행한다.
docs/README.md파일 첫 줄부터 검증 가능한 흔적의 01_plan.md YAML 블록을 두고, 이어서 본문을 작성한다.
---
issue_driven_dev:
source: subagent
phase: plan
subagent_type: generalPurpose
feature: "{feature-directory-name}"
---
# {Feature Name} — 개발 계획서
## 개발 범위
## 기술적 접근 방식
## TDD 구현 순서
각 단계는 아래 형식을 따른다:
### Step N: {기능 단위 설명}
**RED** — 실패하는 테스트 작성
- 테스트 파일: {경로}
- 테스트 케이스 목록
**GREEN** — 테스트를 통과하는 최소 구현
- 구현 파일: {경로}
- 핵심 구현 내용
**REFACTOR** — 코드 개선
- 리팩토링 대상 및 방향
## 파일 변경 계획
## 완료 조건
## 테스트 전략
Issues/{feature}/01_plan.md에 Write 도구로 작성한다. 내용은 계획 Task의 응답 전문이며, 금지 사항 및 게이트 및 검증 가능한 흔적을 만족해야 한다.
모델: 기본 모델 (auto) — Task 도구 사용 시 model 파라미터를 지정하지 않는다. 사용자가 별도로 모델을 명시한 경우에만 해당 모델을 사용한다.
01_plan.md를 읽고 TDD 순서에 따라 직접 구현한다.
각 Step마다:
npm test 실행 → 실패 확인npm test 실행 → 통과 확인npm test 실행 → 여전히 통과 확인모든 Step 완료 후 전체 테스트 실행하여 regression 없음을 확인한다.
3개의 Task를 동시에 실행한다. 반드시 하나의 메시지에서 3개의 Task 도구를 병렬 호출한다. 금지 사항 및 게이트를 위반하지 않는다.
각 리뷰 Task 프롬프트에 검증 가능한 흔적에 따라 해당 review_kind와 YAML 프론트 매터를 응답 맨 앞에 출력하도록 지시한다.
01_plan.md 전문git diff main 출력 (변경 내용 전체)git diff --name-only main 출력 (변경 파일 목록)subagent_type: code-reviewer.cursor/agents/implementation-reviewer.md의 시스템 프롬프트를 프롬프트에 포함Issues/{feature}/02_review_implementation.mdsubagent_type: security-reviewer.cursor/agents/security-reviewer.md의 시스템 프롬프트를 프롬프트에 포함Issues/{feature}/03_review_security.mdsubagent_type: code-reviewer.cursor/agents/architecture-reviewer.md의 시스템 프롬프트를 프롬프트에 포함Issues/{feature}/04_review_architecture.md3개 리뷰가 모두 완료된 후 실행한다. 금지 사항 및 게이트에 따라 메인 에이전트가 종합문을 직접 쓰지 않는다.
subagent_type: generalPurpose.cursor/agents/review-synthesizer.md의 시스템 프롬프트를 프롬프트에 포함02_review_implementation.md, 03_review_security.md, 04_review_architecture.md) 전문Issues/{feature}/05_review_synthesis.md — 검증 가능한 흔적의 05 YAML 블록으로 시작해야 한다. Task 프롬프트에 동일 형식을 요구한다.05_review_synthesis.md를 읽고 즉시 수정이 필요한 항목을 처리한다.
Issues/{feature}/06_fixes.md# 리뷰 반영 수정 기록
## 수정 항목
### 1. {이슈 제목}
- 심각도: {CRITICAL/HIGH/MEDIUM}
- 출처: {02/03/04 중 어떤 리뷰}
- 수정 내용: {변경 요약}
- 변경 파일: {파일 경로}
## 미수정 항목 (사유 포함)
## 수정 후 테스트 결과
아래 명령을 순서대로 실행한다. 하나라도 실패하면 수정 후 전체를 다시 실행한다.
npx tsc --noEmit # 타입 체크
npx eslint . # 린트
npx prettier --check . # 포매팅
npm test # 테스트
npm run build # 빌드
모든 검사가 통과할 때까지 반복한다.
Issues/{feature}/07_summary.md:
# {Feature Name} — 작업 요약
## 구현된 기능
## 주요 기술적 결정
## 테스트 커버리지
## 파일 변경 목록
## 알려진 제한 사항
## 다음 단계 (해당 시)
docs/ 하위 문서에 변경/추가 사항이 있으면 반영한다.
Issues/STATUS.md에서 해당 이슈를 ✅ 완료로 변경한다.
git add -A
git commit -m "{feature-name}: 구현 완료"
git checkout main
git merge {feature-name}
git push origin main
git branch -d {feature-name}