10-subagent-patterns Subagent 활용 패턴

왜 Subagent인가

메인 세션에서 탐색·분석 작업을 수행하면 컨텍스트 윈도우를 소비한다. Context 70% 초과 시 정밀도 저하, 85% 초과 시 할루시네이션 증가 (리서치 기반).

Subagent는 독립 컨텍스트로 실행되어 메인 세션을 오염시키지 않는다.

핵심 패턴: 탐색은 Subagent, 구현은 메인

탐색 작업(파일 읽기, 검색, 분석)을 메인에서 직접 하지 않고 Subagent에 위임 → 결과 요약만 메인으로 수신.

위임 적합 작업:

프로젝트 전체 구조 분석
의존성 관계 조사
기존 패턴 코드베이스 검색 (API 엔드포인트 목록, 컴포넌트 목록 등)
보안 취약점 스캔
대규모 리뷰 (PR 전체 검토)

메인 세션에서 직접 실행:

코드 구현 및 수정
커밋, push
사용자와의 대화

Subagent 권한 제한 설계 (운영 철학)

각 에이전트는 역할에 필요한 최소 권한만 가진다.

에이전트	허용 도구	금지 도구	모델
`planner`	Read, Glob, Grep, WebSearch	Edit, Write, Bash	기본
`builder`	전체	—	기본
`investigator`	Read, Glob, Grep, Bash	Edit, Write	기본
`reviewer`	Read, Glob, Grep	Edit, Write, Bash	claude-opus-4-6 (정밀도 중요)
`qa`	Read, Glob, Grep, Bash	Edit, Write	기본
`security`	Read, Glob, Grep	Edit, Write, Bash	claude-opus-4-6

왜 권한 제한인가:

investigator가 Edit 권한을 가지면 "진단하다가 수정"하는 역할 혼선 발생 — Iron Law 위반
reviewer가 Edit 권한을 가지면 "리뷰하다가 수정"하는 역할 혼선 발생
security가 Bash를 가지면 취약점 발견 시 임의로 패치 시도 가능
planner가 Write 권한을 가지면 계획 단계에서 코드 생성 시작

Subagent 정의 포맷 (.claude/agents/)

파일 위치: .claude/agents/{agent-name}.md

---
name: reviewer
description: PR 생성 전 코드 리뷰 에이전트. 수정 없이 읽기와 분석만 수행.
  코드 품질, 규칙 준수, 보안 이슈를 검토하고 리뷰 코멘트를 반환한다.
model: claude-opus-4-6
tools: Read, Glob, Grep
---

## 역할

PR 생성 전 코드 리뷰 전문 에이전트.
수정은 하지 않는다 — 발견 사항만 보고한다.

## 리뷰 체크리스트

- [ ] 02-code Hard Bans 위반 여부
- [ ] 03-security STRIDE 항목
- [ ] API 시그니처 변경 시 하위 호환성
- [ ] 테스트 커버리지 적절성

base agent → .claude/agents/ 전환 계획

현재 agents/base-*.md 파일들은 Claude Code 공식 subagent 포맷이 아님. YAML frontmatter 추가로 실제 실행 가능한 subagent로 전환:

현재 파일	전환 후	권한 변경 사항
`agents/base-planner.md`	`name: planner`, `tools: Read,Glob,Grep,WebSearch`	Write/Edit 제거
`agents/base-builder.md`	`name: builder`, tools: 전체	변경 없음
`agents/base-reviewer.md`	`name: reviewer`, `model: claude-opus-4-6`, `tools: Read,Glob,Grep`	Edit/Bash 제거
`agents/base-qa.md`	`name: qa`, `tools: Read,Glob,Grep,Bash`	Edit/Write 제거
`agents/base-security.md`	`name: security`, `model: claude-opus-4-6`, `tools: Read,Glob,Grep`	Edit/Write/Bash 제거

adapters/claude-code.mjs에서 프로젝트별 .claude/agents/ 출력 시 frontmatter 포함하도록 수정 예정 (Phase 3).

Teammate 패턴 (병렬 독립 작업)

Subagent는 메인 에이전트에만 보고하지만, Teammate는 서로 직접 메시지 가능한 독립 에이전트다.

구분	Subagent	Teammate
통신 방향	메인 에이전트에만 보고	서로 직접 메시지 가능
컨텍스트	독립	독립
적합 작업	순차 위임 (탐색→결과)	병렬 독립 작업

Teammate 사용 기준:

프론트엔드 구현 + 백엔드 구현을 동시에 진행할 때
두 작업이 서로 결과를 기다릴 필요가 없고 독립적일 때
각자 완료 후 메인 에이전트에게 결과 보고

# Teammate 패턴 예시
메인: "프론트 teammate + 백엔드 teammate 동시 소환"
  └─ frontend-builder teammate: UI 컴포넌트 구현
  └─ backend-builder teammate: API 엔드포인트 구현
  └─ (둘 다 완료 후) 메인: 통합 검증

Context Budget 가이드라인

상황	권장 행동
탐색할 파일 5개 이하	메인 세션에서 직접 읽기
탐색할 파일 6개 이상	Subagent에 위임
대화 30턴 초과	세션 파일 HANDOFF 작성 → 새 세션
응답 속도 저하 감지	즉시 세션 파일 HANDOFF 작성 → 새 세션 요청
리뷰 대상 파일 3개 이상	reviewer subagent에 위임