Claude Code Subagent_case-study

Claude Code Subagent의 개념을 MyApp 모노레포(App + Web + Server)에 실제 적용한 설계 사례. 기획서를 입력하면 플랫폼별 개발 문서를 자동 생성하는 Skill + Agent 하이브리드 시스템을 설계한다.

해당 개념이 필요한 이유

• 기획서 작성 후 3개 플랫폼에 각각 개발 문서를 수작업으로 만드는 반복 비용 제거
• 각 플랫폼의 코드베이스가 크기 때문에 (App 171파일, Web 128파일) 컨텍스트 격리 필수
• 문서 포맷 일관성 보장을 위한 자동 검증 레이어 필요
• 사용자는 기획서만 작성하고, 리뷰에만 집중하는 워크플로우 자동화

AS-IS

sequenceDiagram
    autonumber
    actor User
    participant Main as Claude Code (Main)

    User->>Main: "recurring-todo 개발 문서 만들어"
    Main->>Main: app/CLAUDE.md 읽기 (577줄)
    Main->>Main: app/lib/ 탐색 (171파일)
    Main->>Main: App overview 생성
    Note over Main: ⚠️ 컨텍스트 오염 시작

    Main->>Main: web/CLAUDE.md 읽기
    Main->>Main: web/src/ 탐색 (128파일)
    Main->>Main: Web overview 생성
    Note over Main: ⚠️ 컨텍스트 포화<br/>App 탐색 결과가 밀려남

    Main->>Main: server/ 탐색
    Note over Main: ❌ 컨텍스트 한계<br/>이전 문서 품질 저하
    Main-->>User: 불완전한 문서 3개

TO-BE

sequenceDiagram
    autonumber
    actor User
    participant Skill as dev-doc-generator<br/>(Skill)
    participant AW as app-doc-writer<br/>(Agent)
    participant WW as web-doc-writer<br/>(Agent)
    participant SW as server-doc-writer<br/>(Agent)
    participant V as design-verifier<br/>(Agent)

    User->>Skill: /dev-doc-generator recurring-todo.md

    par 3개 Agent 병렬 호출
        Skill->>AW: 기획서 + "App overview 작성"
        Skill->>WW: 기획서 + "Web overview 작성"
        Skill->>SW: 기획서 + "Server overview 작성"
    end

    Note over AW: 독립 컨텍스트에서<br/>171파일 탐색
    Note over WW: 독립 컨텍스트에서<br/>128파일 탐색
    Note over SW: 독립 컨텍스트에서<br/>서버 탐색

    AW-->>Skill: app-overview.md
    WW-->>Skill: web-overview.md
    SW-->>Skill: server-overview.md

    Skill->>V: 기획서 vs 3개 문서 검증
    V-->>Skill: PASS

    Skill->>User: "확인해주세요"
    Note over Skill: ✅ 컨텍스트 깨끗<br/>요약만 남음

Agent 분리 기준 적용 과정

Claude Code Subagent에서 정의한 4가지 판단 질문을 실제로 적용:

질문	app-doc-writer	web-doc-writer	server-doc-writer	design-verifier
자기완결적?	YES (기획서+코드→문서)	YES	YES	YES (기획서+문서→판정)
도구 제한?	Read/Glob/Grep/Write	동일	동일	Read-only
대량 출력?	YES (171파일 탐색)	YES (128파일)	YES (확장 대비)	NO
도메인 특화?	YES (App 아키텍처)	YES (Redux+TS)	YES (Supabase)	YES (품질 기준)

설계 시 내린 주요 결정 3가지

결정 1: server-doc-writer를 Agent로 분리할 것인가?

• Architect 의견: Server는 7개 파일뿐이므로 Skill 내부 처리 추천
• 사용자 결정: 3개 플랫폼 동일 구조로 유지 (일관성 + 확장성 우선)
• 근거: Server 코드가 향후 성장할 가능성 + 병렬 호출의 일관된 패턴

결정 2: 검증 레이어를 어떻게 구현할 것인가?

3가지 방안 중 하이브리드 (방안 C) 선택:

검증 유형	담당	이유
포맷 검증 (필수 섹션, heading 구조)	Skill 내부	단순 규칙, Agent 오버헤드 불필요
설계 품질 검증 (기획서 반영도, 일관성)	design-verifier Agent	복잡한 판단, 도메인 지식 필요

결정 3: 오케스트레이터를 Agent가 아닌 Skill로

오케스트레이터가 해야 할 일	Agent	Skill
사용자에게 질문	❌	✅
다른 Agent 호출	❌ (Agent→Agent 불가)	✅
여러 결과 취합/조율	❌	✅

→ 공식 제약상 오케스트레이터 = 반드시 Skill

파일 배치

myapp/
├── .claude/
│   ├── agents/                    ← Agent 정의 (4개)
│   │   ├── app-doc-writer.md
│   │   ├── web-doc-writer.md
│   │   ├── server-doc-writer.md
│   │   └── design-verifier.md
│   └── skills/                    ← Skill 정의 (1개)
│       └── dev-doc-generator/
│           ├── SKILL.md
│           └── templates/
│
├── docs/
│   ├── plan.md                    ← 최상위 인덱스
│   └── recurring-todo.md          ← 기획문서
│
├── app/docs/recurring-todo/       ← 생성된 문서
│   ├── overview.md
│   └── phase1.md ...
├── web/docs/recurring-todo/
│   ├── overview.md
│   └── phase1.md ...
└── server/docs/recurring-todo/
    ├── overview.md
    └── phase1.md ...

전체 Flow (6 Phase)

Phase	담당	내용
1. 입력 수집	Skill	기획서 파싱, 플랫폼 선택, 기능명 확인
2. overview 생성	Writer Agent x3 (병렬)	각 플랫폼 코드베이스 분석 + overview.md 작성
3. 검증	Skill (포맷) + Verifier Agent (품질)	실패 시 Writer 재호출, 2회 초과 시 사용자 판단
4. 사용자 확인	Skill	플랫폼별 순차 확인, 경미한 수정은 Skill 직접 Edit
5. phase별 문서	Writer Agent	승인된 overview 기반 phaseN.md 생성 + 검증 + 확인 반복
6. 파일화 + 연결	Skill	각 플랫폼 docs/에 저장, 링크 연결, plan.md 업데이트

참고 문서

• Claude Code Subagent - Agent 분리 기준, Skill vs Agent 판단 기준
• Claude Code Subagents 공식 문서
• Claude Code Skills 공식 문서