서브 에이전트로 작업을 오케스트레이션 하기

2026. 3. 2.

이 문서는 메인 에이전트가 직접 구현하지 않고 전문 서브 에이전트들을 단계별로 위임·통제하여 기획부터 개발, 리뷰, QA까지 수행하는 에이전트 오케스트레이션 워크플로우를 정리한 내용입니다.

오케스트레이션 규칙

핵심 원칙

메인 에이전트는 직접 코드를 작성하거나 파일을 수정하지 않는다.
모든 작업은 반드시 전문 서브 에이전트에게 위임한다.
에이전트 간 정보 전달은 파일(마크다운)을 통해서만 이루어진다.
사용자 승인이 필요한 단계에서는 반드시 승인을 받은 후 진행한다.

산출물 경로 컨벤션

산출물	경로	작성 에이전트
기획 명세서	`docs/specs/{기능명}-spec.md`	planner
유저 테스트 케이스	`docs/test-cases/{기능명}-tc.md`	planner
코드 리뷰 결과	`docs/reviews/{기능명}-review.md`	code-reviewer
QA 결과	`docs/qa/{기능명}-qa-result.md`	qa-tester

실제 파일 구조

Code

📦docs
 ┣ 📂qa
 ┃ ┣ 📂screenshots
 ┃ ┃ ┗ 📂control-cooldown
 ┃ ┃ ┃ ┣ 📜tc-001-initial.png
 ┃ ┃ ┃ ┣ 📜tc-002-initial.png
 ┃ ┃ ┃ ┣ 📜tc-003-initial.png
 ┃ ┃ ┃ ┣ 📜tc-004-initial.png
 ┃ ┃ ┃ ┣ 📜tc-control-leaf-noauth.png
 ┃ ┃ ┃ ┗ 📜tc-initial.png
 ┃ ┗ 📜control-cooldown-qa-result.md
 ┣ 📂reviews
 ┃ ┗ 📜control-cooldown-review.md
 ┣ 📂specs
 ┃ ┗ 📜control-cooldown-spec.md
 ┣ 📂test-cases
 ┃ ┗ 📜control-cooldown-tc.md

워크플로우

Phase 0: 요구사항 정제 (메인 에이전트가 직접 수행)

아래 항목 중 2개 이상 불명확하면 사용자에게 질문한다.
1. 어떤 화면/페이지에 적용되는 기능인지
2. 사용자가 기대하는 동작 흐름 (인터랙션)
3. 기존 기능과의 관계 (신규/수정/확장)
모두 명확하면 바로 Phase 1로 진행한다.
질문은 최대 3개까지만 한다.

Phase 0.5: 프로젝트 구조 확인 (메인 에이전트가 직접 수행)

CLAUDE.md의 "프로젝트 구조" 섹션이 존재하고 내용이 채워져 있는지 확인한다.
비어있으면 사용자에게 "프로젝트 탐색을 먼저 진행해주세요"라고 안내하고 워크플로우를 중단한다.
채워져 있으면 Phase 1로 진행한다.

Phase 1: 기획 (planner 에이전트)

입력: 정제된 사용자 요구사항 + CLAUDE.md의 프로젝트 구조 정보
산출물: docs/specs/{기능명}-spec.md, docs/test-cases/{기능명}-tc.md
사용자 승인 필수: 명세서 작성 후 메인 에이전트가 사용자에게 검토를 요청한다.
피드백 반영 시 planner를 재호출한다. 재호출 시 반드시 아래 정보를 전달한다.
1. 현재 명세서 파일 경로
2. 현재 테스트 케이스 파일 경로
3. 사용자 피드백 원문
4. "기존 문서를 수정하라"는 명시적 지시
사용자가 승인할 때까지 Phase 2로 진행하지 않는다.

Phase 2: 개발 (frontend-developer 에이전트)

입력: 승인된 기획 명세서 파일 경로 (docs/specs/{기능명}-spec.md)
산출물: 구현된 코드
CLAUDE.md의 프로젝트 구조를 참고하여 기존 코드 컨벤션을 따른다.

Phase 3: 코드 리뷰 (code-reviewer 에이전트)

입력: git diff (Phase 2에서 변경된 파일들)
산출물: docs/reviews/{기능명}-review.md

Phase 4: 리뷰 반영 (frontend-developer 에이전트)

입력: 코드 리뷰 결과 파일 경로 (docs/reviews/{기능명}-review.md)
개발자가 리뷰 항목을 검토하여 수정하거나 근거와 함께 유지한다.
리뷰 사이클은 최대 2회로 제한한다.
- 1차: code-reviewer 리뷰 → frontend-developer 반영
- 2차: code-reviewer 재리뷰 → Critical 이슈만 반영
- 2차 이후에도 Critical 이슈가 남아있으면 사용자에게 판단을 요청한다.

Phase 5: QA (qa-tester 에이전트)

입력: 유저 테스트 케이스 파일 경로 (docs/test-cases/{기능명}-tc.md)
산출물: docs/qa/{기능명}-qa-result.md
QA 실패 시:
1. qa-tester가 실패 리포트를 작성한다.
2. frontend-developer가 실패 항목을 수정한다.
3. qa-tester가 실패했던 항목만 재검증한다.
4. QA 사이클은 최대 3회로 제한한다.
5. 3회 초과 시 사용자에게 판단을 요청한다.