3-Agent 팀(Architect + Builder + Reviewer)으로 Claude 코딩 워크플로우 정리하기

Who Should Read

Claude Code나 Cursor로 복잡한 기능을 개발하다가 에이전트가 맥락을 잃거나 요청하지 않은 기능을 마음대로 추가하는 문제를 겪는 개발자. 멀티 에이전트 구조를 실제 코딩 워크플로우에 바로 도입하고 싶은 사람.

Core Mechanics

• 단일 에이전트에 모든 작업을 맡기면 컨텍스트가 비대해지면서 drift(의도 벗어남)와 hallucination이 늘어나는데, 역할 분리로 이를 해결.
• Architect는 요청을 분석해 구체적인 작업 브리프(brief)로 쪼개는 역할만 담당. 구현은 일절 하지 않음.
• Builder는 브리프에 적힌 것만 구현. '있으면 좋겠다' 싶은 기능을 임의로 추가하는 행동을 규칙으로 차단.
• Reviewer는 결과물이 브리프 요구사항을 충족하는지만 검토. 승인 없이는 다음 단계로 넘어가지 않음.
• 에이전트 간 인수인계(handoff)는 `handoff/` 폴더의 마크다운 파일로 처리. 불필요한 컨텍스트 재독을 막는 규칙이 내장되어 토큰 절감.
• Claude Code, Cursor, VS Code 등 어느 환경에서나, 어느 LLM과도 사용 가능. 30초 글로벌 설치 지원.

Evidence

• 단일 에이전트 대비 토큰 사용량이 '대폭(massive)' 감소한다고 저자가 명시. 구체적 수치는 논문에 없으나, 불필요한 컨텍스트 재독 차단 규칙이 직접적 원인.
• strict sequence(Architect→Builder→Reviewer 고정 순서) 적용 후 drift와 hallucination이 눈에 띄게 줄었다고 보고. 정량 수치는 미제공.

How to Apply

• 새 기능 개발 시 Architect 에이전트에게 요청사항을 넘기고 브리프 파일을 받은 뒤, Builder에게 그 파일만 주고 구현하게 하면 된다. '브리프에 없는 건 하지 말 것' 규칙을 시스템 프롬프트에 명시하는 게 핵심.
• Reviewer 에이전트에게는 브리프 파일과 구현 결과물만 제공하고 '브리프 기준으로만 판단할 것'을 지시. 코드 스타일이나 개인 선호로 범위를 벗어나지 않도록 제한.
• 에이전트 간 전달 내용은 `handoff/` 폴더의 마크다운 파일로 관리. 채팅 히스토리 전체를 넘기지 않으므로 다음 에이전트의 컨텍스트 창 낭비를 막을 수 있음.

Code Example

# handoff/brief.md 예시 (Architect → Builder)

## Task Brief
**Goal:** 사용자 프로필 수정 API 엔드포인트 추가

**Scope (이것만 구현):**
- `PATCH /api/users/:id` 엔드포인트
- 수정 가능 필드: name, bio (email 제외)
- 입력 유효성 검사 포함

**Out of Scope (절대 추가 금지):**
- 인증 미들웨어 변경
- 다른 엔드포인트 수정
- 리팩토링

**완료 기준:**
- 위 두 필드만 업데이트됨
- 잘못된 입력 시 400 반환
- 기존 테스트 통과

---
# Builder 시스템 프롬프트 예시
"brief.md에 명시된 것만 구현하라.
범위 밖 기능 추가, 리팩토링, 스타일 변경 금지.
완료 후 handoff/review-request.md에 변경 파일 목록 작성."

Terminology

관련 논문

• 프로덕션 AI 에이전트를 GPT-5.6으로 마이그레이션: 2.2배 빠르고 27% 저렴

  마케팅 웹사이트를 자동 생성하는 프로덕션 AI 에이전트를 Claude Opus 4.8에서 GPT-5.6 Sol로 전환한 실전 경험담으로, 단순 모델 교체가 아니라 eval 하네스, 툴 스키마, 캐싱, 추론 리플레이까지 손봐야 했던 과정을 구체적인 수치와 함께 정리했다.

• xAI Grok Build CLI가 xAI 서버로 전송하는 데이터: 네트워크 레벨 분석

  xAI의 공식 코딩 CLI 도구 Grok Build가 사용자 동의 없이 전체 Git 저장소와 .env 시크릿 파일을 xAI 서버로 업로드한다는 사실이 네트워크 트래픽 분석으로 밝혀졌다.

• 중요할 때 기억하라: Long-Horizon 에이전트를 위한 Proactive Memory Agent

  LLM 에이전트가 긴 작업 중 중요한 정보를 잊어버리는 문제를 별도의 메모리 에이전트가 '적절한 타이밍에' 끼어들어 해결하는 방법

• WebSwarm: 깊고 넓은 웹 검색을 위한 재귀적 Multi-Agent Orchestration

  복잡한 웹 검색을 재귀적으로 분해하고 각 노드에 적합한 검색 모드를 동적으로 할당하는 멀티에이전트 프레임워크

• 웹 앱을 리버스 엔지니어링해서 AI Agent 도구로 자동 변환하기

  로그인된 웹 앱의 API 호출을 브라우저에서 감시해 자동으로 MCP 도구로 변환하는 에이전트를 만들었다. 소스 코드나 공식 API 문서 없이도 Jira, Spotify 같은 서비스에 AI 어시스턴트를 붙일 수 있다.

• FableCut – AI 에이전트가 조작할 수 있는 브라우저 기반 비디오 에디터 (zero deps)

  타임라인 전체를 JSON 파일 하나로 표현하고 MCP/REST로 AI 에이전트가 직접 편집할 수 있는 브라우저 비디오 에디터로, Claude 같은 AI가 프롬프트 하나로 영상을 자동 컷편집하고 결과를 실시간으로 UI에 반영해준다.

Related Resources

• https://github.com/russelleNVy/three-man-team