Claude Code Subagents 패턴 — 멀티 에이전트 개발 워크플로 6개월 운영기

핵심 요약

Claude Code의 subagent(Explore, Plan, general-purpose, security-review 등)를 main 세션에서 분리 호출하면 컨텍스트 윈도우 오염을 막고 정확도를 끌어올린다. 6개월간 12명 팀에서 운영한 결과 토큰 비용 38% 절감, 첫 시도 PR 통과율 12%p 상승. 단, 위임 비용·전달 손실·디버깅 난이도가 새 문제로 등장한다.

1. Subagent가 뭔가

Claude Code의 Task 도구로 호출하는 격리된 Claude 인스턴스. 별도 컨텍스트 윈도우를 갖고 결과만 main에 반환한다. 핵심은 컨텍스트 격리: main 세션은 grep 결과 수천 줄, 파일 읽기 로그를 보지 않고 요약만 받는다.

# .claude/agents/code-explorer.md
---
name: code-explorer
description: 코드베이스 탐색 전담. 파일 구조, 의존성, 호출 그래프 파악 후 요약 반환.
tools: Read, Grep, Glob, Bash
---

너는 코드 탐색 전문가다. 사용자의 질문에 답하기 위해
필요한 파일을 모두 읽고, 핵심 발견만 5~10줄로 요약해라.
파일 경로는 절대경로로, 라인 번호 포함.

2. 6개월 운영 데이터

3. 언제 위임하나 — 위임해도 되는 작업

• 광범위 탐색: "이 기능이 어디서 호출되나" — grep 50번 돌아도 main은 5줄 요약만 본다
• 독립 검증: 보안 리뷰, 테스트 작성, 문서 생성 — 결과물이 독립적
• 병렬 가능 작업: 5개 모듈 동시 분석 — main에서 Task 5개 동시 호출
• 대량 파일 읽기: 100개 파일 훑어 패턴 찾기

4. 언제 위임하면 안 되나

• 대화 맥락이 필요한 수정: "방금 만든 그 함수 수정해" — subagent는 방금이 뭔지 모른다
• 점진적 디버깅: 출력 보고 다음 가설 세우는 루프 — 왕복 비용이 손해
• 짧은 단일 파일 작업: 위임 오버헤드(~7초)가 작업보다 큼
• 사용자 확인이 필요한 결정: subagent는 사용자와 대화 못함

5. 우리 팀 표준 agents 6개

.claude/agents/
├── explorer.md        # 코드베이스 탐색·요약
├── planner.md         # 큰 작업 분해, 파일 단위 계획
├── reviewer.md        # PR diff 리뷰, 보안·성능 체크
├── test-writer.md     # 기존 코드 보고 테스트 생성
├── doc-writer.md      # API 문서, README 갱신
└── migration.md       # 일괄 변환 (예: enzyme → testing-library)

각 agent는 200~400줄 시스템 프롬프트. 도구 권한도 최소화 — reviewer는 Write 금지, migration은 git commit 금지.

6. 안티패턴 — 빠진 함정들

7. 병렬 위임 — 5배 빠른 코드베이스 분석

# 5개 모듈 동시 탐색 — 한 메시지에 Task 5번
[
  Task(explorer, "auth 모듈 분석"),
  Task(explorer, "payment 모듈 분석"),
  Task(explorer, "notification 모듈 분석"),
  Task(explorer, "admin 모듈 분석"),
  Task(explorer, "api-gateway 모듈 분석"),
]
# 순차: 14분 → 병렬: 2분 50초

8. 결정 가이드

참고

• docs.claude.com/claude-code/subagents
• github.com/anthropics/claude-code-cookbook