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

관련 논문

• ctx – 로컬 머신의 코딩 에이전트 히스토리를 검색하는 CLI 도구

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Model API 내부 협업으로 Frontier 모델을 이기는 방법 (vLLM Semantic Router)

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: 에이전틱 코딩을 위한 자기 개선형 오픈소스 모델

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Tool-Augmented Agent에서의 Entity Binding 실패 분석

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: 터미널에서 여러 AI Agent를 한 번에 관리하는 Agent Multiplexer

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: 스스로 Scaffold를 생성하는 Agentic Coding LLM

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

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