Root CLAUDE.md가 하위 Agent의 CLAUDE.md를 불러와 스킬을 실행하는 구조입니다. 이 패턴을 적용하면 Agent별 독립적인 스킬 관리가 가능합니다.
Root CLAUDE.md가 하위 Agent의 CLAUDE.md를 불러와 스킬을 실행하는 구조입니다. 이 패턴을 적용하면 Agent별 독립적인 스킬 관리가 가능합니다.
| 용어 | 정의 |
|---|---|
| Claude Code | 사용자의 자연어 지시를 해석하고 실행하는 AI 도구 (행위자) |
| CLAUDE.md | Claude Code가 참조하는 설정 파일. 명령과 Skill을 연결하는 매핑 테이블을 담고 있음 |
| Skill | 특정 작업의 실행 절차가 적힌 .md 파일 (예: 노트생성.md) |
| Agent | 독립된 CLAUDE.md + Skill 세트를 가진 하위 작업 단위 |
| 디스패처 | 사용자의 지시를 적절한 Agent로 라우팅하는 Root CLAUDE.md의 역할 |
Claude Code 자체는 어떤 절차도 내장하지 않습니다. .md 파일이 Claude Code의 행동을 정의하고, Claude Code는 그것을 읽고 실행합니다.
┌─────────────────────────────────────────────┐
│ 사용자 │
│ "노트 만들어줘" │
└────────────────────┬────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Claude Code (행위자) │
│ 지시를 해석하고 실행하는 두뇌 + 손발 │
└────────────────────┬────────────────────────┘
│ ① 참조
▼
┌─────────────────────────────────────────────┐
│ Root CLAUDE.md (디스패처) │
│ 등록된 Agent 목록에서 대상을 선택/매칭 │
│ │
│ Agent명 │ CLAUDE.md 경로 │
│ ─────────────┼────────────────── │
│ Research │ research/CLAUDE.md │
│ Document │ document/CLAUDE.md │
└────────────────────┬────────────────────────┘
│ ② 디스패치
▼
┌─────────────────────────────────────────────┐
│ Agent CLAUDE.md (라우터) │
│ "무엇을 할 수 있는지" — 명령 ↔ 스킬 매핑 │
│ │
│ 사용자 입력 │ 스킬 파일 │
│ ─────────────┼────────────────── │
│ 노트 만들어줘 │ 노트생성.md │
│ 문서 index정리│ 문서index정리.md │
└────────────────────┬────────────────────────┘
│ ③ 로드
▼
┌─────────────────────────────────────────────┐
│ Skill 파일 (레시피) │
│ "어떻게 해야 하는지" — 단계별 실행 절차 │
│ │
│ 예: 노트생성.md │
│ 1. 템플릿 확인 │
│ 2. 파일 생성 │
│ 3. 내용 작성 │
└────────────────────┬────────────────────────┘
│ ④ 실행
▼
┌─────────────────────────────────────────────┐
│ Claude Code가 절차대로 작업 수행 │
│ (파일 생성, 편집, 명령 실행 등) │
└─────────────────────────────────────────────┘| 구성요소 | 역할 | 핵심 질문 |
|---|---|---|
| Claude Code | 읽고, 판단하고, 실행하는 행위자 | — |
| CLAUDE.md | 명령 → 스킬 매핑 (라우터) | "무엇을 할 수 있는가?" |
| Skill 파일 | 단계별 실행 절차 (레시피) | "어떻게 해야 하는가?" |
Root CLAUDE.md (항상 로드됨, cwd 기준)
├── 공통 스킬 테이블 ─→ 직접 스킬 파일 실행
├── 디스패처 명령 테이블 ─→ Agent 선택 유도
└── 등록된 Agent 목록 ─→ 하위 CLAUDE.md 경로
하위 CLAUDE.md (디스패처를 통해 명시적으로 읽힘)
└── 스킬 매핑 섹션 ─→ 스킬 파일 경로 + 주요 동작
└── 스킬 파일 ─→ 실제 실행 절차사용자: "노트 만들어줘"
→ Root CLAUDE.md: 등록된 Agent 목록 표시
→ 사용자: Agent 선택
→ 해당 Agent CLAUDE.md 로드
→ 스킬 매핑 섹션에서 매칭되는 스킬 파일 확인
→ 스킬 파일 읽기 → 절차대로 실행
사용자: "Research 노트 만들어줘" (Agent명 포함)
→ 선택 단계 스킵 → 바로 Research CLAUDE.md 로드 → 스킬 실행### Agent 스킬 (디스패처)
아래 명령은 Agent 목록을 보여주고 사용자가 선택한 뒤,
해당 Agent의 CLAUDE.md → 스킬 매핑 섹션을 읽어 실행한다.
| 명령어 | 동작 |
|------------------|-----------------------------------------------|
| "노트 만들어줘" | Agent 선택 → 해당 CLAUDE.md의 노트생성 스킬 실행 |
| "문서 index정리" | Agent 선택 → 해당 CLAUDE.md의 문서index정리 실행 |
> Agent명을 앞에 붙이면 선택 단계를 건너뛴다.
> 예: "Research 노트 만들어줘" → 바로 Research CLAUDE.md 스킬 실행### 등록된 Agent 목록
| # | Agent명 | CLAUDE.md 경로 |
|---|----------|---------------------|
| 1 | Agent명 | CLAUDE.md 상대경로 |## 스킬 매핑
이 Agent의 작업은 모두 스킬 파일을 통해 처리한다.
스킬 파일 위치: 스킬 파일 폴더 경로
| 사용자 입력 | 스킬 파일 | 주요 동작 |
|------------------------|--------------|------------|
| "Agent명 노트 만들어줘" | 스킬파일경로 | 동작 설명 |
> 명령 시 스킬 파일을 먼저 읽고 그 안의 절차대로 실행한다.> 상위 Root CLAUDE.md에서 Agent 선택 시 이 파일이 로드됩니다.
> Root의 공통 규칙도 함께 적용됩니다.