Claude Code 멀티 에이전트 워크플로: 역할 분리, 격리, 수동 검토
역할 분리, Git worktree 격리, 인수인계 카드, 수동 승인으로 Claude Code 멀티 에이전트 워크플로를 구성하는 실무 가이드입니다.
코드를 자동으로 병합하는 완전 자율형 “AI 에이전트 팀”을 만들면 미묘한 아키텍처 결함, 순환적인 리팩터링 루프, 코드베이스 품질 저하가 생기기 쉽습니다. 병렬로 실행되는 두 에이전트가 독립적인 사실 기준을 만들어 주지는 않습니다. 작성 에이전트가 논리 오류를 내면 비슷한 프롬프트 기반에서 작동하는 검토 에이전트도 그 오류를 놓칠 수 있습니다.
신뢰할 수 있는 멀티 에이전트 워크플로는 완전 자율성이라는 환상이 아니라 엄격한 역할 분리에 기반합니다. 구현을 맡는 Author, 독립적으로 검증하는 Reviewer, 그리고 최종 병합을 결정하는 사람 개발자입니다.
1. 역할 경계: Author, Reviewer, 사람 의사결정자
효율적인 개발 워크플로에서는 각 참여자에게 닫혀 있고 명확한 책임 범위가 있습니다.
2. 컨텍스트와 워크스페이스 격리
Author와 Reviewer를 같은 작업 디렉터리나 같은 대화 스레드에서 실행하지 마세요. 다음 세 가지 운영 수준에서 분리해야 합니다.
- 세션 컨텍스트: 독립된 대화 스레드는 상호 환각과 순환적 확인을 줄입니다.
- 파일 시스템 격리: 별도의 Git worktree를 사용하면 Reviewer는 더티 작업 상태가 아니라 확정된 diff만 검토할 수 있습니다.
- 환경 보안: API 키와 런타임 자격 증명은 환경 변수에 남겨 두고 프롬프트 텍스트로 전달하지 않습니다.
worktree 준비 명령
[!IMPORTANT]
API 구성: 각 Claude Code 세션은 운영체제 환경 변수로 설정한 전용 API 자격 증명을 사용합니다. 현재 설정 절차는 BetterToken Claude Code 문서에서 확인하세요.
3. 구조화된 인수인계 계약
Author 에이전트가 구현을 마치면 간결한 인수인계 카드를 만듭니다. 원본 채팅 기록, 비밀 정보, 검증되지 않은 가정은 엄격히 제외합니다.
Handoff Card
- Task: Add HTTP 429 retry support in payment client with exponential backoff.
- Branch:
feat/payment-retry - Changed Files:
src/client/http.ts,tests/http-retry.test.ts - Verification Command:
npm test -- tests/http-retry.test.ts(Passed) - Risks & Blockers: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- Next Step: Reviewer agent validates Retry-After header handling.
4. 사람의 최종 승인을 위한 프로토콜
Reviewer 에이전트는 격리된 환경에서 평가를 수행합니다.
- 깨끗한 worktree
../agent-reviewer로 이동합니다. - 기록된 검증 명령을 실행합니다.
- 부작용과 엣지 케이스를 찾기 위해 독립적으로 diff를 검사합니다.
- 담당 엔지니어를 위한 구조화된 요약을 작성합니다.
최종 승인은 엔지니어가 수행합니다.
- Reviewer의 발견 사항을 검토합니다.
main대비 회귀가 없음을 확인합니다.- 수동으로 병합합니다:
git merge feat/payment-retry.
이 파이프라인은 상호 확인 루프를 막고, 품질과 아키텍처에 대한 책임을 개발자에게 남겨 둡니다.