Claude Code Subagents로 탐색·구현·리뷰 작업을 역할별로 나누는 방법

하나의 대화에서 코드 탐색, 구현, 리뷰를 모두 진행하면 앞 단계에서 읽은 파일 내용이 컨텍스트를 채워 뒤 단계의 판단이 흐려지기 쉽다. Claude Code Subagents 문서는 각 Subagent가 자체 컨텍스트 창, 시스템 프롬프트, 도구 권한을 갖고 일한 뒤 요약만 돌려준다고 설명한다. 이 성질을 이용해 역할을 나누면 본 대화에는 결정에 필요한 결과만 남는다. 역할 분리 설계의 일반 원리는 Orchestrator와 Worker 패턴 글에서 다뤘고, 이 글은 Claude Code에서의 구체적인 설정 방법에 집중한다.

역할을 나누기 전에 정할 세 가지

역할	주 작업	허용 도구	산출물
탐색(explorer)	관련 파일과 호출 흐름 찾기	Read, Grep, Glob	파일 목록과 흐름 요약
구현(implementer)	합의된 계획대로 코드 수정	Read, Edit, Write, Bash	변경 diff와 테스트 결과
리뷰(reviewer)	변경의 위험 요소 찾기	Read, Grep, Glob, Bash(git diff)	문제 목록(파일·줄·위험도)

역할마다 도구를 다르게 주는 이유는 실수의 범위를 줄이기 위해서다. 리뷰 에이전트가 수정 권한을 가지면 문제를 보고하는 대신 직접 고쳐 버려, 사람이 무엇이 바뀌었는지 놓칠 수 있다. 기본 제공 Explore 에이전트도 읽기 전용이라 탐색 역할은 별도 정의 없이 시작할 수 있다.

1단계: 에이전트 파일 작성하기

프로젝트 전용 에이전트는 .claude/agents/에, 모든 프로젝트에서 쓸 에이전트는 ~/.claude/agents/에 둔다. 같은 이름이 있으면 프로젝트 쪽이 우선한다. 필수 필드는 name과 description이며, 모델은 description을 보고 언제 위임할지 판단한다.

---
name: implementer
description: 승인된 계획에 따라 지정된 파일만 수정하고 관련 테스트를 실행한다. 계획이 확정된 뒤 구현 단계에서 사용.
tools: Read, Edit, Write, Bash
model: inherit
maxTurns: 30
isolation: worktree
---

너는 구현 담당이다. 다음 규칙을 지킨다.
1. 위임 메시지에 적힌 파일 외에는 수정하지 않는다.
2. 수정 후 해당 모듈의 테스트만 실행하고 결과를 그대로 보고한다.
3. 계획과 다른 판단이 필요하면 수정하지 말고 이유를 보고한다.

---
name: reviewer
description: 현재 브랜치의 변경을 읽기 전용으로 검토해 권한 누락, 경계값, 시그니처 변경을 찾는다. 구현 직후 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
---

git diff로 변경 범위를 확인하고, 문제를 표(파일, 줄, 위험도, 근거)로만 보고한다.
코드를 수정하지 않는다.

isolation: worktree를 두면 해당 에이전트가 임시 git worktree에서 작업해 본 작업 디렉터리와 파일 충돌이 생기지 않는다. 변경 없이 끝나면 worktree는 자동으로 정리된다고 worktree 문서에 나와 있다. maxTurns는 에이전트가 끝없이 반복하지 않도록 상한을 거는 필드다.

2단계: 위임 요청 문장을 구체적으로 쓰기

Subagent는 본 대화의 기록을 받지 않는다. 문서에 따르면 시작 시 받는 것은 시스템 프롬프트, 위임 메시지, CLAUDE.md, git 상태 스냅샷, 미리 지정한 Skill 정도다. 따라서 위임 메시지에 필요한 맥락을 모두 담아야 한다.

explorer 에이전트로 다음을 조사해 줘.
- 목표: 주문 취소 API가 재고를 복구하는 경로 찾기
- 범위: src/orders, src/inventory 폴더만
- 보고 형식: 호출 순서(파일:함수), 트랜잭션 경계, 테스트 파일 위치
- 하지 말 것: 코드 수정, 범위 밖 폴더 탐색

탐색 결과를 받은 뒤 본 대화에서 계획을 확정하고, 그 계획 문장을 그대로 implementer 위임 메시지에 붙인다. 이렇게 하면 구현 에이전트는 탐색 과정의 시행착오 없이 확정된 내용만 받는다.

3단계: 탐색 → 구현 → 리뷰 순서로 실행하기

1. 탐색: explorer(또는 기본 Explore)에 범위와 보고 형식을 지정해 위임한다.
2. 계획 확정: 본 대화에서 사람이 계획을 검토한다. 이 단계는 위임하지 않는다.
3. 구현: implementer에 계획과 수정 대상 파일을 넘긴다. worktree에서 작업하므로 결과 브랜치를 확인한다.
4. 리뷰: reviewer에 변경 브랜치를 검토시키고, 나온 문제 목록을 다시 implementer에 넘겨 수정한다.
5. 병합: 사람이 diff와 테스트 결과를 보고 병합 여부를 결정한다.

큰 변경이라면 리뷰 단계의 결과를 스택 PR 워크플로우로 나눠 올리면 사람이 검토하기 쉬운 크기가 된다.

역할 분리가 실패하는 신호와 대응

신호	원인	대응
에이전트가 위임되지 않음	description이 모호하거나 요청과 맞지 않음	"언제 사용"을 description에 명시하거나 에이전트 이름을 직접 지정
구현 에이전트가 범위 밖 파일 수정	위임 메시지에 범위가 없음	수정 대상 파일 목록과 금지 범위를 메시지에 포함
리뷰 결과가 매번 다름	검토 기준이 시스템 프롬프트에 없음	검토 항목과 보고 형식을 표로 고정
에이전트가 멈추지 않음	종료 조건 없음	maxTurns 설정과 완료 조건 명시

Subagent가 또 다른 Subagent를 부르는 중첩은 기본 3단계까지 허용된다. 역할 분리 목적이라면 중첩이 오히려 추적을 어렵게 하므로, CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 1로 설정해 막아 두는 것도 방법이다.

역할 분리에 쓰는 frontmatter 필드 정리

필드	용도	역할 분리에서의 쓰임
tools / disallowedTools	허용·차단 도구 목록	리뷰·탐색 에이전트에서 Edit, Write 제거
model	sonnet, opus, haiku, inherit 등	탐색은 빠른 모델, 설계 판단은 상위 모델
permissionMode	plan, acceptEdits 등	리뷰 에이전트를 계획 모드로 고정
maxTurns	최대 반복 횟수	끝나지 않는 구현 루프 방지
skills	시작 시 미리 불러올 Skill	리뷰 체크리스트 Skill을 리뷰 에이전트에 연결
isolation	worktree 지정 시 임시 worktree에서 실행	구현 에이전트의 파일 충돌 방지

필드를 많이 쓸수록 동작이 예측 가능해지지만, 처음에는 tools, model, maxTurns 세 가지만으로 시작하고 문제가 생긴 지점에 맞춰 필드를 늘려 가는 방식이 관리하기 쉽다. 에이전트 파일도 코드처럼 저장소에 커밋해 팀이 같은 역할 정의를 쓰게 한다.