SubAgent(서브 에이전트) 상세 구조

스킬과 서브 에이전트의 차이

스킬과 서브 에이전트는 명확히 다른 역할을 한다.

구분	Skill	SubAgent
비유	문서 양식	담당자/전문가
역할	"이 형식대로 쓰세요"	"이 양식을 쓸 줄 아는 사람"
파일	skills/{name}/SKILL.md	agents/{name}.md
결과	10년차 PM이 쓴 PRD ≠ 신입이 쓴 PRD	전문가 페르소나가 결과 품질을 높임

서브 에이전트를 쓰는 이유: 컨텍스트 관리

서브 에이전트의 가장 큰 장점은 메인 컨텍스트를 차지하지 않는다는 것이다.

서브 에이전트는 각각 별도의 컨텍스트를 받는다. 메인 컨텍스트에는 최종 결과만 간략히 전달되므로, 메인이 오염되지 않고 깨끗하게 유지된다.

에이전트 파일 구조

서브 에이전트는 .claude/agents/{이름}.md 파일로 정의한다. 최신 Claude Code 기준으로는 name, description, tools가 핵심이고, 역할과 작업 규칙은 본문에 자연어로 적는 방식이 기본이다.

핵심: description과 tools

description 은 언제 이 서브 에이전트를 호출할지를 결정하는 핵심 설명이고, tools 는 어떤 도구까지 사용할 수 있는지를 제한한다.

특정 스킬이나 템플릿을 함께 쓰고 싶다면, 공식 frontmatter 필드로 강제하기보다 본문 규칙에서 "어떤 스킬을 참고해 어떤 형식으로 작성할지"를 명시하는 편이 안전하다.

4개 핵심 에이전트

1. Planner (기획 전문가)

항목	내용
페르소나	10년차 PM, 요구사항 분석 전문가
스킬	PRDWriter
색상	Blue (파란색)
역할	사용자와 대화하며 요구사항 수집 → PRD 작성
특징	질문을 통해 타겟 사용자, 기술 스택, MVP 범위 등을 파악

2. Architect (기술 설계 전문가)

항목	내용
페르소나	시스템 아키텍트, 기술 설계 전문가
스킬	TechSpecWriter
색상	Purple (보라색)
전제 조건	PRD가 없으면 작업을 진행하지 않음
역할	PRD를 읽고 기술 스택 결정, API 설계, 파일 구조 설계

3. Developer (코드 구현 전문가)

항목	내용
페르소나	시니어 풀스택 개발자
스킬	CodeGenerator
색상	Green (초록색)
전제 조건	PRD + Tech Spec 모두 필요
작업 방식	Tech Spec에 명시된 파일 경로, 함수명을 그대로 사용. 점진적 구현

4. Reviewer (품질 검증 전문가)

항목	내용
페르소나	QA 엔지니어, 품질 검증 전문가
스킬	SpecValidator
색상	Yellow (노란색)
전제 조건	모든 문서 필요 (PRD + Spec + 코드)
검증 방식	PRD, Spec, 코드 3중 대조

에이전트 병렬 실행

최신 Claude Code에서는 서브 에이전트를 병렬 실행해 작업을 나눌 수 있다. 예를 들어, 컴포넌트가 많을 때 Developer가 3개의 에이전트를 동시에 실행하여 각각 다른 컴포넌트를 구현한다.

이렇게 병렬로 진행하면 각 서브 에이전트가 별도 컨텍스트를 사용하므로, 메인 컨텍스트 오염 없이 대규모 작업을 수행할 수 있다.