subagents는 한 명의 에이전트에게 모든 걸 몰아주지 않고, 문제를 역할별로 나눠 처리하는 접근입니다. 하지만 모든 문제를 팀으로 풀 필요는 없습니다. 이 장은 언제 분리하고 언제 한 명으로 끝낼지 판단하는 감각을 복원합니다.
subagents가 빛나는 장면
- 조사와 구현을 병렬로 돌릴 때
- 리뷰와 구현을 분리해 판단을 선명하게 할 때
- 넓은 문제를 역할별로 나누는 편이 오류를 줄일 때
오히려 한 명이 나은 장면
- 작업 범위가 매우 좁을 때
- 파일 변경이 강하게 얽혀 있을 때
- 설정보다 실행이 더 빠른 상황일 때
실습 예시
mkdir -p .claude/agents
cp 04-subagents/*.md .claude/agents/
# Claude Code 안에서
# /review-pr위 흐름처럼 서브에이전트는 “역할을 분리하면 더 빨라지는 문제”에 붙일 때 가장 좋습니다. 너무 작은 문제까지 팀으로 나누면 오히려 비용이 커집니다.
팀으로 묶는 대표 흐름
1메인 에이전트가 문제를 읽습니다.
2조사, 구현, 리뷰 같은 하위 역할을 분리합니다.
3필요할 때만 병렬로 돌리고, 결과를 합쳐 결론을 냅니다.
팀이 정답이 아니라, 팀이 필요한 문제만 팀으로 풀어야 합니다
학습 목적에서는 “언제 나눌 것인가”를 아는 것이 “무조건 나눈다”보다 더 중요합니다.
예시 워크플로
- Complete Code Review Workflow: 메인 에이전트가 PR을 읽고, 코드리뷰 서브에이전트와 테스트 서브에이전트로 나눠 검토합니다.
- Automated Documentation: 메모리와 문서 작성 서브에이전트를 결합해 API 문서를 자동 생성합니다.
- DevOps Deployment: 플러그인과 MCP, hooks를 함께 써서 배포 전후 검증 흐름을 구성합니다.
원본 출발점은 luongnv89/claude-howto이며, 역할 분리와 협업 흐름을 다시 살리는 방향으로 재편집했습니다.