Chapter 0: 하네스 한눈에 보기

이 챕터는 책 전체의 핵심을 3분 안에 전달한다. Agent와 Skill의 기본 개념을 이미 알고 있다면, 여기서 하네스의 전체 그림을 파악하고 Part 2(Chapter 4)부터 바로 시작할 수 있다.

하네스 = 에이전트 팀 + 오케스트레이터 스킬

하네스의 핵심은 한 문장으로 요약된다:

전문 에이전트 팀을 구성하고, 오케스트레이터 스킬이 이들을 조율하여 복잡한 요청을 처리하는 구조.

사용자 요청
    │
    ▼
┌─────────────────────────────────┐
│  오케스트레이터 스킬 (SKILL.md)  │  ← 누가, 언제, 어떤 순서로 일하는지 정의
│                                 │
│  Phase 1 → 에이전트 A → 산출물  │
│  Phase 2 → 에이전트 B → 산출물  │
│  Phase 3 → 에이전트 C → 검증    │
│  Phase 4 → ...       → 결과물  │
└─────────────────────────────────┘
    │
    ▼
  최종 결과

에이전트는 “누가 하는가” — 전문가의 역할과 원칙을 정의한다. 스킬은 “어떻게 하는가” — 작업의 절차와 규칙을 정의한다. 오케스트레이터 스킬은 “어떤 순서로 하는가” — 에이전트 팀의 실행 흐름을 정의한다.

이 세 요소가 .claude/ 디렉토리 안에 마크다운 파일로 존재한다. 그것이 하네스의 전부다.

인포그래픽: 하네스 구성 요소 전체 맵

메타 스킬: “책을 집필해줘” 한마디면 끝

사용자가 하네스를 직접 설계할 필요는 없다. 하네스 메타 스킬(/harness)이 이 과정을 자동화한다.

“책 집필을 자동화하고 싶다”고 요청하면, 메타 스킬이:

1. 도메인을 분석한다 (어떤 작업이 필요한가?)
2. 에이전트 팀을 구성한다 (.claude/agents/ 에 파일 생성)
3. 각 에이전트의 스킬을 만든다 (.claude/skills/ 에 파일 생성)
4. 팀을 조율하는 오케스트레이터를 만든다
5. 생성된 하네스를 검증한다

메타 스킬은 “스킬을 만드는 스킬”이다. 에이전트 팀 + 오케스트레이터라는 복잡한 구조를 한 번의 요청으로 자동 생성한다. 물론 자동 생성된 결과를 이해하고 커스터마이징하려면 각 파일의 구조를 알아야 한다 — 이것이 이 책에서 생성된 구조를 상세히 다루는 이유다.

인포그래픽: 메타 스킬이 하네스를 만드는 과정

메타 스킬의 실제 내용

아래는 실제로 사용되는 하네스 메타 스킬의 전체 내용이다. 3개의 파일로 구성된다.

디렉토리 구조

~/.claude/skills/harness/
├── SKILL.md                        # 메타 스킬 본체
└── references/
    ├── agent-design-patterns.md    # 아키텍처 패턴 레퍼런스
    └── team-examples.md            # 팀 구성 예시

프로젝트별이 아니라 사용자의 홈 디렉토리(~/.claude/)에 위치한다. 어떤 프로젝트에서든 “책을 집필해줘”, “리서치 팀을 구성해줘”라고 요청하면 이 메타 스킬이 트리거되어 해당 도메인에 맞는 하네스를 자동 생성한다.

파일 1: SKILL.md (메타 스킬 본체)

---
name: harness
description: "하네스를 구성합니다. 전문 에이전트를 정의하며, 해당 에이전트가
             사용할 스킬을 생성하는 메타 스킬. (1) '하네스 구성해줘',
             '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링'
             요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화
             체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때 사용."
---

# Harness — Agent Team & Skill Architect

도메인/프로젝트에 맞는 하네스를 구성하고, 각 에이전트의 역할을 정의하며,
에이전트가 사용할 스킬을 생성하는 메타 스킬.

**핵심 원칙: 에이전트 정의(`.claude/agents/`)와 스킬(`.claude/skills/`)을 생성한다.**

## 워크플로우

### Phase 1: 도메인 분석
1. 사용자 요청에서 도메인/프로젝트 파악
2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
3. 기존 에이전트/스킬 확인 (충돌/중복 방지)

### Phase 2: 팀 아키텍처 설계
1. 작업을 전문 영역으로 분해
2. 에이전트 팀 구조 결정 (아키텍처 패턴은 `references/agent-design-patterns.md` 참조)
   - **파이프라인**: 순차 의존 작업
   - **팬아웃/팬인**: 병렬 독립 작업
   - **전문가 풀**: 상황별 선택 호출
   - **생성-검증**: 생성 후 품질 검수
3. 에이전트 분리 기준 적용:
   - 전문성이 다르면 분리
   - 독립 실행 가능하면 분리
   - 컨텍스트 부담이 크면 분리
   - 재사용성이 높으면 분리

### Phase 3: 에이전트 정의 생성
각 에이전트를 `프로젝트/.claude/agents/{name}.md`에 정의:

​```markdown
---
name: agent-name
description: "역할 설명. 트리거 키워드."
model: sonnet
---

# Agent Name — 역할 요약

당신은 [도메인]의 [역할] 전문가입니다.

## 핵심 역할
## 작업 원칙
## 출력 형식
## 협업
​```

**에이전트 생성 원칙:**
- shared/ 규칙(기본 지침, 코딩 원칙 등)을 에이전트 작업 원칙에 반영
- "Always respond in Korean" 등 기본 지침을 포함
- 출력 형식은 구체적으로 (마크다운 예시 포함)

### Phase 4: 스킬 생성
각 에이전트가 사용할 스킬을 `프로젝트/.claude/skills/{name}/SKILL.md`에 생성.

**스킬 생성 원칙:**
- 에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다)
- 여러 에이전트가 공유하는 스킬도 가능
- 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다
- 레퍼런스가 크면 `references/` 하위에 분리

### Phase 5: 통합 스킬 (오케스트레이터)
팀 전체를 조율하는 상위 스킬 생성:
- 시나리오별 에이전트 구성 테이블
- Phase별 워크플로우 (병렬/순차)
- 에이전트 간 데이터 흐름
- 각 Phase의 **검증 기준** 명시

### Phase 6: 검증
- [ ] 모든 에이전트 파일이 올바른 위치에 있는지 확인
- [ ] frontmatter(name, description, model) 검증
- [ ] 에이전트의 description에 트리거 키워드가 포함되어 있는지 확인
- [ ] 에이전트 간 참조 일관성 확인
- [ ] 오케스트레이터 스킬에서 모든 에이전트가 참조되는지 확인
- [ ] 커맨드(`.claude/commands/`)가 생성되지 않았는지 확인

## 산출물 체크리스트

- [ ] `프로젝트/.claude/agents/` — 에이전트 정의 파일들
- [ ] `프로젝트/.claude/skills/` — 스킬 파일들 (SKILL.md + references/)
- [ ] 통합 오케스트레이터 스킬 1개
- [ ] `.claude/commands/` — 아무것도 생성하지 않음
- [ ] 기존 에이전트/스킬과 충돌 없음

## 참고

- 아키텍처 패턴: `references/agent-design-patterns.md`
- 팀 구성 예시: `references/team-examples.md`

파일 2: references/agent-design-patterns.md (아키텍처 패턴)

메타 스킬이 Phase 2에서 팀 구조를 결정할 때 참조하는 패턴 레퍼런스다.

# Agent Team Design Patterns

## 에이전트 팀 아키텍처 유형

### 1. 파이프라인 (Pipeline)
순차적 작업 흐름. 이전 에이전트의 출력이 다음 에이전트의 입력.

​```
[분석] → [설계] → [구현] → [검증]
​```

예시: 소설 집필 — 세계관 → 캐릭터 → 플롯 → 집필 → 편집

### 2. 팬아웃/팬인 (Fan-out/Fan-in)
병렬 처리 후 결과 통합. 독립적 작업을 동시 수행.

​```
         ┌→ [전문가A] ─┐
[분배] → ├→ [전문가B] ─┼→ [통합]
         └→ [전문가C] ─┘
​```

예시: 종합 리뷰 — 문체/과학/일관성 동시 검증 → 통합 보고

### 3. 전문가 풀 (Expert Pool)
상황에 따라 적절한 전문가를 선택 호출.

​```
[라우터] → { 전문가A | 전문가B | 전문가C }
​```

예시: 소설 도메인 — 세계관/캐릭터/플롯 중 필요한 전문가만 호출

### 4. 생성-검증 (Producer-Reviewer)
생성 에이전트와 검증 에이전트가 쌍으로 동작.

​```
[생성] → [검증] → (문제시) → [생성] 재실행
​```

예시: 웹툰 — artist 생성 → reviewer 검수 → 문제 패널 재생성

## 에이전트 분리 기준

| 기준 | 분리 | 통합 |
|------|------|------|
| 전문성 | 영역이 다르면 분리 | 영역이 겹치면 통합 |
| 병렬성 | 독립 실행 가능하면 분리 | 순차 종속이면 통합 고려 |
| 컨텍스트 | 컨텍스트 부담이 크면 분리 | 가볍고 빠르면 통합 |
| 재사용성 | 다른 팀에서도 쓰면 분리 | 이 팀에서만 쓰면 통합 고려 |

## 스킬 vs 에이전트 구분

| 구분 | 스킬 (Skill) | 에이전트 (Agent) |
|------|-------------|-----------------|
| 정의 | 절차적 지식 + 도구 번들 | 전문가 페르소나 + 행동 원칙 |
| 위치 | `.claude/skills/` | `.claude/agents/` |
| 트리거 | 사용자 요청 키워드 매칭 | Agent 도구로 명시적 호출 |
| 용도 | "어떻게 하는가" | "누가 하는가" |

파일 3: references/team-examples.md (팀 구성 예시)

메타 스킬이 도메인별 팀 구성을 참고할 때 사용하는 예시 모음이다.

# Agent Team Examples

## 예시 1: SF 소설 집필 팀

| 에이전트 | 역할 | 스킬 |
|---------|------|------|
| worldbuilder | 세계관 구축 | world-setting |
| character-designer | 캐릭터 설계 | character-profile |
| plot-architect | 플롯 구조 | outline |
| prose-stylist | 문체 편집 | write-scene, review-chapter |
| science-consultant | 과학 검증 | science-check |
| continuity-manager | 일관성 검증 | consistency-check |

### 팀 아키텍처
​```
Phase 1 (병렬): worldbuilder + character-designer + plot-architect
Phase 2 (순차): prose-stylist (집필)
Phase 3 (병렬): prose-stylist + science-consultant + continuity-manager (리뷰)
​```

## 예시 2: 웹툰 제작 팀

| 에이전트 | 역할 | 스킬 |
|---------|------|------|
| webtoon-artist | 패널 이미지 생성 | generate-webtoon |
| webtoon-reviewer | 품질 검수 | review-webtoon, fix-webtoon-panel |

### 팀 아키텍처
​```
Phase 1: webtoon-artist (패널 생성)
Phase 2: webtoon-reviewer (검수)
Phase 3: webtoon-artist (문제 패널 재생성)
​```

## 예시 3: 리서치 팀

| 에이전트 | 역할 |
|---------|------|
| web-researcher | 웹 검색/수집 |
| analyst | 데이터 분석/종합 |
| report-writer | 보고서 작성 |

이 3개 파일이 메타 스킬의 전부다. SKILL.md가 워크플로우(6단계)를 정의하고, references의 두 파일이 팀 설계 시 참조하는 패턴 사전과 예시 모음 역할을 한다. 메타 스킬은 이 레퍼런스를 읽고 도메인에 적합한 패턴과 팀 구조를 결정한다.

실제 동작 예시: 이 책이 만들어진 방법

이 책 자체가 하네스로 만들어졌다. “12챕터 기술서를 집필해줘”라는 요청 하나로, 5명의 에이전트가 협업하여 259페이지 PDF를 만들어냈다.

에이전트 팀

오케스트레이터가 조율한 흐름

Phase 1: [book-planner]         → outline.md (목차 설계)
              │
Phase 2: [chapter-writer]       → ch01.md ~ ch12.md (12챕터 집필)
              │
Phase 3: [book-editor]          → 리뷰 → CRITICAL 이슈?
              │                          ├─ Yes → [chapter-writer] 수정 → 재리뷰
              │                          └─ No  → 승인
              │
Phase 4: [infographic-creator]  → 7개 SVG (병렬 생성)
              │
Phase 5: [book-publisher]       → PDF 259p + 웹 뷰어

에이전트들은 서로 직접 대화하지 않는다. 파일을 통해 통신한다. book-planner가 outline.md를 만들면, chapter-writer가 그 파일을 읽고 챕터를 쓴다. 오케스트레이터가 이 데이터 흐름을 관리한다.

파일 구조

.claude/
├── agents/                     # 에이전트 정의 (5명)
│   ├── book-planner.md
│   ├── chapter-writer.md
│   ├── book-editor.md
│   ├── infographic-creator.md
│   └── book-publisher.md
└── skills/
    └── book-writer/            # 오케스트레이터 스킬
        └── SKILL.md

마크다운 파일 6개. 이것이 5명의 전문가 팀과 지휘자를 만들어낸 전부다.

인포그래픽: book-writer 하네스 전체 아키텍처

하네스의 핵심 아이디어 3가지

1. 복잡한 작업은 팀으로 나눈다. 한 에이전트에게 모든 것을 맡기면 역할 충돌, 컨텍스트 부족, 병렬 처리 불가의 벽에 부딪힌다. 전문성별로 에이전트를 나누면 각자 자기 역할에 집중할 수 있다.

2. 오케스트레이터가 팀을 지휘한다. 에이전트들이 있어도 누군가 순서를 정하고 결과를 전달해야 한다. 오케스트레이터 스킬이 Phase별 워크플로우를 정의하고, 에이전트 간 데이터 흐름을 관리한다.

3. 모든 것이 마크다운 파일이다. 에이전트 정의, 스킬 정의, 오케스트레이터 — 전부 .claude/ 안의 마크다운 파일이다. 코드 한 줄 없이 자연어로 팀을 구성한다. 이것이 하네스가 접근하기 쉬운 이유다.

이 책의 구성과 읽는 법

추천 경로

• Agent/Skill 개념이 처음이라면: Chapter 1부터 순서대로 읽는다.
• 하네스가 처음이라면: Chapter 2(메타 스킬)를 읽고 직접 실행해본다. 그 후 Part 2로 간다.
• 생성된 구조를 이해하고 싶다면: Part 2(Chapter 3)부터 시작한다.
• 실전 사례가 궁금하다면: Part 3(Chapter 6)의 book-writer 하네스 분석부터 읽는다.

다음 챕터부터는 이 전체 그림을 구성하는 각 조각을 하나씩 다룬다. Chapter 1에서는 에이전트와 스킬의 기본 개념과 파일 구조를 살펴본다.

Chapter 1: Claude Code의 Agent와 Skill 이해하기

이 챕터에서 배울 것

• Claude Code의 확장 구조인 .claude/ 디렉토리가 어떻게 구성되는지
• Agent(에이전트)와 Skill(스킬)이 각각 무엇이며, 왜 분리되어 있는지
• 에이전트 파일과 스킬 파일의 물리적 위치와 구조
• frontmatter의 역할과 트리거 키워드가 동작하는 방식
• 실제 에이전트 파일과 스킬 파일을 읽고 구조를 파악하는 방법

본문

Claude Code는 어떻게 확장되는가

Claude Code는 터미널에서 동작하는 AI 코딩 어시스턴트다. 기본 상태로도 코드를 읽고, 수정하고, 실행할 수 있다. 하지만 프로젝트마다 필요한 전문성은 다르다. 코드 리뷰를 전문으로 하는 AI가 필요할 수도 있고, PDF 조판을 담당하는 AI가 필요할 수도 있다.

이런 확장은 프로젝트 루트의 .claude/ 디렉토리를 통해 이루어진다. 이 디렉토리 안에 마크다운 파일을 배치하면, Claude Code가 이를 읽어서 새로운 능력과 역할을 갖추게 된다.

.claude/
├── agents/           # 에이전트 정의 파일들
│   ├── book-planner.md
│   ├── chapter-writer.md
│   └── book-editor.md
├── skills/           # 스킬 정의 파일들
│   └── book-writer/
│       └── SKILL.md
└── settings.local.json

여기서 핵심적인 두 가지 개념이 등장한다: Agent와 Skill이다.

Agent: “누가 하는가”

에이전트(Agent)는 특정 전문성을 가진 페르소나(persona)다. 사람으로 비유하면 “직책”에 해당한다. 편집자, 기획자, 디자이너처럼 각자 다른 관점과 원칙을 가지고 일한다.

에이전트 파일은 다음 질문에 답한다:

• 이 AI는 누구인가? (역할 정의)
• 어떤 원칙을 따르는가? (행동 규범)
• 어떤 형식으로 결과를 내는가? (출력 규격)
• 누구와 협업하는가? (인터페이스)

에이전트 파일은 .claude/agents/ 디렉토리에 위치하며, 파일명은 {에이전트명}.md 형식이다.

에이전트는 행동의 주체를 정의한다. “무엇을 해야 하는지”보다 “어떤 관점에서 일하는지”에 초점을 맞춘다.

Skill: “어떻게 하는가”

스킬(Skill)은 구체적인 작업 절차를 담은 가이드다. 사람으로 비유하면 “업무 매뉴얼”에 해당한다. 여러 에이전트가 어떤 순서로 일하고, 어떤 도구를 쓰고, 어떤 결과물을 만들어야 하는지를 정의한다.

스킬 파일은 다음 질문에 답한다:

• 어떤 단계를 거쳐 작업하는가? (워크플로우)
• 각 단계에서 어떤 도구를 사용하는가? (도구 번들)
• 산출물은 어디에, 어떤 형식으로 저장하는가? (출력 규칙)
• 여러 에이전트를 어떤 순서로 호출하는가? (오케스트레이션)

스킬 파일은 .claude/skills/{스킬명}/SKILL.md 경로에 위치한다. 에이전트와 달리 디렉토리 단위로 관리되는데, 스킬에 필요한 참고 자료(references/)나 템플릿을 함께 묶기 위해서다.

스킬은 절차와 방법을 정의한다. “누가 하는지”보다 “어떤 순서로, 어떤 도구로 하는지”에 초점을 맞춘다.

Agent와 Skill의 관계

이 둘의 관계를 정리하면 다음과 같다:

인포그래픽: Agent vs Skill 비교 다이어그램

왜 분리해야 할까? 하나의 스킬이 여러 에이전트를 조율할 수 있고, 하나의 에이전트가 여러 스킬에서 활용될 수 있기 때문이다. 예를 들어 chapter-writer 에이전트는 book-writer 스킬뿐 아니라, 미래에 만들 blog-writer 스킬에서도 재사용할 수 있다.

파일 구조: frontmatter와 본문

에이전트 파일과 스킬 파일은 모두 마크다운으로 작성되며, frontmatter(프론트매터)라는 메타데이터 영역을 가진다. frontmatter는 파일 최상단에 ---로 감싸진 YAML 블록이다.

frontmatter의 3가지 핵심 필드

---
name: chapter-writer
description: "책의 챕터를 집필하는 에이전트. '챕터 작성', '집필', 'write chapter' 요청 시 트리거."
model: opus
---

• name: 이 에이전트(또는 스킬)의 고유 식별자. 다른 파일에서 이 이름으로 참조한다.
• description: 역할 설명과 함께 트리거 키워드를 포함한다. Claude Code가 사용자의 요청을 이 설명과 매칭하여 적절한 에이전트/스킬을 활성화한다.
• model: 이 에이전트가 사용할 AI 모델을 지정한다. opus는 가장 강력한 모델로 복잡한 창작 작업에 적합하고, sonnet은 빠르고 효율적인 모델로 분석이나 검증 작업에 적합하다.

트리거 키워드의 역할

description 필드에 포함된 키워드는 단순한 설명이 아니다. 사용자가 Claude Code에게 요청할 때, 이 키워드와 매칭되는 에이전트나 스킬이 자동으로 선택된다.

# book-planner의 description
description: "책의 목차와 구조를 설계하는 에이전트. '목차 설계', '책 구조', 'book plan' 요청 시 트리거."

사용자가 “목차 설계해줘”라고 입력하면, Claude Code는 이 description을 보고 book-planner 에이전트를 활성화한다. 따라서 트리거 키워드는 사용자가 실제로 사용할 만한 자연스러운 표현이어야 한다.

실습: 실제 에이전트 파일 읽어보기

이 책을 집필하는 데 사용된 실제 에이전트 파일을 살펴보자. 먼저 chapter-writer 에이전트다.

파일 위치: .claude/agents/chapter-writer.md

---
name: chapter-writer
description: "책의 챕터를 집필하는 에이전트. '챕터 작성', '집필', 'write chapter' 요청 시 트리거."
model: opus
---

# Chapter Writer — 챕터 집필 전문가

당신은 기술서적의 챕터를 집필하는 전문 작가입니다.

## 핵심 역할
1. **챕터 집필**: book-planner의 명세에 따라 본문 작성
2. **예제 코드 작성**: 따라할 수 있는 실습 코드 포함
3. **설명 문체**: 초보자도 이해할 수 있는 명확한 설명
4. **구조화**: 일관된 챕터 구조 유지

## 작업 원칙
- Always respond in Korean
- 예제 코드는 반드시 **실행 가능**해야 함
- "왜 이렇게 하는가"를 항상 설명
- 전문 용어 첫 등장 시 정의 포함
- 한 챕터에 하나의 핵심 주제만
- 마크다운으로 작성, 파일명: `chapters/ch{NN}-{slug}.md`

## 협업
- `book-planner`의 목차/명세를 입력으로 받음
- `book-editor`가 작성된 챕터를 리뷰
- 리뷰 피드백에 따라 수정 반영

이 파일의 구조를 분석해보자:

1. frontmatter: name으로 식별하고, description에 한국어/영어 트리거 키워드를 모두 포함했다. model: opus로 설정한 이유는 챕터 집필이 긴 맥락을 이해하고 창작하는 복잡한 작업이기 때문이다.

2. 제목과 역할 선언: “당신은 ~전문가입니다”로 시작하여 페르소나를 명확히 부여한다. Claude Code는 이 문장을 읽고 해당 역할에 맞는 어조와 관점을 유지한다.

3. 핵심 역할: 이 에이전트가 무엇을 하는지 4가지로 정의한다. 번호를 매겨 우선순위를 암시한다.

4. 작업 원칙: 모든 출력에 적용되는 규칙이다. “한 챕터에 하나의 핵심 주제만”처럼 구체적이고 검증 가능한 원칙이 좋다.

5. 협업 섹션: 다른 에이전트와의 인터페이스를 정의한다. 입력은 누구에게서 받고, 출력은 누구에게 전달하는지 명시한다.

실습: 실제 스킬 파일 읽어보기

이제 이 에이전트들을 조율하는 book-writer 스킬을 살펴보자.

파일 위치: .claude/skills/book-writer/SKILL.md

---
name: book-writer
description: "책 집필 오케스트레이터. 에이전트 팀을 조율하여 책 한 권을 완성합니다.
              '책 집필', '책 쓰기', 'write book' 요청 시 트리거."
---

# Book Writer — 집필 오케스트레이터

에이전트 팀(book-planner, chapter-writer, book-editor, infographic-creator,
book-publisher)을 조율하여 책 한 권을 완성하는 오케스트레이터 스킬.

## 에이전트 팀 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `book-planner` | 목차/구조 설계 | sonnet | 1 |
| `chapter-writer` | 챕터 집필 | opus | 2, 3 |
| `book-editor` | 원고 리뷰/편집 | sonnet | 3 |
| `infographic-creator` | SVG 인포그래픽 | sonnet | 4 |
| `book-publisher` | PDF + 웹 뷰어 | sonnet | 5 |

## 워크플로우

### Phase 1: 목차 설계
- **에이전트**: `book-planner`
- **입력**: 책 주제, 대상 독자, 요구사항
- **출력**: `book/outline.md`
- **검증**: 사용자가 목차를 확인하고 승인

### Phase 2: 챕터 집필
- **에이전트**: `chapter-writer`
- **입력**: `book/outline.md`의 챕터별 명세
- **출력**: `book/chapters/ch{NN}-{slug}.md`
- **검증**: 각 챕터 파일이 챕터 구조를 따르는지 확인

### Phase 3: 리뷰 루프
- **에이전트**: `book-editor` → `chapter-writer`
- **프로세스**: 리뷰 → 수정 → 재리뷰 → 승인

### Phase 4: 인포그래픽 생성
- **에이전트**: `infographic-creator`
- **출력**: `book/assets/infographic-ch{NN}-{slug}.svg`

### Phase 5: 출판
- **에이전트**: `book-publisher`
- **출력**: PDF + 웹 뷰어

에이전트 파일과 비교하면 구조적 차이가 뚜렷하다:

1. frontmatter에 model이 없다: 스킬 자체는 특정 모델에 종속되지 않는다. 모델은 각 에이전트가 결정한다.

2. 에이전트 팀 구성 테이블: 어떤 에이전트를 어떤 Phase에서 사용하는지 한눈에 보여준다. 이것이 에이전트 파일에는 없는, 스킬만의 고유한 요소다.

3. Phase별 워크플로우: 각 단계의 입력, 출력, 검증 기준을 명시한다. 에이전트 파일이 “내가 누구인지”를 정의한다면, 스킬 파일은 “일의 흐름”을 정의한다.

4. 산출물 경로 규칙: book/chapters/ch{NN}-{slug}.md처럼 파일이 저장될 위치와 네이밍 규칙을 구체적으로 지정한다.

심화: 에이전트와 스킬, 왜 이렇게 나눴을까

“하나의 파일에 역할과 절차를 모두 쓰면 안 되나?”라고 생각할 수 있다. 물론 가능하다. 하지만 분리하면 얻는 이점이 있다.

1. 재사용성

chapter-writer 에이전트는 book-writer 스킬에서만 쓰이는 것이 아니다. 나중에 “블로그 글 작성” 스킬을 만들 때도 같은 에이전트를 호출할 수 있다. 역할 정의는 그대로 두고, 절차만 새로 만들면 된다.

2. 독립적 변경

편집자의 리뷰 기준을 바꾸고 싶다면 book-editor.md만 수정하면 된다. 워크플로우의 Phase 순서를 바꾸고 싶다면 SKILL.md만 수정하면 된다. 서로 영향을 주지 않는다.

3. 관심사 분리

에이전트 파일을 작성할 때는 “이 전문가가 어떤 사람인지”에만 집중하면 된다. 스킬 파일을 작성할 때는 “일의 순서가 어떻게 되는지”에만 집중하면 된다. 두 가지를 동시에 생각하지 않아도 되므로 설계가 명확해진다.

이 분리 원칙은 소프트웨어 설계의 기본 원칙과 같다. 인터페이스(에이전트)와 구현(스킬)을 분리하면 시스템이 유연해진다.

심화: model 선택의 기준

frontmatter의 model 필드는 비용과 품질 사이의 트레이드오프다. 이 책의 에이전트들은 다음과 같이 모델을 배정받았다:

일반적인 기준은 이렇다: - opus: 복잡한 추론, 긴 텍스트 생성, 미묘한 판단이 필요한 작업 - sonnet: 구조화된 작업, 분석, 검증, 코드 생성 등 패턴이 명확한 작업

비용이 제한적이라면, 모든 에이전트를 sonnet으로 시작하고 품질이 부족한 에이전트만 opus로 올리는 점진적 접근이 실용적이다.

정리

• Claude Code의 확장은 .claude/ 디렉토리의 마크다운 파일로 이루어진다.
• Agent는 “누가 하는가”를 정의한다. 전문가 페르소나, 행동 원칙, 출력 형식을 담은 파일이며 .claude/agents/*.md에 위치한다.
• Skill은 “어떻게 하는가”를 정의한다. 워크플로우, 도구 사용법, 산출물 규칙을 담은 파일이며 .claude/skills/*/SKILL.md에 위치한다.
• frontmatter의 name, description, model 세 필드가 에이전트/스킬의 식별, 트리거, 모델 선택을 결정한다.
• 둘을 분리하면 재사용성, 독립적 변경, 관심사 분리라는 설계 이점을 얻는다.

다음 챕터 미리보기

• Chapter 2에서는 이 Agent와 Skill이 팀으로 묶일 때 어떤 일이 벌어지는지 다룬다. 단일 에이전트의 한계를 넘어, 여러 에이전트가 협업하는 하네스(harness)의 개념과, 이를 자동 생성하는 메타 스킬을 소개한다.

Chapter 2: 하네스와 메타 스킬

이 챕터에서 배울 것

• 단일 에이전트의 세 가지 한계: 컨텍스트 윈도우, 역할 충돌, 병렬 처리 불가
• 하네스(harness)가 무엇이고, 메타 스킬이 어떻게 하네스를 자동 생성하는지
• 메타 스킬의 6단계 워크플로우: 도메인 분석부터 검증까지
• 하네스의 3요소: 에이전트 정의, 스킬 정의, 통합 오케스트레이터
• 에이전트를 분리하는 4가지 기준: 전문성, 병렬성, 컨텍스트 부담, 재사용성
• 실전 예제: “기술 블로그 자동화” 하네스를 메타 스킬로 생성하는 전체 과정
• book-writer 하네스의 실제 구조와 데이터 흐름

본문

단일 에이전트의 한계

Chapter 1에서 에이전트와 스킬의 개념을 배웠다. 에이전트 하나와 스킬 하나만으로도 많은 일을 할 수 있다. 하지만 작업이 복잡해지면 벽에 부딪힌다.

책 한 권을 쓰는 상황을 생각해보자. 한 명의 에이전트에게 다음을 모두 맡긴다고 가정한다:

• 목차를 설계한다
• 챕터를 집필한다
• 작성한 내용을 스스로 리뷰한다
• 인포그래픽을 만든다
• PDF로 조판한다

이 접근에는 세 가지 근본적인 문제가 있다.

첫째, 컨텍스트 윈도우(context window) 한계. 컨텍스트 윈도우란 AI가 한 번에 읽고 기억할 수 있는 텍스트의 최대 크기다. 목차 설계 지침, 집필 원칙, 리뷰 체크리스트, SVG 생성 규칙, PDF 조판 설정을 모두 하나의 컨텍스트에 넣으면, 정작 중요한 본문 내용이 들어갈 자리가 줄어든다. 마치 책상 위에 다섯 과목의 교과서를 동시에 펼쳐놓고 공부하는 것과 같다.

둘째, 역할 충돌. 작가는 “표현을 풍부하게” 쓰려 하고, 편집자는 “불필요한 수식어를 삭제해라”고 한다. 한 에이전트에게 두 역할을 동시에 부여하면, 어떤 원칙을 따라야 할지 모호해진다. 글을 쓰면서 동시에 자기 글을 냉정하게 평가하기 어려운 것은 사람도 마찬가지다.

셋째, 병렬 처리 불가. 챕터 12개의 인포그래픽을 만들 때, 단일 에이전트는 하나씩 순서대로 처리해야 한다. 각 인포그래픽이 서로 독립적인데도 동시에 작업할 수 없다.

이 세 가지 문제를 한 줄로 요약하면 이렇다: 복잡한 작업은 한 명이 아니라 팀이 필요하다.

하네스란 무엇인가

하네스(harness)는 에이전트 팀과 오케스트레이터 스킬을 자동 생성하는 메타 스킬(meta-skill)이다. 메타 스킬이란 “스킬을 만드는 스킬”이라는 뜻이다.

사용자 입장에서 하네스와의 상호작용은 놀랍도록 단순하다:

사용자: "책 집필을 자동화하고 싶어. 하네스 구성해줘"
하네스: (도메인 분석 → 에이전트 설계 → 스킬 생성 → 오케스트레이터 조립 → 검증)
결과: .claude/ 안에 에이전트 팀 + 오케스트레이터 완성

이 한 번의 요청이 핵심이다. 사용자는 에이전트 정의 파일을 직접 작성하지 않는다. 스킬 파일을 하나하나 만들지 않는다. 오케스트레이터의 Phase를 설계하지 않는다. 메타 스킬이 이 모든 것을 자동으로 생성한다.

왜 “하네스”라는 이름일까? 하네스는 원래 여러 줄의 케이블이나 끈을 하나로 묶어 관리하는 장치를 뜻한다. 자동차의 와이어 하네스가 수십 개의 전선을 체계적으로 정리하듯, 이 하네스는 여러 에이전트와 스킬을 하나의 체계로 묶어준다.

메타 스킬이 중요한 이유는 진입 장벽을 낮추기 때문이다. 에이전트 정의, 스킬 정의, 오케스트레이터를 직접 작성하려면 이 책의 Part 2 전체를 이해해야 한다. 하지만 메타 스킬을 사용하면 “하네스 구성해줘”라는 한마디로 시작할 수 있다. 물론 자동 생성된 결과를 검토하고 미세 조정하려면 수동 구성의 원리를 알아야 한다 — 이것이 이 책이 존재하는 이유다.

메타 스킬의 6단계 워크플로우

메타 스킬(/harness)이 하네스를 생성할 때 거치는 6단계를 상세히 살펴보자.

메타 스킬의 위치

harness 메타 스킬은 다음 경로에 위치한다.

~/.claude/skills/harness/
├── SKILL.md                        # 메타 스킬 본체
└── references/
    ├── agent-design-patterns.md    # 아키텍처 패턴 레퍼런스
    └── team-examples.md            # 팀 구성 예시

~/.claude/ 경로에 있다는 점에 주목하자. 프로젝트 레벨(.claude/)이 아니라 사용자의 홈 디렉토리(~/.claude/)에 위치한다. 이는 harness 메타 스킬이 특정 프로젝트에 종속되지 않는 범용 도구임을 의미한다. 어떤 프로젝트에서든 “하네스 구성해줘”라고 요청하면 동작한다.

메타 스킬의 frontmatter는 이렇게 생겼다.

---
name: harness
description: "하네스를 구성합니다. 전문 에이전트를 정의하며, 해당 에이전트가
             사용할 스킬을 생성하는 메타 스킬. (1) '하네스 구성해줘',
             '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링'
             요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화
             체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때 사용."
---

references 디렉토리의 두 파일은 메타 스킬이 팀 구조를 결정할 때 참조하는 지식이다. agent-design-patterns.md에는 4가지 아키텍처 패턴(Chapter 3에서 상세히 다룬다)이, team-examples.md에는 다양한 도메인의 팀 구성 예시가 담겨 있다.

Phase 1: 도메인 분석

사용자 요청 → [도메인/프로젝트 파악] → [핵심 작업 유형 식별] → [기존 에이전트/스킬 확인]

사용자가 “기술 블로그 자동화 하네스를 구성해줘”라고 요청하면, Phase 1에서 세 가지를 수행한다.

첫째, 도메인을 파악한다. “기술 블로그 자동화”라는 요청에서 도메인은 “기술 블로그”이고, 자동화 대상은 블로그 글의 기획부터 발행까지의 과정이다.

둘째, 핵심 작업 유형을 식별한다. 기술 블로그를 만들려면 어떤 종류의 작업이 필요한가? 주제 리서치, 아웃라인 작성, 본문 집필, 코드 예제 작성, 기술 검증, 편집, 발행 등이 있다. 이 단계에서 작업 유형을 “생성”, “검증”, “편집”, “분석” 같은 카테고리로 분류한다.

셋째, 기존 에이전트/스킬을 확인한다. 프로젝트에 이미 .claude/agents/나 .claude/skills/에 파일이 있는지 확인한다. 이미 존재하는 에이전트와 이름이 충돌하거나, 역할이 중복되는 것을 방지하기 위해서다.

왜 Phase 1이 중요한가? 잘못된 도메인 분석 위에 세운 팀 구조는 전부 다시 만들어야 한다. 도메인 분석이 정확해야 이후 Phase의 결과도 정확하다.

Phase 2: 팀 아키텍처 설계

[작업을 전문 영역으로 분해] → [아키텍처 패턴 선택] → [에이전트 분리 기준 적용]

Phase 1에서 식별한 작업 유형을 바탕으로 에이전트 팀의 구조를 결정한다. 메타 스킬은 references/agent-design-patterns.md를 참조하여 4가지 아키텍처 패턴 중 적합한 것을 선택한다.

• 파이프라인: 순차적으로 의존하는 작업 (A의 출력이 B의 입력)
• 팬아웃/팬인: 독립적인 작업을 병렬 처리한 후 결과 통합
• 전문가풀: 상황에 따라 적절한 전문가를 선택 호출
• 생성-검증: 생성 후 품질 검수, 문제 시 재생성

그리고 에이전트를 분리할지 통합할지를 4가지 기준으로 판단한다(이 기준은 이 챕터의 뒷부분에서 상세히 다룬다). 메타 스킬이 자동으로 판단하지만, 결과를 사용자에게 보여주고 확인을 받는다. 자동화가 판단을 대신해도 최종 승인은 사람의 몫이다.

Phase 3: 에이전트 정의 생성

[에이전트 파일 생성] → 프로젝트/.claude/agents/{name}.md

Phase 2에서 설계한 팀 구조를 기반으로, 각 에이전트의 정의 파일을 .claude/agents/ 디렉토리에 생성한다. 에이전트 파일은 Chapter 1에서 배운 구조를 따른다: frontmatter + 역할 선언 + 핵심 역할 + 작업 원칙 + 출력 형식 + 협업.

메타 스킬이 에이전트를 생성할 때 적용하는 원칙이 세 가지 있다.

첫째, 프로젝트 공유 설정을 반영한다. 기본 지침, 코딩 원칙 등이 있으면 에이전트의 작업 원칙에 이를 반영한다.

둘째, 출력 형식을 구체적으로 명시한다. “적절히 작성하라”가 아니라, 마크다운 예시를 포함하여 산출물의 형태를 명확히 보여준다.

셋째, 협업 섹션에서 다른 에이전트와의 관계를 정의한다. 누구에게서 입력을 받고, 누구에게 출력을 전달하는지를 명시한다. 이 정보가 없으면 에이전트는 팀 안에서 자기 위치를 모른다.

Phase 4: 스킬 생성

[스킬 파일 생성] → 프로젝트/.claude/skills/{name}/SKILL.md

각 에이전트가 사용할 스킬을 .claude/skills/ 디렉토리에 생성한다. 모든 에이전트가 반드시 별도 스킬 파일을 가져야 하는 것은 아니다. 에이전트 정의 안에 작업 절차가 충분히 담길 수 있으면 별도 스킬 없이도 동작한다. 작업 절차가 길거나, 참고 자료(references/)를 함께 관리해야 할 때 스킬로 분리한다.

스킬 생성의 핵심 원칙 네 가지:

Phase 5: 통합 스킬 (오케스트레이터) 생성

[오케스트레이터 스킬 생성] → 프로젝트/.claude/skills/{팀명}/SKILL.md

팀 전체를 조율하는 상위 스킬을 생성한다. 오케스트레이터가 정의하는 것은 네 가지다.

1. 에이전트 구성 테이블: 시나리오별로 어떤 에이전트가 참여하는지
2. Phase별 워크플로우: 각 Phase의 입력, 출력, 실행 방식 (병렬/순차)
3. 에이전트 간 데이터 흐름: 산출물이 파일로 어디에 저장되고, 다음 에이전트가 어디서 읽는지
4. Phase별 검증 기준: 각 Phase가 끝날 때 충족해야 할 조건

오케스트레이터는 하네스의 “설계도”다. 이 파일 하나를 읽으면 팀의 전체 구조와 워크플로우를 파악할 수 있어야 한다.

Phase 6: 검증

Phase 1~5를 거쳐 파일들이 생성된 후, 마지막으로 6가지 항목을 검증한다.

검증 체크리스트:
- [ ] 모든 에이전트 파일이 올바른 위치에 있는가
- [ ] frontmatter(name, description, model)가 유효한가
- [ ] 에이전트의 description에 트리거 키워드가 포함되어 있는가
- [ ] 에이전트 간 참조가 일관성 있는가
- [ ] 오케스트레이터 스킬에서 모든 에이전트가 참조되는가
- [ ] .claude/commands/ 에 아무것도 생성되지 않았는가

파일 위치 검증: 위치가 틀리면 Claude Code가 인식하지 못한다. frontmatter 검증: name이 빠지면 에이전트가 로드되지 않는다. 트리거 키워드 검증: description에 트리거 키워드가 없으면 사용자가 에이전트를 호출할 방법이 없다. 참조 일관성 검증: 에이전트 A의 협업 섹션에서 “에이전트 B에게 전달”이라고 했는데, 에이전트 B가 존재하지 않으면 워크플로우가 끊긴다. 오케스트레이터 완전성 검증: 참조하지 않는 에이전트가 있으면 팀에서 호출되지 않는 “고아”가 된다. commands 미생성 검증: 메타 스킬이 “도움이 될 것 같아서” 커맨드까지 생성하는 과잉 행동을 방지한다.

결과적으로 하네스가 생성하는 산출물은 다음 세 가지다:

하네스의 산출물
├── 에이전트 정의 파일들    (.claude/agents/*.md)
├── 스킬 정의 파일들        (.claude/skills/*/SKILL.md)
└── 통합 오케스트레이터     (.claude/skills/{팀명}/SKILL.md)

인포그래픽: 메타 스킬이 하네스를 만드는 과정

하네스의 3요소

하네스를 구성하는 세 가지 요소를 정리하면 다음과 같다.

이 세 요소는 각각 Chapter 1에서 배운 Agent와 Skill의 확장이다. 차이점은 여러 에이전트가 하나의 오케스트레이터 아래 조율된다는 것이다.

각 요소를 하나씩 살펴보자.

요소 1: 에이전트 정의

에이전트 정의는 Chapter 1에서 본 것과 동일하다. 다만 팀으로 묶일 때는 협업 섹션이 중요해진다. 어떤 에이전트에게서 입력을 받고, 어떤 에이전트에게 출력을 전달하는지 명시해야 한다.

## 협업
- `book-planner`의 목차/명세를 입력으로 받음
- `book-editor`가 작성된 챕터를 리뷰
- 리뷰 피드백에 따라 수정 반영

이 협업 정의가 없으면 에이전트는 자기 역할만 알고, 팀 내에서 자신의 위치를 모른다.

요소 2: 스킬 정의

개별 스킬은 에이전트가 참조하는 작업 절차다. 오케스트레이터와 구분하기 위해 개별 스킬이라 부르자. 예를 들어 book-editor 에이전트가 리뷰할 때 참조하는 체크리스트, infographic-creator가 SVG를 생성할 때 따르는 디자인 가이드 등이 여기에 해당한다.

모든 에이전트가 반드시 별도의 스킬 파일을 가져야 하는 것은 아니다. 에이전트 정의 파일 안에 작업 절차가 충분히 담길 수 있으면 별도 스킬 없이도 동작한다. 작업 절차가 길거나, 참고 자료(references/)를 함께 관리해야 할 때 스킬로 분리한다.

요소 3: 통합 오케스트레이터

오케스트레이터(orchestrator)는 팀 전체를 지휘하는 상위 스킬이다. 오케스트라의 지휘자가 각 악기 파트에 언제 연주하라고 신호를 보내듯, 오케스트레이터는 각 에이전트에게 언제, 어떤 순서로 작업하라고 지시한다.

오케스트레이터가 정의하는 것은 세 가지다:

1. 에이전트 구성 테이블: 누가 팀에 있는지, 각자 어떤 Phase에서 활동하는지
2. Phase별 워크플로우: 각 Phase의 입력, 출력, 검증 기준
3. 에이전트 간 데이터 흐름: 산출물이 파일로 어디에 저장되고, 다음 에이전트가 어디서 읽는지

오케스트레이터 자체도 .claude/skills/ 아래의 SKILL.md 파일이다. 다른 스킬과 형식이 같지만, 여러 에이전트를 호출하는 워크플로우를 담고 있다는 점이 다르다.

인포그래픽: 하네스 구성 요소 전체 맵

에이전트 분리 기준 4가지

하네스를 설계할 때 가장 어려운 판단은 “이 작업을 별도 에이전트로 분리할 것인가, 기존 에이전트에 맡길 것인가”다. 메타 스킬이 Phase 2에서 이 판단을 자동으로 내리지만, 사용자가 결과를 검토하려면 기준을 알아야 한다. 다음 4가지 기준으로 판단한다.

기준 1: 전문성

영역이 다르면 분리한다.

목차 설계와 본문 집필은 서로 다른 전문성을 요구한다. 목차 설계는 전체 구조를 조감하는 분석적 사고가 필요하고, 본문 집필은 독자를 이끌어가는 서술 능력이 필요하다. 하나의 에이전트에게 “분석가이면서 작가”라는 이중 역할을 부여하면, 어느 쪽에도 깊이 집중하지 못한다.

반대로, 영역이 겹치면 통합을 고려한다. “문법 검사”와 “맞춤법 검사”는 전문성이 거의 같으므로 하나의 에이전트로 충분하다.

기준 2: 병렬성

독립적으로 실행 가능하면 분리한다.

12개 챕터의 인포그래픽을 만드는 작업은 챕터 간에 의존성이 없다. 챕터 3의 인포그래픽을 만들기 위해 챕터 1의 인포그래픽이 완성되어야 할 이유가 없다. 이런 경우 별도 에이전트로 분리하면 병렬 처리가 가능해진다.

반대로, 반드시 순서대로 처리해야 하는 작업은 분리해도 병렬 이점이 없으므로 통합을 고려한다.

기준 3: 컨텍스트 부담

컨텍스트 윈도우를 크게 차지하면 분리한다.

PDF 조판을 위해서는 CSS 스타일시트, 페이지 레이아웃 설정, 폰트 임베딩 규칙 등 방대한 참고 자료가 필요하다. 이 모든 것을 챕터 집필 에이전트의 컨텍스트에 함께 넣으면, 정작 집필에 쓸 공간이 줄어든다. 별도의 book-publisher 에이전트로 분리하면 각자 자기 작업에 필요한 컨텍스트만 가지면 된다.

기준 4: 재사용성

다른 팀에서도 활용할 수 있으면 분리한다.

chapter-writer 에이전트는 이 책의 집필뿐 아니라, 기술 블로그 작성, 교육 자료 제작 등 다른 하네스에서도 재사용할 수 있다. 범용적인 역할은 독립 에이전트로 분리해두면 미래의 다른 프로젝트에서 그대로 가져다 쓸 수 있다.

이 4가지 기준을 표로 정리하면 다음과 같다:

4가지 기준 모두 충족할 필요는 없다. 하나라도 강하게 해당되면 분리를 고려하되, 에이전트 수가 너무 많아지면 오케스트레이터의 복잡도가 올라간다는 트레이드오프도 기억해야 한다.

실전: “기술 블로그 자동화” 하네스 생성

이제 harness 메타 스킬을 사용하여 실제로 하네스를 생성하는 전체 과정을 따라가 보자. 도메인은 “기술 블로그 자동화”다. 6단계 워크플로우가 실전에서 어떻게 동작하는지, Phase별로 살펴본다.

시작: 사용자 요청

사용자: 기술 블로그 자동화 하네스를 구성해줘.
        주제 선정부터 블로그 글 발행까지 자동화하고 싶어.
        코드 예제가 포함된 기술 글을 작성하는 거야.

이 한 마디로 메타 스킬이 트리거된다. “하네스 구성해줘”가 description의 트리거 키워드에 매칭되기 때문이다.

Phase 1 실행: 도메인 분석

메타 스킬이 요청을 분석한 결과:

도메인 분석 결과:
- 도메인: 기술 블로그
- 자동화 범위: 주제 선정 → 리서치 → 아웃라인 → 집필 → 코드 예제 → 기술 검증 → 편집 → 발행
- 핵심 작업 유형:
  - 분석: 주제 리서치, 기술 트렌드 파악
  - 설계: 아웃라인 구성, 글 구조 설계
  - 생성: 본문 집필, 코드 예제 작성
  - 검증: 기술 정확성 검증, 코드 실행 검증
  - 편집: 가독성 개선, 문법 검수
- 기존 에이전트/스킬: 없음 (신규 프로젝트)

기존 에이전트가 없으므로 충돌 걱정이 없다. 기존 에이전트가 있었다면 여기서 충돌 가능성을 보고하고 대안을 제시했을 것이다.

Phase 2 실행: 팀 아키텍처 설계

작업 유형을 전문 영역으로 분해하고, 아키텍처 패턴을 선택한다.

팀 아키텍처 설계:

아키텍처 패턴: 파이프라인 + 생성-검증
- 파이프라인: 리서치 → 아웃라인 → 집필 → 편집 → 발행 (순차 의존)
- 생성-검증: 집필 → 기술 검증 → (문제시) 재집필 (품질 보장)

에이전트 분리 결정:
| 에이전트 후보 | 분리 근거 |
|-------------|----------|
| topic-researcher | 전문성: 리서치 ≠ 집필 |
| blog-writer | 전문성: 글쓰기에 집중 |
| code-crafter | 전문성: 코드 작성 ≠ 글쓰기, 컨텍스트: 언어별 컨벤션 |
| tech-reviewer | 역할 충돌 방지: 작성자 ≠ 검증자 |
| blog-editor | 전문성: 편집 ≠ 집필, 역할 충돌 방지 |

여기서 메타 스킬이 내린 핵심 판단 두 가지를 살펴보자.

첫째, blog-writer와 code-crafter를 분리했다. 하나의 에이전트가 글도 쓰고 코드도 작성할 수 있지만, 분리한 이유는 컨텍스트 부담이다. 기술 글의 코드 예제는 실행 가능해야 하고, 해당 언어의 관용적 스타일을 따라야 한다. 코드 컨벤션과 실행 환경 설정을 글쓰기 에이전트의 컨텍스트에 함께 넣으면 컨텍스트 오염 문제가 발생할 수 있다.

둘째, tech-reviewer를 blog-writer와 분리했다. 생성-검증 패턴의 핵심 원칙이다. 글을 쓴 에이전트가 자기 글의 기술적 정확성을 객관적으로 평가하기 어렵다. 검증자는 “이 설명이 기술적으로 맞는가?”만 판단하면 되므로, 역할을 분리하는 것이 품질에 유리하다.

메타 스킬은 이 설계 결과를 사용자에게 보여주고 확인을 받은 후 Phase 3으로 넘어간다.

Phase 3 실행: 에이전트 정의 생성

확정된 팀 구조를 기반으로 5개의 에이전트 파일을 생성한다.

.claude/agents/topic-researcher.md:

---
name: topic-researcher
description: "기술 블로그 주제 리서치 전문가. 트렌드 분석, 주제 선정,
             참고 자료 수집을 담당합니다. '주제 리서치', '토픽 분석' 요청 시 트리거."
model: sonnet
---

# 주제 리서처 -- 기술 트렌드를 분석하고 블로그 주제를 제안합니다

당신은 기술 블로그의 주제 리서치를 담당하는 전문가입니다.
항상 한국어로 응답합니다.

## 핵심 역할
1. 기술 트렌드와 커뮤니티 관심사를 분석한다
2. 블로그 주제를 3~5개 제안하고 각각의 근거를 제시한다
3. 선정된 주제에 대한 참고 자료를 수집한다
4. 글의 아웃라인 초안을 작성한다

## 작업 원칙
- 제안하는 주제에 반드시 "왜 지금 이 주제인가"의 근거를 포함한다
- 참고 자료는 출처를 명시한다
- 독자 수준(초급/중급/고급)을 고려한 난이도 표시를 한다

## 출력 형식
리서치 결과를 `blog-output/research.md`에 저장한다.

## 협업
- **출력**: blog-writer에게 리서치 결과와 아웃라인 전달

.claude/agents/blog-writer.md:

---
name: blog-writer
description: "기술 블로그 본문 집필 전문가. 리서치 결과를 바탕으로
             독자 친화적인 기술 글을 작성합니다. '블로그 집필', '글쓰기' 요청 시 트리거."
model: opus
---

# 블로그 라이터 -- 독자 친화적인 기술 글을 작성합니다

당신은 기술 블로그의 본문을 집필하는 전문가입니다.
항상 한국어로 응답합니다.

## 핵심 역할
1. 리서치 결과와 아웃라인을 기반으로 본문을 작성한다
2. 기술 개념을 비유와 단계적 설명으로 풀어쓴다
3. 코드가 삽입될 위치를 표시하고 code-crafter에게 전달할 명세를 작성한다

## 작업 원칙
- "왜 이렇게 하는가"를 항상 설명한다
- 한 섹션에 하나의 개념만 다룬다
- 코드 예제가 필요한 곳에 `<!-- CODE: {설명} -->` 플레이스홀더를 삽입한다

## 출력 형식
블로그 글을 `blog-output/draft.md`에 저장한다.

## 협업
- **입력**: topic-researcher의 `blog-output/research.md`
- **출력**: code-crafter에게 코드 명세 전달, tech-reviewer가 기술 검증

.claude/agents/code-crafter.md:

---
name: code-crafter
description: "기술 블로그 코드 예제 전문가. 실행 가능한 코드 예제와
             테스트를 작성합니다. '코드 예제', '코드 작성' 요청 시 트리거."
model: opus
---

# 코드 크래프터 -- 실행 가능한 코드 예제를 작성합니다

당신은 기술 블로그에 포함될 코드 예제를 작성하는 전문가입니다.
항상 한국어로 응답합니다.

## 핵심 역할
1. blog-writer가 표시한 코드 플레이스홀더에 맞는 코드를 작성한다
2. 모든 코드는 독자가 복사하여 바로 실행할 수 있어야 한다
3. 필요시 간단한 테스트 코드를 포함한다

## 작업 원칙
- 코드에 한국어 주석으로 핵심 로직을 설명한다
- 외부 라이브러리 사용 시 설치 명령을 함께 제공한다
- 해당 언어의 관용적 스타일을 따른다

## 출력 형식
코드를 `blog-output/codes/` 디렉토리에 저장한다.

## 협업
- **입력**: blog-writer의 `blog-output/draft.md`에서 코드 플레이스홀더 확인
- **출력**: `blog-output/codes/` 에 코드 파일 저장, blog-writer가 본문에 삽입

.claude/agents/tech-reviewer.md:

---
name: tech-reviewer
description: "기술 블로그 기술 검증 전문가. 기술적 정확성과 코드의
             실행 가능성을 검증합니다. '기술 검증', '팩트 체크' 요청 시 트리거."
model: sonnet
---

# 기술 리뷰어 -- 기술적 정확성을 검증합니다

당신은 기술 블로그의 기술적 정확성을 검증하는 전문가입니다.
항상 한국어로 응답합니다.

## 핵심 역할
1. 본문의 기술 설명이 정확한지 검증한다
2. 코드 예제가 실행 가능하고 올바른 결과를 내는지 확인한다
3. 기술적 오류를 발견하면 구체적인 피드백을 작성한다

## 검증 기준

### CRITICAL (FAIL)
- 기술적으로 틀린 설명이 있다
- 코드에 구문 오류가 있다
- 보안 취약점이 있는 코드 예제다

### MAJOR (FAIL)
- 설명과 코드가 일치하지 않는다
- 코드의 에러 처리가 누락되어 실행 시 크래시가 예상된다
- 더 이상 사용하지 않는(deprecated) API를 사용한다

### MINOR (PASS -- 기록만)
- 더 효율적인 방법이 있다
- 주석이 부족하다

## 출력 형식
검증 결과를 `blog-output/review.md`에 저장한다.

## 작업 원칙
- 코드를 직접 수정하지 않는다. 피드백만 작성한다
- MINOR 이슈로 FAIL 판정하지 않는다

.claude/agents/blog-editor.md:

---
name: blog-editor
description: "기술 블로그 편집 전문가. 가독성, 구조, 문법을 개선합니다.
             '블로그 편집', '글 다듬기' 요청 시 트리거."
model: sonnet
---

# 블로그 에디터 -- 가독성과 구조를 개선합니다

당신은 기술 블로그의 편집을 담당하는 전문가입니다.
항상 한국어로 응답합니다.

## 핵심 역할
1. 문장의 가독성과 흐름을 개선한다
2. 전체 글의 구조가 논리적인지 검토한다
3. 맞춤법과 문법을 검수한다
4. 기술 용어의 일관성을 확인한다

## 작업 원칙
- 기술적 정확성은 tech-reviewer의 영역이다. 편집은 가독성에 집중한다
- 원본의 기술적 의미를 변경하지 않는다

## 출력 형식
편집 결과를 `blog-output/edited-draft.md`에 저장한다.

## 협업
- **입력**: tech-reviewer의 검증을 통과한 `blog-output/draft.md`
- **출력**: 최종 편집본 `blog-output/edited-draft.md`

5개 에이전트의 모델 선택 근거를 정리하면 다음과 같다.

창의적 생성(집필, 코드)에는 opus, 규칙 기반 작업(리서치, 검증, 편집)에는 sonnet. 이것이 비용 대비 품질의 균형이다.

Phase 4 실행: 스킬 생성

이 예제에서는 개별 에이전트의 작업 절차가 에이전트 정의 안에 충분히 담겼으므로, 별도 스킬 파일 없이 오케스트레이터 스킬만 생성한다. 모든 에이전트가 반드시 별도 스킬을 가질 필요는 없다는 것을 기억하자.

만약 code-crafter가 여러 언어를 다루어 언어별 컨벤션 레퍼런스가 필요하다면, skills/code-crafter/SKILL.md와 skills/code-crafter/references/를 별도로 생성할 수 있다. 이 판단은 도메인의 복잡도에 따라 달라진다.

Phase 5 실행: 오케스트레이터 생성

.claude/skills/tech-blog/SKILL.md:

---
name: tech-blog
description: "기술 블로그 자동화 하네스. 주제 리서치부터 편집까지
             자동화합니다. '기술 블로그', 'tech blog harness' 요청 시 트리거."
---

# 기술 블로그 오케스트레이터

주제 리서치부터 편집까지 기술 블로그 작성 전 과정을 자동화하는 하네스입니다.

## 에이전트 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `topic-researcher` | 주제 리서치, 아웃라인 | sonnet | 1 |
| `blog-writer` | 본문 집필 | opus | 2, 3 |
| `code-crafter` | 코드 예제 작성 | opus | 2 |
| `tech-reviewer` | 기술 검증 | sonnet | 3 |
| `blog-editor` | 편집, 교정 | sonnet | 4 |

## 산출물 디렉토리

blog-output/
├── research.md          # Phase 1 산출물
├── draft.md             # Phase 2 산출물
├── codes/               # Phase 2 산출물 (코드)
│   ├── example-01.py
│   └── example-02.py
├── review.md            # Phase 3 산출물
└── edited-draft.md      # Phase 4 산출물 (최종)

## 워크플로우

### Phase 1: 주제 리서치
- **에이전트**: `topic-researcher`
- **입력**: 사용자의 주제 요청 또는 "알아서 선정"
- **출력**: `blog-output/research.md` (주제, 근거, 참고 자료, 아웃라인)
- **검증**: 주제와 아웃라인을 사용자에게 보여주고 승인
- **완료 후**: 사용자 확인

### Phase 2: 집필 + 코드 작성
- **에이전트**: `blog-writer` → `code-crafter`
- **처리**:
  1. `blog-writer`가 아웃라인 기반으로 본문을 작성한다
     (코드 위치에 플레이스홀더 삽입)
  2. `code-crafter`가 플레이스홀더에 맞는 코드를 작성한다
  3. `blog-writer`가 코드를 본문에 삽입하여 완성한다
- **출력**: `blog-output/draft.md`, `blog-output/codes/`
- **검증**: 모든 플레이스홀더가 코드로 교체되었는지 확인
- **완료 후**: 초안을 사용자에게 보여주고 확인

### Phase 3: 기술 검증 루프 (생성-검증)
- **생성자**: `blog-writer` + `code-crafter`
- **검증자**: `tech-reviewer`
- **최대 반복**: 3회
- **루프 절차**:
  1. `tech-reviewer`가 본문과 코드의 기술적 정확성을 검증
  2. CRITICAL 또는 MAJOR 이슈가 있으면 FAIL
  3. FAIL 시: 피드백을 blog-writer/code-crafter에게 전달하여 수정
  4. 수정본을 다시 tech-reviewer가 검증
  5. PASS가 나오거나 최대 반복에 도달할 때까지 반복
- **출력**: `blog-output/review.md`
- **루프 종료 조건**: CRITICAL 0개 AND MAJOR 0개
- **최대 반복 도달 시**: 남은 이슈를 사용자에게 에스컬레이션

### Phase 4: 편집
- **에이전트**: `blog-editor`
- **입력**: 기술 검증을 통과한 `blog-output/draft.md`
- **출력**: `blog-output/edited-draft.md`
- **검증**: 편집본을 사용자에게 보여주고 최종 확인

## 중요 규칙
- 각 Phase 완료 후 사용자에게 결과를 보여주고 다음 Phase 진행 여부를 확인한다
- tech-reviewer는 코드를 직접 수정하지 않는다. 피드백만 작성한다
- blog-editor는 기술적 정확성을 판단하지 않는다. 가독성에만 집중한다

이 오케스트레이터에서 주목할 설계 판단 세 가지:

첫째, Phase 2에서 blog-writer와 code-crafter가 순차 협업한다. blog-writer가 먼저 플레이스홀더를 포함한 초안을 쓰고, code-crafter가 코드를 채우고, blog-writer가 코드를 본문에 삽입한다. 코드와 글이 분리 생성되기 때문에 각자 전문성에 집중할 수 있다.

둘째, Phase 3의 생성-검증 루프에서 생성자가 2명이다. 기술적 오류가 본문에 있으면 blog-writer가, 코드에 있으면 code-crafter가 수정한다. 검증자가 피드백에서 어느 에이전트에게 수정을 요청할지 명시한다.

셋째, 블로그 발행(publish) 단계는 포함하지 않았다. 사용자의 요청이 “주제 선정부터 블로그 글 발행까지”였지만, 발행은 플랫폼(GitHub Pages, Medium, 개인 블로그 등)에 따라 완전히 달라지므로 범용 에이전트로 만들기 어렵다. 메타 스킬이 이 판단을 내리고 사용자에게 알릴 수 있다.

Phase 6 실행: 검증

생성된 파일들을 검증 체크리스트로 확인한다.

검증 결과:

[PASS] 모든 에이전트 파일이 .claude/agents/ 에 위치함
       - topic-researcher.md
       - blog-writer.md
       - code-crafter.md
       - tech-reviewer.md
       - blog-editor.md

[PASS] frontmatter 검증
       - 모든 파일에 name, description, model 존재
       - model 값이 sonnet 또는 opus로 유효

[PASS] 트리거 키워드 검증
       - 모든 description에 트리거 키워드 포함

[PASS] 에이전트 간 참조 일관성
       - blog-writer → code-crafter: code-crafter 존재 확인
       - blog-writer → tech-reviewer: tech-reviewer 존재 확인
       - tech-reviewer → blog-writer: blog-writer 존재 확인

[PASS] 오케스트레이터 완전성
       - 5개 에이전트 모두 오케스트레이터에서 참조됨

[PASS] commands 미생성
       - .claude/commands/ 에 새 파일 없음

6개 항목 모두 PASS. 하네스 생성이 완료되었다.

생성된 디렉토리 구조

프로젝트/
├── .claude/
│   ├── agents/
│   │   ├── topic-researcher.md
│   │   ├── blog-writer.md
│   │   ├── code-crafter.md
│   │   ├── tech-reviewer.md
│   │   └── blog-editor.md
│   └── skills/
│       └── tech-blog/
│           └── SKILL.md            # 오케스트레이터
└── blog-output/                    # (실행 시 생성될 산출물 디렉토리)
    ├── research.md
    ├── draft.md
    ├── codes/
    ├── review.md
    └── edited-draft.md

생성된 하네스 사용하기

하네스가 생성되었으니, 이제 사용할 차례다. 사용자가 Claude Code에서 다음과 같이 요청한다.

사용자: 기술 블로그 하네스로 "Python의 패턴 매칭(match/case)" 주제로 글을 써줘

“기술 블로그”가 오케스트레이터의 트리거 키워드에 매칭되어 tech-blog 스킬이 활성화된다. 이후 오케스트레이터가 Phase 1부터 순서대로 실행한다.

1. topic-researcher가 Python 패턴 매칭에 대한 리서치와 아웃라인을 작성한다
2. 사용자가 아웃라인을 확인하고 승인한다
3. blog-writer가 본문을 쓰고, code-crafter가 코드 예제를 작성한다
4. 사용자가 초안을 확인한다
5. tech-reviewer가 기술 검증을 수행한다
6. 문제가 있으면 수정-재검증 루프가 돈다
7. blog-editor가 최종 편집을 한다
8. 사용자가 편집본을 최종 확인한다

각 Phase에서 사용자 확인을 받는다는 점이 중요하다. 자동화되었다고 해서 사람이 빠지는 것이 아니다. 사람은 “방향이 맞는지” 판단하고, 에이전트는 “실행”을 담당한다.

book-writer 하네스로 이 책이 만들어지는 과정도 본질적으로 동일하다. 다음 절에서 book-writer 하네스의 구조를 살펴보면, 같은 원리가 다른 도메인에 어떻게 적용되는지 확인할 수 있다.

실습: book-writer 하네스의 구조 살펴보기

이 책 자체가 하네스로 집필되고 있다. 이보다 좋은 예제는 없다. book-writer 하네스의 실제 구조를 살펴보자.

디렉토리 구조

프로젝트/
├── .claude/
│   ├── agents/                     # 에이전트 정의
│   │   ├── book-planner.md         # 목차 설계자
│   │   ├── chapter-writer.md       # 챕터 집필자
│   │   ├── book-editor.md          # 편집자
│   │   ├── infographic-creator.md  # 인포그래픽 제작자
│   │   └── book-publisher.md       # 출판 담당자
│   └── skills/
│       └── book-writer/            # 통합 오케스트레이터
│           └── SKILL.md
└── book/                           # 산출물 디렉토리
    ├── outline.md                  # Phase 1 산출물
    ├── chapters/                   # Phase 2 산출물
    │   ├── ch01-agent-and-skill.md
    │   ├── ch02-harness-concept.md
    │   └── ...
    ├── assets/                     # Phase 4 산출물
    │   └── infographic-ch01-*.svg
    └── output/                     # Phase 5 산출물
        ├── pdf/
        └── web/

이 구조에서 두 가지를 주목하자:

1. .claude/ 아래에 에이전트와 스킬이 분리되어 있다. 에이전트 5명은 각각 독립적인 마크다운 파일이고, 오케스트레이터는 skills/book-writer/SKILL.md 하나다.

2. book/ 디렉토리가 산출물 저장소다. 에이전트 간 통신은 이 디렉토리의 파일을 통해 이루어진다. book-planner가 outline.md를 만들면, chapter-writer가 그 파일을 읽고 챕터를 쓴다. 별도의 메시지 큐나 API가 아니라 파일 시스템이 에이전트 간 통신 채널이다.

에이전트 팀 구성

왜 이렇게 분리했을까? 4가지 기준을 적용해보자:

• book-planner vs chapter-writer: 전문성이 다르다. 구조 설계 vs 본문 작성.
• chapter-writer vs book-editor: 역할 충돌 방지. 작가와 편집자는 정반대의 관점을 가져야 한다.
• infographic-creator: 병렬 처리 가능. 12개 챕터의 인포그래픽을 동시에 만들 수 있다.
• book-publisher: 컨텍스트 부담. PDF 조판 규칙은 집필과 무관한 대량의 참고 자료를 필요로 한다.

Phase별 워크플로우

이 오케스트레이터는 5개의 Phase를 순서대로 실행한다. 각 Phase의 실행 방식이 다르다는 점에 주목하자.

Phase 1 – 목차 설계 (순차)

[book-planner] → outline.md → 사용자 승인

book-planner가 목차를 만들고, 사용자가 확인한 후 다음으로 넘어간다. 목차가 확정되지 않으면 이후 모든 작업이 의미 없으므로 순차 실행이 필수다.

Phase 2 – 챕터 집필 (순차)

[chapter-writer] → ch01.md → ch02.md → ... → ch12.md

chapter-writer가 한 챕터씩 순서대로 집필한다. 앞 챕터의 내용을 뒤 챕터에서 참조하므로 순차 실행한다.

Phase 3 – 리뷰 루프 (생성-검증)

[book-editor] → 리뷰 → CRITICAL 이슈 발견?
                         ├─ Yes → [chapter-writer] → 수정 → [book-editor] 재리뷰
                         └─ No  → 승인

이 Phase가 가장 흥미롭다. 두 에이전트가 루프를 돈다. book-editor가 리뷰하고, 심각한 문제가 있으면 chapter-writer가 수정하고, 다시 book-editor가 리뷰한다. CRITICAL 이슈가 0개가 될 때까지 반복한다. 이것이 생성-검증(Producer-Reviewer) 패턴이다.

Phase 4 – 인포그래픽 생성 (병렬)

         ┌→ [infographic-creator] → ch01 SVG
         ├→ [infographic-creator] → ch02 SVG
         ├→ [infographic-creator] → ch03 SVG
         └→ ...

각 챕터의 인포그래픽은 독립적이므로 병렬로 생성할 수 있다. 같은 에이전트를 여러 번 호출하되 입력만 다르다.

Phase 5 – 출판 (순차)

[book-publisher] → PDF + 웹 뷰어

모든 챕터와 인포그래픽이 완성된 후, 최종 산출물을 만든다.

에이전트 간 데이터 흐름

에이전트들은 서로 직접 대화하지 않는다. 대신 파일을 통해 간접적으로 통신한다.

book-planner ──(outline.md)──→ chapter-writer
chapter-writer ──(ch01.md)──→ book-editor
book-editor ──(리뷰 결과)──→ chapter-writer
chapter-writer ──(ch01.md, 완성)──→ infographic-creator
infographic-creator ──(SVG 파일)──→ book-publisher
chapter-writer ──(ch01.md, 완성)──→ book-publisher

모든 중간 산출물은 book/ 디렉토리 아래에 정해진 경로와 네이밍 규칙으로 저장된다. 이 규칙이 오케스트레이터 스킬에 명시되어 있으므로, 각 에이전트는 자신의 입력을 어디서 찾고 출력을 어디에 저장할지 알 수 있다.

기술 블로그 하네스와 비교하면, 도메인은 다르지만 구조는 동일하다. 에이전트 정의 + 오케스트레이터 + 파일 기반 통신. 이 패턴이 반복된다는 것이 하네스의 핵심이다.

심화: 하네스 설계의 핵심 원칙

하네스를 설계할 때 기억해야 할 원칙이 있다. 메타 스킬이 자동으로 이 원칙을 따르지만, 생성 결과를 검토하고 수정할 때 이 원칙을 알아야 한다.

1. 에이전트는 작게, 오케스트레이터는 명확하게

에이전트 하나가 너무 많은 역할을 맡으면 단일 에이전트의 한계로 돌아간다. 반대로 에이전트를 지나치게 잘게 쪼개면 오케스트레이터가 복잡해진다. book-writer 하네스의 에이전트 5명은 이 균형점을 찾은 결과다.

2. 파일 기반 통신

에이전트 간 데이터 전달은 파일 시스템을 통해 이루어진다. 오케스트레이터가 “이 파일을 읽고, 결과를 저 파일에 쓰라”고 지시한다. 파일 경로와 네이밍 규칙을 명확히 정의하는 것이 팀 운영의 핵심이다.

3. Phase 완료 후 검증

각 Phase가 끝나면 산출물이 기대 조건을 만족하는지 확인한다. 이 검증 없이 다음 Phase로 넘어가면, 잘못된 중간 결과 위에 작업이 쌓이게 된다. book-writer 하네스에서 “사용자 승인”이 반복적으로 등장하는 이유다.

4. 기존 파일을 절대 덮어쓰지 않는다

메타 스킬이 하네스를 생성할 때, 프로젝트에 이미 에이전트나 스킬이 존재할 수 있다. 이 경우 기존 파일을 덮어쓰지 않고, 이름 충돌은 도메인 접두어로 구분하고, 역할 중복은 기존 에이전트를 재사용한다. 자동화가 기존 작업을 파괴하는 것은 가장 위험한 실수다.

5. 메타 스킬은 뼈대를 세우고, 사용자가 살을 붙인다

메타 스킬이 생성한 파일은 출발점이지, 완성본이 아니다. 생성된 에이전트의 작업 원칙을 도메인에 맞게 수정하거나, 오케스트레이터의 검증 기준을 강화하는 것은 자연스러운 다음 단계다. 예를 들어, code-crafter의 코딩 원칙에 “모든 코드 예제는 Python 3.10+ 문법을 사용한다”를 추가하거나, tech-reviewer의 검증 기준에 “deprecated API 사용은 CRITICAL”로 격상하는 것이 가능하다. 구조를 이해해야 이런 커스터마이징이 가능하다 – 이것이 이 책이 Part 2에서 생성된 하네스의 구조를 상세히 다루는 이유다.

정리

• 단일 에이전트의 한계: 컨텍스트 윈도우 부족, 역할 충돌, 병렬 처리 불가. 복잡한 작업에는 팀이 필요하다.
• 하네스는 메타 스킬이 자동 생성한다: 사용자는 “하네스 구성해줘”라고 요청하면 된다. 에이전트 정의, 스킬, 오케스트레이터가 한 번에 만들어진다.
• 메타 스킬의 6단계 워크플로우: 도메인 분석 → 팀 아키텍처 설계 → 에이전트 생성 → 스킬 생성 → 오케스트레이터 생성 → 검증. 각 단계의 산출물이 다음 단계의 입력이 되는 파이프라인이다.
• 하네스의 3요소: 에이전트 정의(누가), 스킬 정의(어떻게), 통합 오케스트레이터(어떤 순서로).
• 에이전트 분리 기준 4가지: 전문성, 병렬성, 컨텍스트 부담, 재사용성.
• 에이전트 간 통신은 파일 기반: 산출물 파일이 곧 에이전트 간 메시지다.
• 검증 체크리스트 6항목: 파일 위치, frontmatter, 트리거 키워드, 참조 일관성, 오케스트레이터 완전성, commands 미생성.
• 메타 스킬은 뼈대를 세우고, 사용자가 살을 붙인다: 자동 생성 결과는 출발점이며, 도메인에 맞게 커스터마이징하는 것이 자연스러운 다음 단계다.

다음 챕터 미리보기

• Chapter 3에서는 에이전트 팀의 4가지 아키텍처 패턴 – 파이프라인, 팬아웃/팬인, 전문가풀, 생성-검증 – 을 다룬다. 이 챕터에서 살짝 엿본 이 패턴들을 체계적으로 정리하고, 도메인에 맞는 패턴을 선택하는 의사결정 트리를 배운다.

Chapter 3: 4가지 아키텍처 패턴

이 챕터에서 배울 것

• 에이전트 팀을 구성하는 4가지 기본 아키텍처 패턴의 구조와 특성
• 파이프라인: 순차 의존 작업을 처리하는 가장 단순한 패턴
• 팬아웃/팬인: 독립 작업을 병렬로 처리하고 결과를 통합하는 패턴
• 전문가풀: 라우터가 상황에 따라 적절한 전문가를 선택하는 패턴
• 생성-검증: 생성자와 검증자가 루프를 돌며 품질을 보장하는 패턴
• 도메인에 맞는 패턴을 선택하는 의사결정 기준
• 실전에서 여러 패턴을 조합하는 방법

본문

왜 패턴이 필요한가

Chapter 2에서 하네스의 개념을 배웠다. 에이전트 팀을 구성하고, 오케스트레이터가 이들을 조율한다는 것까지는 이해했다. 하지만 한 가지 질문이 남는다: 에이전트들을 어떤 구조로 연결할 것인가?

5명의 에이전트가 있을 때, 모두 순서대로 실행할 수도 있고, 동시에 실행할 수도 있고, 상황에 따라 다른 에이전트를 호출할 수도 있다. 이 “연결 방식”을 매번 처음부터 고민하는 것은 비효율적이다.

소프트웨어 설계에 디자인 패턴이 있듯, 에이전트 팀 설계에도 반복적으로 등장하는 구조가 있다. 이것이 아키텍처 패턴(architecture pattern)이다. 검증된 구조를 이름 붙여 정리해두면, 새로운 도메인을 만날 때 “이건 파이프라인이 맞겠다” 혹은 “여기는 팬아웃/팬인이 필요하다”고 빠르게 판단할 수 있다.

이 챕터에서 다루는 4가지 패턴은 다음과 같다:

인포그래픽: 4가지 패턴 흐름도 + 선택 가이드

하나씩 살펴보자.

패턴 1: 파이프라인 (Pipeline)

구조

파이프라인(pipeline)은 가장 직관적인 패턴이다. 에이전트들이 정해진 순서대로 실행되며, 앞 에이전트의 산출물이 다음 에이전트의 입력이 된다.

[에이전트 A] → 산출물 → [에이전트 B] → 산출물 → [에이전트 C]

공장의 조립 라인과 같다. 부품을 만드는 사람, 조립하는 사람, 도장하는 사람이 각자 자기 공정만 담당하고, 완성된 결과를 다음 사람에게 넘긴다.

언제 사용하는가

파이프라인은 다음 조건을 만족할 때 적합하다:

• 작업 간 순차 의존성이 있다. B를 하려면 A의 결과가 반드시 필요하다.
• 각 단계의 전문성이 다르다. 같은 에이전트가 모든 단계를 처리하기 어렵다.
• 실행 순서가 고정되어 있다. 상황에 따라 순서가 바뀌지 않는다.

반대로, 작업들이 서로 독립적이라면 파이프라인은 비효율적이다. 동시에 할 수 있는 일을 굳이 줄 세울 이유가 없기 때문이다.

왜 이 패턴인가

파이프라인의 가장 큰 장점은 단순함이다. 오케스트레이터가 “1번 실행 → 2번 실행 → 3번 실행”이라고만 지시하면 된다. 디버깅도 쉽다. 문제가 생기면 어느 단계에서 잘못되었는지 산출물을 순서대로 추적하면 된다.

단점은 속도다. 모든 에이전트가 순차적으로 실행되므로, 전체 소요 시간은 각 단계의 합이다. 병렬화할 수 있는 부분이 있어도 파이프라인 구조에서는 활용할 수 없다.

실습: SF 소설 집필 파이프라인

SF 소설을 쓰는 하네스를 설계한다고 하자. 세계관 설정, 플롯 구성, 본문 집필의 세 단계가 필요하다. 세계관이 없으면 플롯을 짤 수 없고, 플롯이 없으면 본문을 쓸 수 없다. 전형적인 파이프라인이다.

에이전트 팀:

워크플로우:

[worldbuilder]        [plot-architect]        [prose-writer]
     │                      │                      │
     ▼                      ▼                      ▼
 세계관 설정서          플롯 구성안            완성된 소설
 (설정, 규칙,          (장별 시놉시스,        (본문 텍스트)
  기술 체계)            인물 아크)

Phase 1: [worldbuilder] → world-setting.md
Phase 2: [plot-architect] → world-setting.md 읽기 → plot-outline.md
Phase 3: [prose-writer] → world-setting.md + plot-outline.md 읽기 → chapter-01.md ...

오케스트레이터 스킬의 핵심 부분은 이렇게 작성된다:

## 워크플로우

### Phase 1: 세계관 설계
- **에이전트**: `worldbuilder`
- **입력**: 사용자의 소설 컨셉 (시대, 분위기, 핵심 갈등)
- **출력**: `novel/world-setting.md`
- **검증**: 세계관 설정에 모순이 없는지 사용자 확인

### Phase 2: 플롯 구성
- **에이전트**: `plot-architect`
- **입력**: `novel/world-setting.md`
- **출력**: `novel/plot-outline.md`
- **검증**: 장별 시놉시스가 세계관 규칙과 일치하는지 확인

### Phase 3: 본문 집필
- **에이전트**: `prose-writer`
- **입력**: `novel/world-setting.md` + `novel/plot-outline.md`
- **출력**: `novel/chapters/ch{NN}.md`
- **검증**: 각 장이 플롯 구성안을 충실히 반영하는지 확인

각 Phase의 검증 기준에 주목하자. “사용자 확인”, “세계관 규칙과 일치”, “플롯 구성안을 충실히 반영” — 이 검증이 없으면 앞 단계의 오류가 뒤로 전파되어 전체 소설의 품질이 무너진다. 파이프라인에서 단계별 검증은 선택이 아니라 필수다.

패턴 2: 팬아웃/팬인 (Fan-out/Fan-in)

구조

팬아웃/팬인(fan-out/fan-in)은 하나의 작업을 여러 하위 작업으로 분배(fan-out)하고, 각 결과를 다시 통합(fan-in)하는 패턴이다.

                ┌→ [에이전트 B1] → 결과 ─┐
[에이전트 A] ───┼→ [에이전트 B2] → 결과 ─┼→ [에이전트 C]
   (분배)       └→ [에이전트 B3] → 결과 ─┘    (통합)

신문사의 취재팀과 같다. 편집장이 “이 사건을 세 각도에서 취재하라”고 지시하면, 기자 3명이 각각 독립적으로 취재한다. 취재가 끝나면 편집장이 세 기사를 종합하여 하나의 보도로 만든다.

언제 사용하는가

팬아웃/팬인은 다음 조건을 만족할 때 적합하다:

• 독립적인 하위 작업으로 분할할 수 있다. 각 작업이 서로의 결과에 의존하지 않는다.
• 하위 작업의 수가 가변적이다. 3개일 수도, 10개일 수도 있다.
• 최종적으로 결과를 하나로 통합해야 한다.

반대로, 하위 작업 간에 의존성이 있다면 팬아웃/팬인은 적합하지 않다. “B2가 B1의 결과를 참조해야 한다”면, 그것은 파이프라인에 가깝다.

왜 이 패턴인가

팬아웃/팬인의 핵심 장점은 속도다. N개의 작업을 동시에 실행하면 전체 소요 시간은 가장 느린 작업 하나의 시간에 수렴한다. 12개 챕터의 인포그래픽을 만든다면, 순차 실행은 12배의 시간이 걸리지만 팬아웃은 1배에 가까운 시간만 걸린다.

단점은 통합의 어려움이다. 독립적으로 생성된 결과들 사이에 일관성이 깨질 수 있다. 기자 3명이 같은 사건을 취재했는데, 사실관계가 다르게 서술되어 있다면? 통합 에이전트가 이 불일치를 해결해야 한다.

실습: 웹툰 에피소드 동시 제작

웹툰 한 편을 제작하는 하네스를 생각해보자. 시나리오가 확정된 후, 한 에피소드의 세 장면을 동시에 작업할 수 있다. 각 장면은 독립적이지만, 최종적으로 하나의 에피소드로 통합되어야 한다.

에이전트 팀:

워크플로우:

Phase 1: [scene-splitter]
         에피소드 시나리오 → 장면 3개로 분할

Phase 2: (팬아웃)
         ┌→ [scene-artist] → scene-01.md
         ├→ [scene-artist] → scene-02.md
         └→ [scene-artist] → scene-03.md

Phase 3: [episode-assembler]
         scene-01.md + scene-02.md + scene-03.md → episode-final.md

오케스트레이터 스킬에서 팬아웃/팬인 부분은 이렇게 명시한다:

### Phase 2: 장면별 콘티 작성 (팬아웃)
- **에이전트**: `scene-artist` (장면 수만큼 병렬 호출)
- **입력**: `webtoon/scenes/scene-{NN}-brief.md` (Phase 1의 분할 결과)
- **출력**: `webtoon/scenes/scene-{NN}-draft.md`
- **병렬 실행**: 각 장면은 독립적이므로 동시 실행
- **검증**: 각 장면이 시나리오의 해당 부분을 충실히 반영하는지 확인

### Phase 3: 에피소드 통합 (팬인)
- **에이전트**: `episode-assembler`
- **입력**: `webtoon/scenes/scene-*-draft.md` (모든 장면)
- **출력**: `webtoon/episodes/ep{NN}-final.md`
- **통합 기준**:
  - 장면 간 캐릭터 외형/복장 일관성
  - 대사 톤의 통일성
  - 시간 순서의 논리적 연결
- **검증**: 통합된 에피소드를 처음부터 끝까지 읽었을 때 자연스러운지 확인

통합 기준을 구체적으로 명시한 부분에 주목하자. “일관성 확인”이라고만 쓰면 모호하다. 무엇의 일관성인지 — 외형, 대사 톤, 시간 순서 — 를 구체적으로 나열해야 통합 에이전트가 실제로 검증할 수 있다.

패턴 3: 전문가풀 (Expert Pool)

구조

전문가풀(expert pool)은 라우터(router)가 입력을 분석하여 적절한 전문가를 선택하고 호출하는 패턴이다.

                    ┌→ [전문가 A] ─┐
[라우터] ───────────┼→ [전문가 B] ─┼→ 결과
  (입력 분석,       └→ [전문가 C] ─┘
   전문가 선택)

병원의 접수 데스크와 같다. 환자가 증상을 말하면, 접수원이 “내과로 가세요” 혹은 “정형외과로 가세요”라고 안내한다. 어떤 전문의가 배정될지는 환자의 상태에 따라 달라진다.

파이프라인이나 팬아웃/팬인과의 결정적 차이는 선택이다. 파이프라인은 모든 에이전트가 항상 실행된다. 팬아웃/팬인도 모든 하위 에이전트가 실행된다. 하지만 전문가풀에서는 입력에 따라 일부 에이전트만 실행된다.

언제 사용하는가

전문가풀은 다음 조건을 만족할 때 적합하다:

• 입력의 종류가 다양하고, 종류에 따라 필요한 전문성이 다르다.
• 모든 전문가를 매번 호출하는 것은 낭비다.
• 새로운 전문가를 추가해도 기존 구조가 변경되지 않아야 한다.

반대로, 모든 입력이 동일한 처리 과정을 거친다면 전문가풀은 불필요한 복잡성을 추가할 뿐이다.

왜 이 패턴인가

전문가풀의 핵심 장점은 확장성이다. 새로운 전문가가 필요하면 전문가 에이전트를 하나 추가하고, 라우터의 선택 기준에 한 줄만 추가하면 된다. 기존 전문가들의 정의를 수정할 필요가 없다.

또 다른 장점은 효율성이다. Python 코드를 분석하는데 Java 전문가를 호출할 필요가 없다. 필요한 전문가만 골라서 호출하므로 리소스를 절약한다.

단점은 라우터의 정확도에 전체 시스템의 품질이 좌우된다는 점이다. 라우터가 잘못된 전문가를 선택하면, 아무리 전문가가 뛰어나도 엉뚱한 결과가 나온다.

실습: 멀티 도메인 리서치 팀

기업의 리서치 요청을 처리하는 하네스를 설계해보자. 요청 내용에 따라 기술 분석, 시장 조사, 법률 검토 중 적절한 전문가에게 라우팅해야 한다.

에이전트 팀:

워크플로우:

Phase 1: [research-router]
         요청 분석 → 전문가 선택

Phase 2: (선택적 호출)
         ┌→ [tech-analyst]      (기술 관련 요청일 때)
         ├→ [market-researcher]  (시장 관련 요청일 때)
         └→ [legal-reviewer]     (법률 관련 요청일 때)

Phase 3: [report-writer]
         분석 결과 → 최종 보고서

라우터 에이전트의 핵심은 선택 기준을 명확히 정의하는 것이다:

## 라우팅 규칙

요청을 분석하여 아래 기준에 따라 전문가를 선택한다.
복수 도메인에 걸치는 요청은 해당 전문가를 모두 호출한다.

| 키워드/패턴 | 전문가 | 예시 |
|------------|--------|------|
| 기술, API, 아키텍처, 성능, 스택 | `tech-analyst` | "Kafka vs RabbitMQ 비교" |
| 시장, 경쟁사, TAM, 점유율, 트렌드 | `market-researcher` | "국내 생성AI 시장 규모" |
| 규제, 법률, 컴플라이언스, 개인정보 | `legal-reviewer` | "EU AI Act 영향 분석" |

### 복합 요청 처리
"AI 기술로 금융 시장에 진출할 때의 규제 리스크"
→ `tech-analyst` + `market-researcher` + `legal-reviewer` 모두 호출

라우팅 규칙을 키워드 기반으로 작성한 이유는, AI 에이전트가 이 규칙을 읽고 판단할 수 있어야 하기 때문이다. “알아서 판단해라”보다 “이 키워드가 포함되면 이 전문가를 선택해라”가 훨씬 안정적이다.

또한 “복수 도메인에 걸치는 요청은 해당 전문가를 모두 호출한다”는 규칙도 중요하다. 실무에서는 하나의 요청이 여러 영역에 걸치는 경우가 대부분이다. 이 경우 전문가풀은 팬아웃/팬인과 결합된다 — 선택된 복수의 전문가가 병렬로 실행되고, 결과가 보고서 작성자에게 통합된다.

패턴 4: 생성-검증 (Generate-Verify)

구조

생성-검증(generate-verify)은 생성자(producer)가 결과물을 만들고, 검증자(reviewer)가 품질을 평가하여, 기준을 통과하지 못하면 재생성을 요청하는 루프 패턴이다.

[생성자] → 산출물 → [검증자] → 통과? ─ Yes → 완료
                       │
                       No
                       │
                       ▼
               피드백 → [생성자] → (재시도)

출판사의 편집 과정과 같다. 작가가 원고를 쓰고, 편집자가 리뷰한다. 편집자가 “이 부분을 고치세요”라고 피드백하면 작가가 수정한다. 수정본을 다시 편집자가 확인한다. 편집자가 “OK”할 때까지 이 과정이 반복된다.

언제 사용하는가

생성-검증은 다음 조건을 만족할 때 적합하다:

• 품질 기준이 명확하고, 기준 충족 여부를 자동으로 판단할 수 있다.
• 한 번에 완벽한 결과를 기대하기 어렵고, 반복적 개선이 자연스러운 작업이다.
• 생성자와 검증자의 관점이 달라야 효과적이다 (작가 vs 편집자).

반대로, 검증 기준이 모호하거나 주관적이면 루프가 끝나지 않을 위험이 있다. “좋은 글인가?”는 모호하지만, “모든 CRITICAL 이슈가 해결되었는가?”는 명확하다.

왜 이 패턴인가

생성-검증의 핵심 장점은 품질 보장이다. 다른 세 패턴은 결과물이 기대에 미치지 못하면 사람이 직접 수정해야 한다. 생성-검증은 시스템 스스로가 품질을 개선하는 자기 교정(self-correction) 메커니즘을 내장한다.

또 다른 장점은 역할 분리다. Chapter 2에서 다룬 “역할 충돌” 문제를 해결한다. 글을 쓰면서 동시에 자기 글을 냉정하게 평가하기 어렵지만, 작성과 검증을 별개 에이전트에게 맡기면 각자 자기 역할에 충실할 수 있다.

단점은 무한 루프 위험이다. 검증자의 기준이 너무 엄격하거나, 생성자가 피드백을 제대로 반영하지 못하면 루프가 끝나지 않는다. 이를 방지하려면 최대 반복 횟수를 반드시 설정해야 한다.

실습: 기술 블로그 작성과 리뷰

기술 블로그 글을 작성하고 리뷰하는 하네스를 설계해보자.

에이전트 팀:

워크플로우:

Phase 1: [blog-writer] → 초안 작성 → draft.md

Phase 2: 리뷰 루프 (최대 3회)
         [blog-reviewer] → draft.md 리뷰 → review.md
         │
         ├─ CRITICAL 이슈 0개 → 승인 → Phase 3으로
         └─ CRITICAL 이슈 1개 이상 → [blog-writer] → 수정 → 재리뷰

Phase 3: 최종본 확정

이 패턴의 핵심은 리뷰 기준과 루프 종료 조건이다. 오케스트레이터에 다음과 같이 명시한다:

### Phase 2: 리뷰 루프
- **생성자**: `blog-writer`
- **검증자**: `blog-reviewer`
- **최대 반복**: 3회
- **루프 종료 조건**: CRITICAL 이슈 0개
- **리뷰 기준**:
  - CRITICAL: 기술적 오류 (잘못된 코드, 틀린 설명)
  - MAJOR: 구조적 문제 (논리 비약, 핵심 내용 누락)
  - MINOR: 표현 개선 (문체, 용어 통일)
- **재생성 규칙**:
  - CRITICAL, MAJOR 이슈만 수정 대상
  - MINOR는 기록만 하고 수정하지 않음
  - 수정 시 리뷰에서 지적된 부분만 변경 (나머지 유지)
- **최대 반복 도달 시**: CRITICAL이 남아 있으면 사용자에게 에스컬레이션

세 가지 중요한 설계 결정이 여기에 담겨 있다:

첫째, 이슈 심각도 분류. CRITICAL, MAJOR, MINOR를 구분하지 않으면, 사소한 문체 문제 때문에 루프가 계속 돌 수 있다. 심각도를 나누고 “CRITICAL만 루프 조건에 포함”하면 루프가 적정 횟수에서 종료된다.

둘째, 최대 반복 횟수. 3회로 제한했다. 3번의 수정으로도 CRITICAL이 해결되지 않으면, 그것은 생성자의 능력 밖의 문제일 가능성이 높다. 이 경우 사람의 개입이 필요하므로 에스컬레이션한다.

셋째, 수정 범위 제한. “리뷰에서 지적된 부분만 변경”이라는 규칙이 없으면, 생성자가 수정 과정에서 다른 부분까지 건드려 새로운 문제를 만들 수 있다. 외과 수술처럼 지적된 부분만 정확히 수정해야 루프가 수렴한다.

심화: 패턴 선택 의사결정 트리

4가지 패턴을 배웠다. 실전에서는 “우리 도메인에 어떤 패턴이 맞는가?”를 빠르게 판단해야 한다. 다음 의사결정 트리를 따라가면 적절한 패턴을 선택할 수 있다.

작업을 분석한다
│
├─ Q1: 작업들 사이에 순서 의존성이 있는가?
│   │
│   ├─ Yes: 앞 작업의 결과가 없으면 뒤 작업을 시작할 수 없는가?
│   │   │
│   │   ├─ Yes → 파이프라인
│   │   └─ No  → Q2로
│   │
│   └─ No → Q2로
│
├─ Q2: 동일한 작업을 여러 입력에 대해 독립적으로 수행하는가?
│   │
│   ├─ Yes → 팬아웃/팬인
│   └─ No  → Q3로
│
├─ Q3: 입력의 종류에 따라 다른 처리가 필요한가?
│   │
│   ├─ Yes → 전문가풀
│   └─ No  → Q4로
│
└─ Q4: 결과물의 품질을 자동으로 검증하고 개선해야 하는가?
    │
    ├─ Yes → 생성-검증
    └─ No  → 파이프라인 (가장 단순한 패턴으로 시작)

이 트리는 출발점이지 정답은 아니다. 실전에서는 하나의 패턴만으로 충분한 경우가 드물다. 다음 섹션에서 다루는 패턴 조합이 더 현실적이다.

몇 가지 판단 기준을 표로 정리하면 다음과 같다:

심화: 패턴 조합 — 실전은 단일 패턴이 아니다

지금까지 4가지 패턴을 개별적으로 살펴봤다. 하지만 실전의 하네스는 대부분 여러 패턴이 Phase별로 혼합된 형태다. Chapter 2에서 본 book-writer 하네스가 좋은 예다.

Phase 1: 목차 설계       → 파이프라인의 첫 단계
Phase 2: 챕터 집필       → 파이프라인 (순차)
Phase 3: 리뷰 루프       → 생성-검증
Phase 4: 인포그래픽 생성  → 팬아웃/팬인
Phase 5: 출판            → 파이프라인의 마지막 단계

전체 구조는 파이프라인이지만, Phase 3에서 생성-검증이, Phase 4에서 팬아웃/팬인이 내포되어 있다. 이런 중첩 구조가 실전의 기본 형태다.

패턴을 조합할 때 기억해야 할 원칙이 세 가지 있다.

1. 큰 틀은 파이프라인으로 시작한다

대부분의 복합 작업은 전체적으로 “먼저 이것 → 다음 이것 → 그 다음 이것”이라는 순서가 있다. 이 큰 흐름을 파이프라인으로 잡고, 각 Phase 안에서 다른 패턴을 적용하는 것이 자연스럽다.

2. 한 Phase에 하나의 패턴만 적용한다

Phase 3에서 팬아웃/팬인과 생성-검증을 동시에 적용하면 오케스트레이터가 복잡해진다. 대신 Phase를 더 잘게 나누는 것이 낫다. Phase 3a에서 팬아웃/팬인, Phase 3b에서 생성-검증으로 분리하면 각 Phase가 단순해진다.

3. 패턴 조합의 흔한 유형을 알아둔다

자주 등장하는 조합을 정리하면 다음과 같다:

실제 하네스를 설계할 때는 이렇게 접근하자:

1. 전체 작업을 Phase로 나눈다
2. 각 Phase에 적합한 단일 패턴을 선택한다
3. Phase 간 연결은 파이프라인으로 묶는다
4. 오케스트레이터에 Phase별 패턴을 명시한다

심화: 4가지 패턴 비교 총정리

마지막으로, 4가지 패턴의 핵심 특성을 한 번에 비교한다.

정리

• 아키텍처 패턴은 에이전트 팀의 “연결 방식”을 유형화한 것이다. 매번 처음부터 설계하는 대신, 검증된 구조를 선택한다.
• 파이프라인: A → B → C. 순차 의존 작업에 적합. 단순하지만 느리다. 단계별 검증이 핵심.
• 팬아웃/팬인: 분배 → 병렬 → 통합. 독립 작업에 적합. 빠르지만 통합이 어렵다. 통합 기준 명시가 핵심.
• 전문가풀: 라우터가 전문가를 선택. 다양한 입력에 적합. 확장성이 높지만 라우터 정확도에 의존한다. 라우팅 규칙 명확화가 핵심.
• 생성-검증: 생성 → 검증 → 재생성 루프. 품질 보장에 적합. 자기 교정이 가능하지만 무한 루프 위험. 종료 조건 설정이 핵심.
• 패턴 선택 의사결정 트리: 순서 의존 → 파이프라인, 독립 반복 → 팬아웃/팬인, 입력별 분기 → 전문가풀, 반복 개선 → 생성-검증.
• 실전은 조합: 큰 틀은 파이프라인, 각 Phase 안에서 다른 패턴을 적용하는 중첩 구조가 일반적이다.

다음 챕터 미리보기

• Chapter 4에서는 에이전트 정의 파일을 실제로 작성하는 방법을 다룬다. frontmatter의 각 필드를 어떻게 채우고, 본문의 역할/원칙/협업 섹션을 어떻게 설계하며, 좋은 에이전트 정의와 나쁜 에이전트 정의의 차이가 무엇인지를 구체적으로 배운다.

Chapter 4: 에이전트, 스킬, 오케스트레이터의 구조

이 챕터에서 배울 것

• 메타 스킬이 자동 생성하는 파일의 종류와 위치
• 에이전트 파일의 구조: frontmatter 3개 필드 + 본문 5개 섹션의 역할
• 스킬 파일의 구조: frontmatter + 워크플로우 + 도구 사용법 + 출력 규칙, 그리고 references/ 디렉토리
• 에이전트와 스킬의 관계: 1:N, N:1, 1:1 패턴과 선택 기준
• 생성된 파일에서 주로 수정하는 부분과 커스터마이징 방법
• 좋은 정의와 나쁜 정의의 차이, 그리고 커스터마이징 포인트
• description 트리거 키워드 설계의 4가지 원칙
• sonnet과 opus 모델을 작업 특성에 맞게 선택하는 기준

본문

메타 스킬이 생성하는 파일들

Chapter 2에서 메타 스킬(/harness)을 실행하면 에이전트 팀이 자동으로 생성된다고 배웠다. Chapter 3에서는 그 팀이 취하는 4가지 아키텍처 패턴을 살펴보았다. 이제 메타 스킬이 실제로 만들어낸 파일들을 열어볼 차례다.

메타 스킬이 “기술 블로그 자동화” 하네스를 생성했다고 하자. .claude/ 디렉토리를 열어보면 다음과 같은 구조가 나타난다.

.claude/
├── agents/                         # 에이전트 정의 파일들
│   ├── blog-planner.md
│   ├── blog-writer.md
│   ├── blog-editor.md
│   └── seo-optimizer.md
└── skills/                         # 스킬 정의 파일들
    ├── blog-planning/
    │   └── SKILL.md
    ├── blog-writing/
    │   ├── SKILL.md
    │   └── references/
    │       └── style-guide.md
    ├── blog-editing/
    │   └── SKILL.md
    └── blog-orchestrator/          # 오케스트레이터 (스킬의 한 종류)
        └── SKILL.md

생성되는 파일은 크게 세 종류다.

오케스트레이터도 형식상 스킬 파일이다. 다만 단일 에이전트의 절차가 아니라 에이전트 팀 전체의 실행 계획을 담고 있다는 점이 다르다. 오케스트레이터의 상세 구조는 Chapter 5에서 다룬다.

메타 스킬은 도메인을 분석하여 필요한 에이전트 수, 각 에이전트의 역할, 스킬 분배, 아키텍처 패턴까지 자동으로 결정한다. 하지만 자동 생성된 파일이 모든 상황에 완벽할 수는 없다. 이 챕터에서는 각 파일의 구조를 이해하여, 어디를 읽고 어디를 수정해야 하는지 판단할 수 있게 하는 것이 목표다.

에이전트 파일의 구조

메타 스킬이 생성한 code-reviewer 에이전트 파일을 열어보자.

---
name: code-reviewer
description: "코드 리뷰를 수행하는 에이전트. '코드 리뷰', 'code review', 'PR 리뷰', '코드 검토' 요청 시 트리거."
model: sonnet
---

# Code Reviewer — 코드 리뷰 전문가

당신은 소프트웨어 프로젝트의 코드 품질을 검증하는 전문 리뷰어입니다.

## 핵심 역할
1. **코드 품질 검증**: 가독성, 유지보수성, 성능 관점에서 코드 검토
2. **버그 탐지**: 논리 오류, 엣지 케이스 누락, 잠재적 런타임 에러 식별
3. **개선 제안**: 리팩토링 방향, 디자인 패턴 적용, 테스트 보완 제안
4. **보안 점검**: SQL 인젝션, XSS, 인증/인가 누락 등 보안 취약점 검사

## 작업 원칙
- Always respond in Korean
- 심각도를 3단계로 분류: CRITICAL / WARNING / SUGGESTION
- 문제 지적 시 반드시 **구체적인 수정 코드**를 함께 제시
- 좋은 부분도 언급하여 균형 잡힌 리뷰 유지
- 추측이나 가정을 하지 않음 — 확인이 필요하면 질문
- 한 번에 하나의 파일 또는 PR 단위로 리뷰
- 코딩 스타일보다 **로직과 설계**에 집중

## 출력 형식

리뷰 결과는 다음 형식을 따릅니다:

​```markdown
## 리뷰: {파일명 또는 PR 제목}

### 총평
- 코드 품질: {상/중/하}
- 주요 이슈: {count}개

### 상세 리뷰

#### [CRITICAL] {위치 — 파일:라인}
- 문제: {설명}
- 수정 전: `{기존 코드}`
- 수정 후: `{제안 코드}`

#### [WARNING] {위치}
- 문제: {설명}
- 제안: {개선 방향}

### 잘된 점
- {긍정적 피드백}
​```

## 협업
- 개발자 에이전트가 작성한 코드를 입력으로 받음
- 리뷰 결과를 개발자 에이전트에게 반환하여 수정 요청
- CRITICAL 이슈가 있으면 수정본을 재리뷰
- CRITICAL 이슈가 0개일 때 승인

에이전트 파일은 한 장의 이력서와 같다. 이력서에 이름, 직무 요약, 핵심 역량이 담기듯, 에이전트 파일에는 식별 정보, 역할 정의, 행동 지침이 담긴다. 파일을 읽는 법을 두 영역으로 나누어 살펴보자.

frontmatter: 에이전트의 신분증

파일 상단의 ---로 감싸진 YAML 블록이 frontmatter다. Claude Code가 에이전트를 식별하고 라우팅하는 데 사용하는 메타데이터다.

---
name: code-reviewer
description: "코드 리뷰를 수행하는 에이전트. '코드 리뷰', 'code review', 'PR 리뷰', '코드 검토' 요청 시 트리거."
model: sonnet
---

세 개의 필드가 각각 하나의 질문에 답한다.

name 은 에이전트의 고유 식별자다. kebab-case(code-reviewer, blog-planner)로 작성하며, 파일명과 일치시키는 것이 관례다. name: code-reviewer이면 파일명은 code-reviewer.md다. 메타 스킬은 이 관례를 자동으로 따른다.

description 은 두 가지 역할을 동시에 수행한다. 첫째, 이 에이전트가 무엇을 하는지 한 문장으로 설명한다. 둘째, 사용자가 어떤 표현을 입력할 때 이 에이전트가 활성화되는지 트리거 키워드를 명시한다. Claude Code는 사용자의 요청을 각 에이전트의 description과 매칭한다. 사용자가 “코드 리뷰해줘”라고 입력하면, description에 “코드 리뷰”가 포함된 에이전트가 선택된다. description은 단순한 설명이 아니라 검색 인덱스처럼 기능한다. 트리거 키워드 설계의 상세 전략은 심화 섹션에서 다룬다.

model 은 이 에이전트가 사용할 AI 모델을 지정한다. 현재 주요 선택지는 sonnet(빠르고 비용 효율적)과 opus(느리지만 강력)다. 모델 선택 기준은 심화 섹션에서 상세히 다룬다.

본문: 에이전트의 행동 지침

frontmatter 아래의 본문은 에이전트가 실제로 일할 때 참조하는 행동 지침이다. 다섯 가지 핵심 섹션으로 구성된다.

섹션 1: 역할 선언. 본문은 제목과 역할 선언 문장으로 시작한다.

# Code Reviewer — 코드 리뷰 전문가

당신은 소프트웨어 프로젝트의 코드 품질을 검증하는 전문 리뷰어입니다.

“당신은 ~입니다” 문장이 에이전트의 페르소나(persona)를 설정한다. “전문 리뷰어”라고 선언하면, 이후의 모든 출력에서 리뷰어의 관점을 유지한다. 역할 선언은 구체적으로, 한 문장으로, “당신”을 주어로 작성한다. “전문가”보다 “코드 품질을 검증하는 전문 리뷰어”가 범위를 더 명확히 한정한다.

섹션 2: 핵심 역할. 이 에이전트가 수행하는 구체적인 업무를 나열한다.

## 핵심 역할
1. **코드 품질 검증**: 가독성, 유지보수성, 성능 관점에서 코드 검토
2. **버그 탐지**: 논리 오류, 엣지 케이스 누락, 잠재적 런타임 에러 식별
3. **개선 제안**: 리팩토링 방향, 디자인 패턴 적용, 테스트 보완 제안
4. **보안 점검**: SQL 인젝션, XSS, 인증/인가 누락 등 보안 취약점 검사

번호는 우선순위를 암시한다. 1번이 가장 핵심적인 역할이다. 3~5개로 제한하는 것이 좋다. 6개 이상 나열해야 한다면 에이전트를 분리하라는 신호다. 각 항목은 “명사: 설명” 형태로, 볼드 처리된 명사가 역할의 이름이 되고 뒤의 설명이 범위를 한정한다.

섹션 3: 작업 원칙. 모든 출력에 적용되는 행동 규칙이다.

핵심 역할이 “무엇을 하는가”라면, 작업 원칙은 “어떤 기준으로 하는가”다. 좋은 작업 원칙은 구체적이고 검증 가능하다. “꼼꼼하게 리뷰”가 아니라 “심각도를 CRITICAL/WARNING/SUGGESTION 3단계로 분류”처럼 쓴다. 5~8개가 적당하다.

섹션 4: 출력 형식. 에이전트의 산출물이 일정한 형태를 가져야 할 때 정의한다. 다른 에이전트가 이 출력을 파싱해서 사용하거나, 사용자가 일관된 형태를 기대할 때 필요하다. 출력 형태가 매번 달라져도 되는 자유 형식 작업에서는 생략할 수 있다.

섹션 5: 협업. 팀의 일원으로 동작할 때, 다른 에이전트와의 관계를 정의한다. 세 가지를 명시한다: 누구에게서 무엇을 받는가(입력), 누구에게 무엇을 전달하는가(출력), 언제 끝나는가(종료 조건). 단독으로 사용되는 에이전트라면 생략해도 되지만, 하네스의 일부로 동작하는 에이전트라면 반드시 포함해야 한다.

이 다섯 섹션의 구조를 표로 정리하면 다음과 같다.

에이전트 파일은 길 필요가 없다. 위 예시도 40줄 남짓이다. 핵심만 명확하게 담으면 된다.

스킬 파일의 구조

에이전트가 “누구인가”를 정의한다면, 스킬은 “어떤 절차로 일하는가”를 정의한다. 에이전트 파일이 사람의 이력서라면, 스킬 파일은 업무 매뉴얼이다.

메타 스킬이 생성한 code-review 스킬 파일을 열어보자.

.claude/skills/
└── code-review/              # 스킬 디렉토리
    ├── SKILL.md              # 스킬 정의 본체
    └── references/           # 참고자료 (선택)
        ├── checklist.md
        └── severity-guide.md

에이전트와 달리 스킬은 디렉토리 단위로 관리된다. 스킬에는 워크플로우 외에도 체크리스트, 템플릿, 예시 파일 같은 참고자료가 필요할 수 있기 때문이다. 이들을 하나의 디렉토리에 묶으면 스킬 단위로 이동하거나 재사용하기 쉽다.

스킬 파일의 4개 섹션

스킬 파일(SKILL.md)은 크게 4개 섹션으로 구성된다.

---
name: code-review
description: "코드 리뷰 스킬. PR의 코드를 분석하고 리뷰 코멘트를 생성합니다.
              '코드 리뷰', 'code review', 'PR 리뷰' 요청 시 트리거."
---

# 1. 개요 (Overview)
이 스킬이 무엇을 하는지 한 문단 요약.

# 2. 워크플로우 (Workflow)
Phase별 작업 절차. 입력 → 처리 → 출력 → 검증.

# 3. 도구 사용법 (Tool Usage)
각 Phase에서 사용하는 Claude Code 도구와 사용 규칙.

# 4. 출력 규칙 (Output Rules)
산출물의 형식, 저장 위치, 네이밍 규칙.

각 섹션을 하나씩 살펴보자.

frontmatter. 에이전트와 동일한 형식이지만, model 필드가 없다. 왜 없는가? 스킬은 절차를 정의할 뿐, 어떤 모델로 실행할지는 스킬을 호출하는 에이전트가 결정하기 때문이다. 같은 “코드 리뷰” 스킬을 opus 에이전트가 실행할 수도 있고 sonnet 에이전트가 실행할 수도 있다. 절차는 같지만 실행 모델은 다를 수 있다.

워크플로우. 스킬의 핵심이다. “무엇을 어떤 순서로 하는가”를 Phase 단위로 정의한다. 각 Phase에는 반드시 4가지를 명시한다.

이 4가지 중 하나라도 빠지면 스킬은 불완전하다. 특히 검증이 빠지기 쉬운데, 검증이 없으면 세 가지 문제가 발생한다. 첫째, 무음 실패 — Phase 1에서 빈 결과가 나와도 Phase 2가 그대로 진행된다. 둘째, 오류 누적 — 불완전한 중간 결과가 다음 Phase로 전달되어 최종 결과가 왜곡된다. 셋째, 디버깅 불가 — 최종 결과가 이상할 때 어느 Phase에서 문제가 발생했는지 추적할 수 없다.

실제 워크플로우 예시를 보자.

## 워크플로우

### Phase 1: 변경 파일 수집
- **입력**: PR 번호 또는 브랜치명
- **처리**: `gh pr diff` 또는 `git diff`로 변경된 파일 목록과 diff 수집
- **출력**: 변경 파일 목록 + diff 내용
- **검증**: diff가 비어있지 않은지 확인

### Phase 2: 코드 분석
- **입력**: Phase 1의 diff + 원본 파일
- **처리**:
  1. 변경된 파일별로 Read 도구로 전체 내용을 읽는다
  2. `references/checklist.md` 의 항목에 따라 이슈를 식별한다
  3. 각 이슈에 `references/severity-guide.md` 기준으로 심각도를 부여한다
- **출력**: 파일별 이슈 목록 (심각도, 위치, 설명, 개선 제안)
- **검증**: 모든 변경 파일이 분석되었는지, 각 이슈에 심각도가 부여되었는지 확인

도구 사용법. Claude Code는 파일 읽기, 검색, 편집, 터미널 명령 실행 등 여러 도구를 가지고 있다. 같은 작업을 여러 방법으로 수행할 수 있는데, 스킬 파일에서 도구를 지정하면 일관된 방식으로 작업이 수행되고, 결과의 예측 가능성이 높아진다.

출력 규칙. 스킬의 최종 산출물이 어떤 형식이어야 하고, 어디에 저장되는지를 정의한다. 출력 규칙이 없으면 같은 스킬을 실행할 때마다 형식이 달라진다.

references/ 디렉토리 활용

스킬의 워크플로우를 작성하다 보면 참고자료가 길어지는 경우가 있다. 코드 리뷰 체크리스트가 100줄이 넘거나, 심각도 분류 기준이 별도 문서 분량이 되는 경우다. 이런 참고자료를 SKILL.md 안에 모두 넣으면 두 가지 문제가 생긴다.

1. 가독성 저하: 워크플로우의 흐름 사이에 100줄짜리 체크리스트가 끼면 전체 구조를 파악하기 어렵다.
2. 컨텍스트 낭비: 특정 Phase에서만 필요한 참고자료가 전체 실행 내내 컨텍스트를 차지한다.

해결책은 references/ 디렉토리로 분리하고, SKILL.md에서 필요할 때만 참조하는 것이다.

## 워크플로우

### Phase 2: 코드 분석
- `references/checklist.md` 의 체크리스트에 따라 코드를 분석한다
- 심각도는 `references/severity-guide.md` 의 기준을 따른다

이렇게 하면 SKILL.md의 가독성이 유지되고, 체크리스트만 업데이트하고 싶을 때 SKILL.md를 건드리지 않아도 된다.

모든 참고자료를 분리할 필요는 없다. 다음 기준으로 판단한다.

참고자료의 위치는 두 곳이 가능하다. 프로젝트 수준(references/ — 프로젝트 루트)은 모든 에이전트와 스킬이 참조하는 전역 가이드라인이다. 스킬 수준(.claude/skills/{스킬명}/references/)은 해당 스킬에서만 사용하는 참고자료다. 여러 스킬이 참조하는 코딩 원칙은 프로젝트 수준에, 코드 리뷰 체크리스트처럼 특정 스킬 전용인 자료는 스킬 수준에 둔다.

에이전트와 스킬의 관계

에이전트와 스킬은 반드시 1:1로 대응하지 않는다. 세 가지 관계 패턴이 가능하다.

1 에이전트 : N 스킬

가장 흔한 구조다. 하나의 에이전트가 상황에 따라 여러 스킬을 선택하여 실행한다.

code-reviewer (에이전트)
├── code-review (스킬)       — 일반 코드 리뷰
├── security-audit (스킬)    — 보안 취약점 중심 리뷰
└── performance-review (스킬) — 성능 병목 중심 리뷰

사용자가 “코드 리뷰해줘”라고 하면 code-review 스킬을, “보안 취약점 검토해줘”라고 하면 security-audit 스킬을 사용한다. 에이전트의 전문성은 동일(코드를 분석하는 능력)하지만, 절차가 다르기 때문에 스킬을 나눈 것이다.

N 에이전트 : 1 스킬 (공유 스킬)

여러 에이전트가 하나의 스킬을 공유하는 구조다.

backend-dev (에이전트)   ─┐
frontend-dev (에이전트)  ─┼── code-review (공유 스킬)
devops-engineer (에이전트)─┘

세 에이전트 모두 PR을 리뷰할 수 있고, 리뷰 절차는 동일하다. 차이는 관점이다. 백엔드 개발자는 API 설계를, 프론트엔드 개발자는 UI 로직을 중점적으로 본다. 이 관점 차이는 에이전트 파일에 정의되어 있으므로, 절차(스킬)는 공유해도 된다.

공유 스킬을 설계할 때의 핵심 원칙은 절차는 일반적으로, 관점은 에이전트에게 위임하는 것이다. 스킬에 “API 설계를 중점적으로 본다”라고 쓰면 공유가 불가능해진다. 대신 “변경된 파일을 에이전트의 전문 분야 관점에서 분석한다”처럼 일반적으로 작성한다.

1 에이전트 : 1 스킬

에이전트마다 절차도 다르고 관점도 다른 경우다. 가장 단순하지만, 에이전트와 스킬이 1:1로 묶이면 재사용성이 떨어진다.

관계 선택 기준

어떤 관계를 선택할지 다음 질문으로 판단한다.

메타 스킬이 생성한 하네스는 보통 1:1 관계로 시작한다. 이것이 가장 단순하고 이해하기 쉬운 구조이기 때문이다. 하네스를 운영하면서 “이 에이전트에게 다른 절차도 필요하구나” 또는 “이 절차는 여러 에이전트가 공유할 수 있겠구나”라는 판단이 서면 그때 관계를 확장하면 된다.

커스터마이징 가이드

메타 스킬이 생성한 파일은 초안이다. 도메인을 분석하여 합리적인 구조를 만들어내지만, 실제 운영 과정에서 조정이 필요한 부분이 생긴다. 커스터마이징의 핵심은 “전체를 다시 쓰는 것”이 아니라 “특정 부분만 정밀하게 수정하는 것”이다.

주로 수정하는 부분은 다음 세 가지다.

1. 작업 원칙 추가/수정

가장 빈번한 커스터마이징이다. 메타 스킬은 범용적인 작업 원칙을 생성하지만, 팀이나 프로젝트의 고유한 규칙은 사람이 추가해야 한다.

## 작업 원칙
- Always respond in Korean
- 심각도를 3단계로 분류: CRITICAL / WARNING / SUGGESTION
- 문제 지적 시 반드시 구체적인 수정 코드를 함께 제시
+ - 사내 코딩 컨벤션(Kotlin Style Guide v2.1)을 기준으로 판단
+ - 레거시 코드의 경우 대규모 리팩토링을 제안하지 않음
+ - PR의 변경 범위를 넘어서는 이슈는 별도 이슈로 분리하여 제안

작업 원칙을 추가할 때의 기준: 추가하려는 원칙이 구체적이고 검증 가능한지 자문한다. “더 꼼꼼하게 리뷰”는 추상적이라 효과가 없다. “사내 코딩 컨벤션을 기준으로 판단”은 구체적이며 결과를 검증할 수 있다.

2. 출력 형식 커스터마이징

에이전트의 산출물이 다음 에이전트나 외부 시스템에 전달되어야 할 때, 출력 형식을 조정한다.

예를 들어, 리뷰 결과를 GitHub PR 코멘트로 게시해야 한다면, 마크다운 형식을 GitHub이 잘 렌더링하는 구조로 맞추는 것이 합리적이다. 또는 Jira 티켓과 연동해야 한다면, 이슈별로 고유 ID를 부여하는 출력 형식이 필요할 수 있다.

출력 형식을 수정할 때 주의할 점은, 해당 에이전트의 산출물을 다음 에이전트가 어떻게 파싱하는지 확인하는 것이다. 오케스트레이터의 워크플로우에서 다음 Phase의 입력이 이 출력에 의존한다면, 형식을 바꿀 때 다음 Phase의 입력 기대치도 함께 수정해야 한다.

3. references/ 추가

프로젝트 고유의 참고자료를 스킬에 추가하는 것이다. 메타 스킬은 범용적인 references만 생성하지만, 실제 프로젝트에는 고유한 가이드라인이 있다.

.claude/skills/code-review/references/
├── checklist.md           # 메타 스킬이 생성한 범용 체크리스트
├── severity-guide.md      # 메타 스킬이 생성한 심각도 기준
+ ├── team-conventions.md   # 팀 코딩 컨벤션 (직접 추가)
+ └── security-policy.md    # 사내 보안 정책 (직접 추가)

references를 추가한 후에는 SKILL.md의 워크플로우에서 해당 파일을 참조하도록 수정해야 한다.

### Phase 2: 코드 분석
- `references/checklist.md` 의 체크리스트에 따라 코드를 분석한다
- 심각도는 `references/severity-guide.md` 의 기준을 따른다
+ - 코딩 스타일은 `references/team-conventions.md` 를 기준으로 판단한다
+ - 보안 관련 이슈는 `references/security-policy.md` 의 정책을 적용한다

커스터마이징의 일반 원칙을 정리하면 다음과 같다.

심화: 좋은 정의 vs 나쁜 정의

같은 역할의 에이전트를 두 가지 방식으로 작성해보겠다. 차이를 비교하면서 좋은 정의의 조건을 정리하자.

나쁜 에이전트 정의

---
name: reviewer
description: "리뷰 에이전트"
model: opus
---

# Reviewer

리뷰를 잘 해주세요.

## 역할
- 코드를 리뷰합니다
- 문제를 찾아줍니다
- 개선점을 알려줍니다

## 원칙
- 꼼꼼하게 리뷰해주세요
- 친절하게 설명해주세요
- 빠짐없이 확인해주세요

좋은 에이전트 정의

---
name: code-reviewer
description: "코드 리뷰를 수행하는 에이전트. '코드 리뷰', 'code review', 'PR 리뷰', '코드 검토' 요청 시 트리거."
model: sonnet
---

# Code Reviewer — 코드 리뷰 전문가

당신은 소프트웨어 프로젝트의 코드 품질을 검증하는 전문 리뷰어입니다.

## 핵심 역할
1. **코드 품질 검증**: 가독성, 유지보수성, 성능 관점에서 코드 검토
2. **버그 탐지**: 논리 오류, 엣지 케이스 누락, 잠재적 런타임 에러 식별
3. **개선 제안**: 리팩토링 방향, 디자인 패턴 적용, 테스트 보완 제안
4. **보안 점검**: SQL 인젝션, XSS, 인증/인가 누락 등 보안 취약점 검사

## 작업 원칙
- Always respond in Korean
- 심각도를 3단계로 분류: CRITICAL / WARNING / SUGGESTION
- 문제 지적 시 반드시 **구체적인 수정 코드**를 함께 제시
- 좋은 부분도 언급하여 균형 잡힌 리뷰 유지
- 추측이나 가정을 하지 않음 — 확인이 필요하면 질문
- 코딩 스타일보다 **로직과 설계**에 집중

차이점 분석

나쁜 정의의 핵심 문제는 추상성이다. “잘 해주세요”, “꼼꼼하게”, “친절하게”는 사람이 들어도 어떻게 행동해야 할지 모호하다. AI도 마찬가지다. 구체적이고 검증 가능한 지시가 일관된 품질을 만든다.

좋은 정의의 조건을 정리하면 다음과 같다.

1. name이 역할을 드러낸다 — 파일명만 봐도 무슨 에이전트인지 안다
2. description에 트리거 키워드가 있다 — 사용자의 자연스러운 표현과 매칭된다
3. model이 작업 특성에 맞다 — 비용과 품질의 균형
4. 역할 선언이 구체적이다 — “당신은 ~하는 전문가입니다”로 범위를 한정한다
5. 핵심 역할이 3~5개로 제한된다 — 집중할 수 있는 범위
6. 작업 원칙이 검증 가능하다 — “잘 하세요”가 아니라 “3단계로 분류”
7. 출력 형식이 정의되어 있다 — 일관된 산출물 보장
8. 협업 관계가 명시되어 있다 — 팀 내 위치와 종료 조건

메타 스킬이 생성한 에이전트 정의를 검토할 때, 이 8가지 조건으로 점검하면 커스터마이징이 필요한 부분을 빠르게 찾아낼 수 있다.

심화: description 트리거 키워드 설계 원칙

description 필드는 에이전트의 “검색 가능성”을 결정한다. 사용자가 어떤 표현으로 요청하든 올바른 에이전트가 선택되게 하려면, 키워드 설계에 4가지 원칙을 적용한다.

원칙 1: 사용자의 언어로 쓴다

개발자가 “코드 리뷰해줘”라고 하지 “소스코드 정적 분석을 수행해줘”라고 하지 않는다. 트리거 키워드는 사용자가 실제로 입력할 표현이어야 한다.

# 나쁜 예 — 전문 용어 위주
description: "소스코드 정적 분석 및 동적 검증 에이전트. '정적 분석', 'static analysis' 요청 시 트리거."

# 좋은 예 — 사용자 표현 위주
description: "코드 리뷰를 수행하는 에이전트. '코드 리뷰', 'code review', 'PR 리뷰', '코드 검토' 요청 시 트리거."

원칙 2: 한국어와 영어를 모두 포함한다

개발자는 한국어와 영어를 섞어 쓴다. 두 언어의 키워드를 모두 포함해야 트리거 누락을 방지한다.

description: "... '코드 리뷰', 'code review', 'PR 리뷰' ..."

원칙 3: 동의어와 유사 표현을 포함한다

같은 의도를 다른 단어로 표현할 수 있다. 주요 동의어를 커버하되, 핵심 키워드 3~5개로 제한한다. 너무 많으면 관련 없는 요청에도 매칭될 수 있다.

# "리뷰"와 "검토"는 같은 의도
description: "... '코드 리뷰', '코드 검토', 'code review' ..."

원칙 4: 역할 설명 문장 자체에도 키워드를 녹인다

트리거 키워드 목록뿐 아니라, 앞의 역할 설명 문장에도 핵심 단어를 포함시킨다. Claude Code는 description 전체를 매칭에 사용하기 때문이다.

# 역할 설명에 "코드 리뷰"가 이미 포함됨
description: "코드 리뷰를 수행하는 에이전트. '코드 리뷰', 'code review', 'PR 리뷰' 요청 시 트리거."

공통 패턴을 정리하면: “{역할 동사}하는 에이전트. ‘{한국어 키워드}’, ‘{영어 키워드}’ 요청 시 트리거.” 이 패턴을 따르면 일관성 있는 description을 작성할 수 있다.

메타 스킬은 이 원칙을 대체로 잘 따르지만, 프로젝트 고유의 용어(사내 약어, 팀 용어 등)는 사람이 추가해야 한다. 예를 들어 팀에서 코드 리뷰를 “CR”이라고 부른다면, 트리거 키워드에 ’CR’을 추가하는 것이 합리적이다.

심화: model 선택 가이드

모델 선택은 비용과 품질 사이의 트레이드오프다. 잘못된 선택은 불필요한 비용 증가 또는 품질 저하로 이어진다.

sonnet vs opus 판단 표

한 문장으로 요약하면: “정해진 틀에 따라 처리하는 작업은 sonnet, 틀 자체를 만들어야 하는 작업은 opus.”

실전 적용 예시: book-writer 하네스의 모델 배정

이 책의 에이전트 팀에서 왜 chapter-writer만 opus이고 나머지는 sonnet인지 살펴보자.

비용 최적화 전략

모델 선택에 확신이 없다면, 다음 전략을 추천한다.

1. 모든 에이전트를 sonnet으로 시작한다
2. 결과 품질이 부족한 에이전트만 opus로 올린다
3. opus로 올린 후에도 개선이 미미하면 sonnet으로 돌린다 — 이 경우 문제는 모델이 아니라 에이전트 정의 자체에 있다

세 번째 포인트가 중요하다. 품질 문제의 원인이 항상 모델 성능인 것은 아니다. 핵심 역할이 모호하거나, 작업 원칙이 부족하거나, 출력 형식이 불명확한 경우 opus로 올려도 개선되지 않는다. 모델을 바꾸기 전에 에이전트 정의를 먼저 점검하라.

정리

• 메타 스킬은 세 종류의 파일을 생성한다: 에이전트 정의(.claude/agents/), 스킬 정의(.claude/skills/), 오케스트레이터(스킬의 한 종류).
• 에이전트 파일은 frontmatter(name, description, model)와 본문(역할 선언, 핵심 역할, 작업 원칙, 출력 형식, 협업) 두 영역으로 구성된다.
• 스킬 파일은 4개 섹션으로 구성된다: frontmatter, 워크플로우, 도구 사용법, 출력 규칙. model 필드가 없다 — 실행 모델은 에이전트가 결정한다.
• 워크플로우의 각 Phase에는 입력, 처리, 출력, 검증 4가지를 반드시 명시한다. 검증이 없으면 무음 실패, 오류 누적, 디버깅 불가 문제가 발생한다.
• 에이전트와 스킬의 관계는 1:N, N:1, 1:1 모두 가능하다. 절차가 다르면 스킬을 나누고, 관점이 다르면 에이전트를 나눈다.
• 긴 참고자료는 references/ 디렉토리로 분리한다. 20줄 이상, 변경 빈도 높음, 특정 Phase 전용, 다른 스킬에서 재사용 가능 — 네 가지 기준으로 판단한다.
• 트리거 키워드는 사용자의 언어로, 한국어/영어 모두 포함하되 3~5개로 제한한다.
• 모델 선택: 정해진 틀에 따라 처리하는 작업은 sonnet, 틀 자체를 만드는 작업은 opus. 확신이 없으면 sonnet으로 시작하여 점진적으로 올린다. 모델을 바꾸기 전에 에이전트 정의를 먼저 점검하라.
• 좋은 정의의 핵심은 구체성과 검증 가능성이다. “잘 해주세요”가 아니라 “심각도를 3단계로 분류”처럼 쓴다.
• 커스터마이징은 작업 원칙 추가, 출력 형식 조정, references/ 추가 세 가지가 주요 수정 포인트다. 최소 수정, 연쇄 확인, 원본 보존, 점진적 개선의 원칙을 따른다.

다음 챕터 미리보기

• Chapter 5에서는 에이전트 팀 전체를 엮는 오케스트레이터 스킬의 구조를 다룬다. 에이전트 구성 테이블, Phase별 워크플로우, 파일 기반 통신, “각 Phase 완료 후 사용자 확인” 패턴을 배운다. 이 챕터에서 살펴본 에이전트와 스킬이 오케스트레이터에 의해 하나의 팀으로 조율되는 과정을 확인한다.

Chapter 5: 오케스트레이터와 팀 운영

이 챕터에서 배울 것

• 오케스트레이터 스킬이 무엇이며, 일반 스킬과 어떻게 다른지
• 메타 스킬이 생성한 오케스트레이터 파일의 전체 구조를 읽는 법
• 에이전트 구성 테이블에서 팀의 큰 그림을 10초 안에 파악하는 법
• Phase별 워크플로우에서 입력/출력의 연쇄와 검증의 2레벨을 이해하는 법
• 파일 기반 통신의 3가지 규칙: 위치 고정, 형식 통일, 메타 정보 포함
• “각 Phase 완료 후 사용자 확인” 패턴이 왜 필수적인지
• 오케스트레이터 설계에서 흔히 발생하는 4가지 실수와 대처법

본문

오케스트레이터란 무엇인가

Chapter 4에서 에이전트와 스킬의 구조를 살펴보았다. 에이전트는 “누가 하는가”를, 스킬은 “어떻게 하는가”를 정의한다. 하지만 에이전트와 스킬이 각각 존재하는 것만으로는 팀이 되지 않는다. 축구에서 공격수, 미드필더, 수비수가 있어도 감독이 포메이션과 작전을 지시하지 않으면 조직적인 플레이가 나오지 않는다.

오케스트레이터(orchestrator)는 이 감독의 역할을 한다. 에이전트 팀의 실행 순서, 데이터 흐름, 의사결정 분기를 정의하는 스킬이다.

일반 스킬과 오케스트레이터 스킬의 차이를 정리하면 다음과 같다.

일반 스킬이 “한 사람의 업무 매뉴얼”이라면, 오케스트레이터는 “팀 전체의 작전 계획서”다.

왜 오케스트레이터가 별도로 필요할까? 에이전트 정의에 “다음에 에이전트 B를 호출하라”고 쓸 수도 있지 않은가? 가능은 하지만, 세 가지 문제가 생긴다.

1. 결합도가 높아진다: 에이전트 A가 에이전트 B의 존재를 직접 알아야 한다. B를 C로 교체하면 A도 수정해야 한다.
2. 전체 흐름이 보이지 않는다: 5개 에이전트 파일을 모두 열어야 전체 워크플로우를 파악할 수 있다.
3. 재사용이 어렵다: 같은 에이전트를 다른 팀에서 쓰려면 협업 섹션을 매번 수정해야 한다.

오케스트레이터가 있으면 에이전트는 자기 역할에만 집중하고, 팀 구조는 오케스트레이터 한 파일에서 관리된다. 에이전트 교체, 순서 변경, 팀 확장이 모두 오케스트레이터 수정만으로 가능해진다.

메타 스킬(/harness)로 하네스를 생성하면, 이 오케스트레이터가 자동으로 만들어진다. 생성된 .claude/skills/{하네스명}/SKILL.md 파일을 열어보면, 에이전트 팀 구성부터 Phase별 워크플로우까지 완성된 형태로 나온다. 이 챕터에서는 그 생성된 구조를 하나씩 분해하여 이해한다.

인포그래픽: 오케스트레이터 실행 흐름도

오케스트레이터 스킬의 전체 구조

오케스트레이터 스킬 파일은 일반 스킬과 동일하게 .claude/skills/{스킬명}/SKILL.md에 위치한다. 파일 형식도 같다. 다만, 포함하는 정보의 범위가 다르다.

메타 스킬이 생성한 오케스트레이터 파일을 열어보면 다음과 같은 구조가 나온다.

---
name: {오케스트레이터-이름}
description: "{역할 설명}. '{트리거1}', '{트리거2}' 요청 시 트리거."
---

# {타이틀} — {한 줄 설명}

{오케스트레이터의 목적 한 문단 요약}

## 에이전트 팀 구성
(에이전트 구성 테이블)

## 디렉토리 구조
(산출물 저장 위치 계획)

## 워크플로우
(Phase별 실행 순서, 데이터 흐름, 검증 기준)

## 실행 방법
(실제로 어떻게 실행하는지)

일반 스킬에는 없고 오케스트레이터에만 있는 섹션이 두 개다: 에이전트 팀 구성과 디렉토리 구조. 이 두 섹션이 오케스트레이터의 핵심이다. 하나씩 살펴보자.

에이전트 구성 테이블

오케스트레이터의 첫 번째 섹션은 에이전트 팀 구성 테이블이다. 이 테이블은 팀 전체를 한눈에 보여준다.

## 에이전트 팀 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `code-reviewer` | 코드 리뷰 | sonnet | 1, 4 |
| `test-writer` | 테스트 코드 작성 | sonnet | 2 |
| `code-fixer` | 코드 수정 | sonnet | 3 |

테이블의 네 컬럼은 각각 다음 질문에 답한다.

이 테이블이 왜 중요한가? 오케스트레이터를 처음 읽는 사람이 전체 팀 구조를 10초 안에 파악할 수 있기 때문이다. 워크플로우의 상세 내용은 뒤에 나오지만, 테이블만으로도 “3명의 에이전트가 4개 Phase로 동작하는구나”라는 큰 그림이 보인다.

테이블 읽는 법

테이블에서 읽어내야 할 핵심 정보는 네 가지다.

첫째, 팀 규모와 역할 분담. 에이전트가 몇 명이고, 각각 무엇을 담당하는지 파악한다. 역할이 겹치는 에이전트가 있다면 설계를 재검토할 필요가 있다.

둘째, 모델 선택의 의도. 대부분의 에이전트는 sonnet을 사용한다. 특정 에이전트만 opus를 사용한다면, 그 에이전트의 작업이 더 높은 추론 능력이나 긴 텍스트 생성을 필요로 한다는 의미다. 예를 들어 book-writer 하네스에서는 chapter-writer만 opus를 사용한다. 긴 텍스트 창작이 필요한 유일한 에이전트이기 때문이다.

셋째, Phase 흐름. Phase 컬럼의 숫자를 따라가면 전체 실행 순서가 보인다. 숫자가 순차적이면 파이프라인 구조, 같은 Phase에 여러 에이전트가 배치되면 병렬 실행을 암시한다.

넷째, 재등장하는 에이전트. 한 에이전트가 여러 Phase에 등장하면(예: code-reviewer가 Phase 1, 4에 모두 참여), 생성-검증 루프를 암시한다. Phase 1에서 초기 리뷰를 하고, Phase 4에서 수정본을 재리뷰하는 패턴이다.

실제 book-writer 하네스의 에이전트 구성 테이블을 보자.

## 에이전트 팀 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `book-planner` | 목차/구조 설계 | sonnet | 1 |
| `chapter-writer` | 챕터 집필 | opus | 2, 3 |
| `book-editor` | 원고 리뷰/편집 | sonnet | 3 |
| `infographic-creator` | SVG 인포그래픽 | sonnet | 4 |
| `book-publisher` | PDF + 웹 뷰어 | sonnet | 5 |

이 테이블에서 읽어낼 수 있는 정보:

• 5명의 에이전트가 5개 Phase로 동작한다.
• chapter-writer만 opus를 사용한다. 긴 텍스트 창작이 필요한 유일한 에이전트이기 때문이다.
• Phase 3에 두 에이전트가 참여한다. 이것은 리뷰 루프(생성-검증 패턴)를 암시한다.
• Phase 1 → 2 → 3 → 4 → 5 순서로 파이프라인 구조다.

테이블 하나에 이만큼의 정보가 담긴다. 메타 스킬이 생성한 오케스트레이터를 처음 열었을 때, 이 테이블부터 읽으면 전체 그림이 빠르게 잡힌다.

테이블의 규칙

에이전트 이름은 백틱으로 감싼다. 코드로 취급되는 식별자임을 시각적으로 표시하기 위해서다. 이 이름은 .claude/agents/ 디렉토리의 파일명과 일치해야 한다. code-reviewer라고 썼으면 .claude/agents/code-reviewer.md 파일이 존재해야 한다.

Phase 컬럼에는 숫자를 쓴다. “리뷰 단계”가 아니라 “Phase 1”로 쓴다. 워크플로우 섹션과 정확히 대응되어야 하기 때문이다.

한 에이전트가 여러 Phase에 등장할 수 있다. 이 경우 Phase 컬럼에 “1, 4”처럼 콤마로 나열한다.

역할은 한 줄로 쓴다. 상세한 역할 정의는 에이전트 파일에 있다. 테이블에서는 이 에이전트가 이 팀에서 어떤 포지션인지만 알 수 있으면 된다.

디렉토리 구조와 파일 기반 통신

오케스트레이터의 두 번째 핵심 섹션은 디렉토리 구조다. 에이전트들은 메모리를 공유하지 않는다. 에이전트 A가 파일을 생성하면, 에이전트 B가 그 파일을 읽어서 작업한다. 이것이 파일 기반 통신이다.

왜 파일인가? Claude Code의 에이전트 호출 구조에서는 각 에이전트가 독립적인 세션으로 실행된다. 한 에이전트의 컨텍스트(대화 내역, 분석 결과 등)는 다른 에이전트에게 자동으로 전달되지 않는다. 에이전트 간에 정보를 전달할 수 있는 유일한 채널은 파일 시스템이다.

메타 스킬이 생성한 오케스트레이터를 열어보면, 디렉토리 구조가 다음과 같이 정의되어 있다.

## 디렉토리 구조

quality-reports/
├── reviews/              # Phase 1: 코드 리뷰 결과
│   └── review-{대상}.md
├── tests/                # Phase 2: 테스트 코드
│   └── test_{대상}.py
├── fixes/                # Phase 3: 수정 사항
│   └── fix-{대상}.md
└── summary/              # 최종 요약
    └── quality-report.md

이 디렉토리 구조는 에이전트 간의 통신 계약(contract)이다. “Phase 1의 산출물은 reviews/review-{대상}.md에 저장한다”는 약속이 있으면, Phase 2의 에이전트는 정확히 어디를 읽어야 하는지 안다.

디렉토리 구조 설계의 3가지 원칙

메타 스킬이 디렉토리 구조를 생성할 때 따르는 원칙이 있다. 커스터마이징할 때도 이 원칙을 유지해야 한다.

원칙 1: Phase별 디렉토리를 만든다. 하나의 Phase가 하나의 디렉토리에 산출물을 저장한다. Phase가 같은 디렉토리에 쓰면 산출물이 뒤섞인다. 이 분리가 있으면 “reviews/에 있는 파일은 리뷰 결과, tests/에 있는 파일은 테스트 코드”라는 것이 파일 시스템만 보고도 명확하다.

원칙 2: 파일명에 패턴을 정한다. review-{대상}.md, test_{대상}.py처럼 네이밍 규칙을 명시한다. 에이전트가 이 패턴을 따르면, 다른 에이전트가 Glob 도구로 해당 패턴의 파일을 쉽게 찾을 수 있다. 파일명 패턴이 없으면 에이전트 A는 review-result.md라고 저장하고, 에이전트 B는 reviews/auth-review.md를 찾으려 한다. 파일을 못 찾아서 실패하거나, 엉뚱한 파일을 읽게 된다.

원칙 3: 최종 산출물과 중간 산출물을 분리한다. 사용자에게 전달되는 최종 결과물과 에이전트 간 통신용 중간 파일을 구분한다. 위 예시에서 summary/quality-report.md는 최종 산출물이고, reviews/와 fixes/는 중간 산출물이다. 이 분리가 있으면 사용자는 summary/만 보면 되고, 디버깅이 필요할 때만 중간 산출물을 확인한다.

이 원칙들이 지켜지면 한 가지 부수적인 이점도 생긴다: 점진적 재실행이 가능해진다. Phase 2가 실패했을 때 Phase 1부터 다시 시작할 필요가 없다. reviews/ 디렉토리에 Phase 1의 산출물이 온전히 남아 있으므로, Phase 2만 재실행하면 된다.

파일 기반 통신의 3가지 규칙

디렉토리 구조가 잡혔으면, 에이전트가 파일을 주고받을 때 따라야 할 규칙이 있다.

규칙 1: 산출물 파일의 위치와 이름을 고정한다. 오케스트레이터에서 각 Phase의 출력을 명시할 때, 정확한 파일 경로를 지정한다.

# 나쁜 예 — 위치가 모호
- **출력**: 리뷰 결과 파일

# 좋은 예 — 위치가 명확
- **출력**: `reviews/review-{대상}.md`

규칙 2: 파일 형식을 통일한다. 중간 산출물은 가능하면 마크다운으로 통일한다. 이유는 두 가지다.

1. AI가 가장 잘 읽고 쓰는 형식이다. Claude Code는 마크다운을 네이티브하게 이해한다. JSON이나 YAML보다 자연스럽게 구조화된 정보를 담을 수 있다.
2. 사람도 읽을 수 있다. 디버깅할 때 중간 산출물을 열어봐야 하는데, 마크다운이면 별도 도구 없이 바로 읽을 수 있다.

물론 예외는 있다. 테스트 코드는 .py나 .ts로, 설정 파일은 .json으로 저장해야 한다. “에이전트 간 통신을 위한 중간 산출물”은 마크다운, “프로젝트의 실제 코드”는 해당 언어의 파일 형식을 사용한다.

규칙 3: 산출물에 메타 정보를 포함한다. 에이전트 B가 에이전트 A의 산출물을 읽을 때, 그 파일이 어떤 맥락에서 생성되었는지 알아야 한다. 산출물 파일의 상단에 메타 정보를 포함하면 이 문제가 해결된다.

# 코드 리뷰: auth-service
- 리뷰 대상: src/auth/token.py, src/auth/session.py
- 리뷰 일시: 2026-03-15
- 리뷰어: code-reviewer (sonnet)

## 요약
- CRITICAL: 1개
- WARNING: 3개
- SUGGESTION: 2개

## 상세 리뷰
...

이 메타 정보가 있으면 에이전트 B는 “어떤 파일을 대상으로 한 리뷰인지”, “어떤 에이전트가 작성한 건지” 즉시 파악할 수 있다. 또한 사람이 디버깅할 때도 유용하다.

Phase별 워크플로우

오케스트레이터의 핵심은 워크플로우다. 에이전트 구성 테이블이 “누가 참여하는가”를 보여준다면, 워크플로우는 “어떤 순서로, 무엇을 주고받으며, 어떻게 검증하는가”를 정의한다.

메타 스킬이 생성한 오케스트레이터의 워크플로우를 열어보면, 각 Phase는 다음과 같은 형식으로 되어 있다.

### Phase 1: 코드 리뷰
- **에이전트**: `code-reviewer`
- **입력**: 리뷰 대상 코드 (파일 경로 또는 PR 번호)
- **처리**: `code-review` 스킬의 워크플로우에 따라 코드 분석
- **출력**: `reviews/review-{대상}.md`
- **검증**: 리뷰 결과에 심각도별 이슈가 분류되어 있는지 확인

일반 스킬의 Phase와 구조는 동일하다. 입력, 처리, 출력, 검증의 4가지를 명시한다. 다만 오케스트레이터의 Phase에는 한 가지가 추가된다: 에이전트 지정. 일반 스킬에서는 해당 스킬을 호출한 에이전트가 모든 Phase를 수행하지만, 오케스트레이터에서는 Phase마다 다른 에이전트가 실행될 수 있으므로, 어떤 에이전트가 이 Phase를 담당하는지 명시해야 한다.

입력과 출력의 연쇄

오케스트레이터에서 가장 중요한 설계 원칙은 “앞 Phase의 출력이 다음 Phase의 입력”이라는 것이다.

Phase 1 출력: reviews/review-auth.md
    ↓
Phase 2 입력: reviews/review-auth.md  ← 동일한 파일
    ↓
Phase 2 출력: tests/test_auth.py
    ↓
Phase 3 입력: reviews/review-auth.md + tests/test_auth.py  ← 누적

이 연쇄가 끊기면 워크플로우가 멈춘다. Phase 2가 reviews/review-auth.md를 입력으로 기대하는데, Phase 1이 review_auth_result.txt로 저장했다면? Phase 2는 입력을 찾지 못한다.

따라서 메타 스킬이 생성한 워크플로우를 확인할 때는 모든 Phase의 입력/출력이 디렉토리 구조와 일치하는지 반드시 점검해야 한다. 이것은 마치 함수의 반환 타입이 다음 함수의 매개변수 타입과 맞아야 하는 것과 같다. 타입이 안 맞으면 컴파일 에러가 나듯, 파일 경로가 안 맞으면 워크플로우가 실패한다.

검증의 2레벨

Chapter 4에서 스킬의 Phase마다 검증 기준을 넣어야 한다고 배웠다. 오케스트레이터에서는 검증이 두 가지 레벨로 작동한다.

레벨 1: 에이전트 수준 검증. 개별 에이전트가 자기 산출물을 스스로 점검한다. 이것은 해당 에이전트의 스킬에 정의된 검증 기준이다. 예를 들어 코드 리뷰어가 “모든 변경 파일이 분석되었는지” 확인하는 것이다.

레벨 2: 오케스트레이터 수준 검증. Phase 간 전환 시점에서 오케스트레이터가 추가로 점검한다. 이것은 에이전트 간의 인터페이스가 올바른지 확인하는 것이다. 예를 들어 “Phase 1의 산출물 파일이 실제로 존재하는지”, “파일 형식이 다음 Phase가 기대하는 구조인지” 확인한다.

### Phase 1: 코드 리뷰
- **에이전트**: `code-reviewer`
- ...
- **검증**:
  - [에이전트 수준] 모든 변경 파일이 분석되었는지
  - [오케스트레이터 수준] `reviews/review-{대상}.md` 파일이 생성되었는지

실제 오케스트레이터에서 반드시 이렇게 두 레벨을 구분하여 태깅할 필요는 없다. 다만 오케스트레이터를 읽거나 수정할 때 “에이전트 자체의 품질 검증”과 “Phase 간 연결 검증”을 모두 고려하고 있는지 점검해야 한다.

“각 Phase 완료 후 사용자 확인” 패턴

메타 스킬이 생성한 오케스트레이터에는 반드시 포함되는 패턴이 있다. 각 Phase가 완료될 때마다 사용자에게 확인을 받는 것이다.

## 실행 방법

Phase 1: code-reviewer → reviews/ 생성 → **사용자 확인**
Phase 2: test-writer → tests/ 생성 → **사용자 확인**
Phase 3: code-fixer → fixes/ 생성 → **사용자 확인**
Phase 4: 최종 요약 → summary/ 생성 → **사용자 확인**

왜 매번 확인을 받아야 할까? 자동으로 Phase 1 → 2 → 3 → 4를 쭉 실행하면 더 효율적이지 않은가? 세 가지 이유가 있다.

이유 1: 오류의 증폭을 방지한다

Phase 1에서 리뷰가 잘못되면, Phase 2의 테스트 코드도 잘못된 리뷰를 기반으로 작성된다. Phase 3의 수정도 잘못된 방향으로 진행된다. 최종 보고서를 보고 “처음부터 잘못되었구나”라고 발견하면, 모든 Phase를 처음부터 다시 해야 한다.

Phase 1 완료 후 사용자가 리뷰 결과를 확인하면, 잘못된 방향을 즉시 교정할 수 있다. “이 부분은 의도한 설계니까 이슈에서 빼줘”라고 피드백하면, Phase 2부터는 올바른 기반 위에서 진행된다.

이유 2: AI의 판단을 사람이 검증한다

AI는 코드를 분석하고 이슈를 찾지만, 도메인 맥락은 사람이 더 잘 안다. “이 코드가 복잡한 건 성능 최적화 때문”이라는 배경 지식은 AI에게 없을 수 있다. 사용자 확인은 AI의 분석에 도메인 지식을 주입하는 기회다.

이유 3: 비용을 통제한다

에이전트 호출에는 API 비용이 발생한다. Phase 1 결과가 불만족스러우면 Phase 2 이후를 실행할 필요가 없다. Phase 1만 재실행하면 된다. 자동 실행이면 불필요한 Phase까지 모두 실행되어 비용이 낭비된다.

사용자 확인이 오케스트레이터에 명시되는 방식

메타 스킬이 생성한 오케스트레이터에서는 사용자 확인이 두 곳에 명시된다. 워크플로우의 각 Phase에 구체적인 확인 내용이 들어가고:

### Phase 1: 코드 리뷰
- **에이전트**: `code-reviewer`
- **입력**: 리뷰 대상 코드
- **출력**: `reviews/review-{대상}.md`
- **검증**: 리뷰 결과 파일이 존재하고, 심각도별 이슈가 분류되어 있는지
- **사용자 확인**: 리뷰 결과를 사용자에게 보여주고, 수정/보완 요청을 반영한 후 다음 Phase로 진행

실행 방법 섹션에 전체 원칙이 일괄 명시된다:

## 실행 방법

각 Phase 완료 후 사용자 확인을 받고 다음 Phase로 진행.
사용자가 재작업을 요청하면 해당 Phase를 재실행한다.

이 두 곳을 모두 확인해야 한다. Phase별 검증 섹션에서는 해당 Phase의 구체적인 확인 내용을, 실행 방법 섹션에서는 전체 원칙을 파악한다.

예제: “코드 품질 관리” 오케스트레이터

지금까지 설명한 개념을 실제 오케스트레이터에서 확인하자. 다음은 메타 스킬이 생성한 “코드 품질 관리” 오케스트레이터의 완성된 모습이다. .claude/skills/code-quality/SKILL.md에 위치한다.

---
name: code-quality
description: "코드 품질 관리 오케스트레이터. 에이전트 팀을 조율하여 코드 리뷰, 테스트, 수정을 수행합니다.
              '코드 품질', 'code quality', '품질 관리' 요청 시 트리거."
---

# Code Quality — 코드 품질 관리 오케스트레이터

에이전트 팀(code-reviewer, test-writer, code-fixer)을 조율하여
코드 변경 사항의 품질을 종합적으로 관리하는 오케스트레이터 스킬.

## 에이전트 팀 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `code-reviewer` | 코드 리뷰 | sonnet | 1, 4 |
| `test-writer` | 테스트 코드 작성 | sonnet | 2 |
| `code-fixer` | 코드 수정 | sonnet | 3 |

## 디렉토리 구조

quality-reports/
├── reviews/                # Phase 1, 4: 코드 리뷰 결과
│   ├── review-{대상}.md
│   └── re-review-{대상}.md
├── tests/                  # Phase 2: 테스트 코드
│   └── test_{대상}.py
├── fixes/                  # Phase 3: 수정 보고서
│   └── fix-{대상}.md
└── summary/                # Phase 5: 최종 보고서
    └── quality-report.md

## 워크플로우

### Phase 1: 코드 리뷰
- **에이전트**: `code-reviewer`
- **입력**: 리뷰 대상 코드 (파일 경로 목록 또는 PR 번호)
- **처리**: `code-review` 스킬의 워크플로우에 따라 코드 분석 및 이슈 식별
- **출력**: `quality-reports/reviews/review-{대상}.md`
- **검증**: 리뷰 파일 생성 확인, 모든 대상 파일 분석 확인, 심각도 부여 확인
- **사용자 확인**: 리뷰 결과를 보여주고 이슈 목록에 동의하는지 확인

### Phase 2: 테스트 코드 작성
- **에이전트**: `test-writer`
- **입력**: `quality-reports/reviews/review-{대상}.md`
- **처리**: CRITICAL/WARNING 이슈에 대한 재현 테스트 작성, 실행하여 Red 상태 확인
- **출력**: `quality-reports/tests/test_{대상}.py`
- **검증**: 테스트 파일 생성 확인, CRITICAL 이슈 테스트 포함 확인, Red 상태 확인
- **사용자 확인**: 테스트 코드와 실행 결과 확인

### Phase 3: 코드 수정
- **에이전트**: `code-fixer`
- **입력**: `quality-reports/reviews/review-{대상}.md` + `quality-reports/tests/test_{대상}.py`
- **처리**: CRITICAL 이슈부터 순서대로 수정, 수정마다 테스트 실행
- **출력**: 수정된 소스 코드 + `quality-reports/fixes/fix-{대상}.md`
- **검증**: CRITICAL 이슈 전체 수정 확인, 테스트 Green 확인, 기존 테스트 통과 확인
- **사용자 확인**: 수정된 코드와 테스트 결과 확인

### Phase 4: 재리뷰
- **에이전트**: `code-reviewer`
- **입력**: 수정된 소스 코드 + `quality-reports/fixes/fix-{대상}.md`
- **처리**: 수정된 코드에 대해 재리뷰
- **출력**: `quality-reports/reviews/re-review-{대상}.md`
- **분기**: CRITICAL 0개 → Phase 5 / CRITICAL 존재 → Phase 3 반복
- **사용자 확인**: 재리뷰 결과 확인, 추가 수정 또는 완료 판단

### Phase 5: 최종 보고서
- **에이전트**: (오케스트레이터)
- **입력**: 전체 산출물 (`quality-reports/` 하위 전체)
- **처리**: 이슈 발견/수정/잔여 현황을 종합
- **출력**: `quality-reports/summary/quality-report.md`
- **검증**: 모든 Phase 산출물이 보고서에 반영되었는지 확인

## 실행 방법

오케스트레이터(사용자 또는 메인 Claude)가 각 Phase를 순서대로 실행:

Phase 1: Agent tool → code-reviewer → 리뷰 생성 → 사용자 확인
Phase 2: Agent tool → test-writer → 테스트 작성 → 사용자 확인
Phase 3: Agent tool → code-fixer → 코드 수정 → 사용자 확인
Phase 4: Agent tool → code-reviewer → 재리뷰 → CRITICAL 0개? → Phase 5 / Phase 3 반복
Phase 5: 최종 보고서 생성 → 사용자 확인

각 Phase 완료 후 사용자 확인을 받고 다음 Phase로 진행.
사용자가 재작업을 요청하면 해당 Phase를 재실행한다.
CRITICAL 이슈가 0개가 될 때까지 Phase 3 ↔ Phase 4를 반복한다. (최대 2회)
2회 반복 후에도 CRITICAL이 남아 있으면 사용자에게 판단을 요청한다.

이 오케스트레이터의 전체 하네스 구조는 다음과 같다.

.claude/
├── agents/
│   ├── code-reviewer.md
│   ├── test-writer.md
│   └── code-fixer.md
└── skills/
    ├── code-review/
    │   ├── SKILL.md
    │   └── references/
    │       ├── checklist.md
    │       └── severity-guide.md
    └── code-quality/          ← 오케스트레이터
        └── SKILL.md

이 구조에서 주목할 점을 짚어보자.

에이전트 3명, 스킬 1개, 오케스트레이터 1개. 사용자가 “코드 품질 관리해줘”라고 요청하면, code-quality 오케스트레이터가 트리거되고, Phase 1부터 순서대로 적절한 에이전트를 호출하며 진행한다.

Phase 4에 분기가 있다. CRITICAL 이슈가 남아있으면 Phase 3으로 돌아간다. 이것이 Chapter 3에서 배운 생성-검증 패턴이다. 코드 수정(생성)과 코드 리뷰(검증)가 루프를 돌며 품질 기준을 만족할 때까지 반복한다. 단, 최대 2회로 제한하여 무한 루프를 방지한다.

Phase 5는 별도 에이전트 없이 오케스트레이터가 직접 수행한다. 최종 보고서 생성은 기존 산출물을 취합하는 단순 작업이므로, 전문 에이전트를 할당할 필요가 없다. 모든 Phase에 반드시 에이전트를 배정해야 하는 것은 아니다.

Phase 2에서 TDD의 Red 단계를 활용한다. 테스트가 현재 코드에서 실패하는지(Red) 확인하는 것은, 테스트가 실제로 이슈를 검출하는지 검증하는 방법이다. 이미 통과하는 테스트는 이슈를 재현하지 못하는 것이므로 의미가 없다.

심화: 오케스트레이터와 아키텍처 패턴의 관계

Chapter 3에서 4가지 아키텍처 패턴을 배웠다. 오케스트레이터의 워크플로우는 이 패턴들의 구체적인 구현이다. 메타 스킬이 생성한 오케스트레이터를 열어보면, 워크플로우 안에 어떤 패턴이 사용되었는지 식별할 수 있다.

파이프라인이 오케스트레이터가 되면

Phase 1 (A) → Phase 2 (B) → Phase 3 (C) → Phase 4 (D)

가장 단순한 형태다. 에이전트 A의 산출물이 B로, B의 산출물이 C로 순차 전달된다. 코드 품질 관리 오케스트레이터의 Phase 1 → 2 → 3 경로가 이것이다.

생성-검증이 오케스트레이터가 되면

Phase N (생성자) → Phase N+1 (검증자) → 기준 미달? → Phase N 반복
                                      → 기준 충족? → 다음 Phase

루프가 들어간다. Phase 3(code-fixer) → Phase 4(code-reviewer) → 다시 Phase 3의 경로가 이것이다. 오케스트레이터에서 생성-검증 패턴을 구현할 때 가장 중요한 것은 분기 조건과 종료 조건을 명시하는 것이다.

패턴을 조합하면

실전의 오케스트레이터는 대부분 여러 패턴의 조합이다. 코드 품질 관리 오케스트레이터는 파이프라인(Phase 1→2→3)과 생성-검증(Phase 3↔︎4)의 조합이다.

[파이프라인]                    [생성-검증 루프]
Phase 1 → Phase 2 → Phase 3 ↔ Phase 4 → Phase 5

book-writer 오케스트레이터도 마찬가지다. Phase 1→2→3→4→5는 파이프라인이지만, Phase 3 안에서 editor와 writer가 생성-검증 루프를 돈다.

패턴을 먼저 선택하고 오케스트레이터를 만드는 것이 아니다. 메타 스킬이 도메인의 워크플로우를 분석하여 자연스럽게 패턴을 선택한다. 패턴의 이름을 아는 것은 “지금 내가 보고 있는 것이 무엇인지” 인식하기 위해서다. 인식하면 해당 패턴에서 주의할 점(예: 생성-검증의 종료 조건)을 놓치지 않게 된다.

심화: 오케스트레이터 설계 시 흔한 실수

메타 스킬이 생성한 오케스트레이터를 커스터마이징하거나, 직접 수정할 때 자주 발생하는 실수를 정리한다.

실수 1: Phase를 너무 세분화한다

# 나쁜 예 — 8개 Phase
Phase 1: PR 정보 수집
Phase 2: diff 추출
Phase 3: 파일별 분류
Phase 4: 코드 분석
Phase 5: 이슈 분류
Phase 6: 테스트 작성
Phase 7: 코드 수정
Phase 8: 최종 보고서

Phase 1~5는 모두 “코드 리뷰” 단계다. 이것은 code-review 스킬 내부의 워크플로우여야 한다. 오케스트레이터의 Phase는 에이전트 전환이 일어나는 단위다. 같은 에이전트가 연속으로 실행되는 Phase는 하나로 합쳐야 한다.

# 좋은 예 — 5개 Phase
Phase 1: 코드 리뷰 (code-reviewer)
Phase 2: 테스트 작성 (test-writer)
Phase 3: 코드 수정 (code-fixer)
Phase 4: 재리뷰 (code-reviewer)
Phase 5: 최종 보고서

판단 기준: “이 Phase와 다음 Phase의 에이전트가 같은가?” 같다면 하나로 합쳐라. 세부 절차는 해당 에이전트의 스킬에 정의한다.

실수 2: 에이전트 간 의존성이 implicit하다

# 나쁜 예 — 입력이 모호
### Phase 2: 테스트 작성
- **입력**: 리뷰 결과
- **출력**: 테스트 코드

“리뷰 결과”가 어디 있는 파일인지 명시되지 않았다. 에이전트가 매번 다른 위치에서 파일을 찾으려 할 수 있다.

# 좋은 예 — 입력이 명시적
### Phase 2: 테스트 작성
- **입력**: `quality-reports/reviews/review-{대상}.md`
- **출력**: `quality-reports/tests/test_{대상}.py`

정확한 파일 경로를 쓴다. 모호성이 사라지고, 에이전트가 정확히 어디를 읽어야 하는지 안다.

실수 3: 종료 조건이 없는 루프

# 나쁜 예 — 종료 조건 없음
### Phase 4: 재리뷰
- CRITICAL 이슈가 있으면 Phase 3으로 돌아감

CRITICAL이 계속 나오면 무한 루프에 빠진다. 반드시 최대 반복 횟수를 정하거나, 대체 종료 조건을 둔다.

# 좋은 예 — 종료 조건 있음
### Phase 4: 재리뷰
- **분기**:
  - CRITICAL 0개 → Phase 5
  - CRITICAL 존재 + 반복 횟수 2회 미만 → Phase 3 반복
  - CRITICAL 존재 + 반복 횟수 2회 이상 → 미해결 이슈로 기록하고 Phase 5 진행

이렇게 하면 최대 2회 루프 후에는 반드시 Phase 5로 진행한다. 미해결 이슈는 최종 보고서에 명시하여 사용자가 직접 판단할 수 있게 한다.

실수 4: 사용자 확인 없이 전체 자동 실행

# 나쁜 예 — 사용자 확인 없음
## 실행 방법
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5를 자동으로 실행

Phase 1의 리뷰가 잘못되면 이후 모든 Phase가 헛수고가 된다. 앞서 설명한 대로, 매 Phase 완료 후 사용자 확인은 필수다. 오류의 증폭을 막고, 비용을 통제하고, 도메인 지식을 주입할 수 있는 유일한 시점이다.

오케스트레이터 체크리스트

메타 스킬이 생성한 오케스트레이터를 검토하거나, 수정한 후 다음 체크리스트로 점검한다.

에이전트 팀 구성: - [ ] 모든 에이전트의 .claude/agents/{이름}.md 파일이 존재하는가? - [ ] 에이전트 구성 테이블의 이름이 파일명과 일치하는가? - [ ] 각 에이전트의 모델 선택이 작업 특성에 맞는가?

디렉토리 구조: - [ ] 모든 Phase의 산출물 저장 위치가 디렉토리 구조에 포함되어 있는가? - [ ] 파일명 패턴이 명확한가? (다른 에이전트가 Glob으로 찾을 수 있는가?) - [ ] 최종 산출물과 중간 산출물이 구분되어 있는가?

워크플로우: - [ ] 모든 Phase에 에이전트, 입력, 처리, 출력, 검증이 명시되어 있는가? - [ ] 앞 Phase의 출력 경로와 다음 Phase의 입력 경로가 일치하는가? - [ ] 루프가 있다면 종료 조건이 명시되어 있는가? - [ ] 각 Phase에 사용자 확인이 포함되어 있는가?

실행: - [ ] 실행 방법 섹션에 전체 흐름이 한눈에 보이는가? - [ ] Phase 재실행 방법이 설명되어 있는가?

정리

• 오케스트레이터는 에이전트 팀의 실행 순서, 데이터 흐름, 의사결정 분기를 정의하는 스킬이다. 일반 스킬이 “한 사람의 업무 매뉴얼”이라면, 오케스트레이터는 “팀의 작전 계획서”다.
• 에이전트 구성 테이블은 팀 전체를 한눈에 보여준다. 에이전트, 역할, 모델, Phase의 4컬럼으로 팀의 큰 그림을 10초 안에 파악할 수 있다.
• 디렉토리 구조는 에이전트 간의 통신 계약이다. Phase별 디렉토리, 파일명 패턴, 최종/중간 산출물 분리의 3가지 원칙을 따른다.
• 파일 기반 통신은 에이전트 간 정보 전달의 유일한 채널이다. 위치 고정, 형식 통일, 메타 정보 포함의 3가지 규칙을 따른다.
• 워크플로우의 각 Phase에는 에이전트, 입력, 처리, 출력, 검증을 명시한다. 앞 Phase의 출력 경로와 다음 Phase의 입력 경로가 반드시 일치해야 한다. 검증은 에이전트 수준과 오케스트레이터 수준의 2레벨로 작동한다.
• 각 Phase 완료 후 사용자 확인은 필수 패턴이다. 오류 증폭 방지, AI 판단의 검증, 비용 통제를 위해 반드시 포함한다.
• 루프가 있는 워크플로우에는 종료 조건을 반드시 명시한다. 최대 반복 횟수를 정하여 무한 루프를 방지한다.
• 오케스트레이터의 워크플로우는 Chapter 3의 아키텍처 패턴(파이프라인, 생성-검증 등)의 구체적인 구현이다. 실전에서는 여러 패턴이 조합된다.

다음 챕터 미리보기

• Chapter 6에서는 이 책 자체를 만든 book-writer 하네스의 전체 구조를 해부한다. 5명의 에이전트, 5개 Phase의 워크플로우, 파이프라인과 생성-검증 패턴의 조합을 실제 파일을 열어보며 분석한다. 이 챕터에서 배운 오케스트레이터 구조가 실전에서 어떻게 적용되는지 확인하는 챕터다.

Chapter 6: 사례 1 — 책 집필 하네스 (파이프라인 + 생성-검증)

이 챕터에서 배울 것

• book-writer 하네스의 전체 구조와 5명의 에이전트가 어떻게 협업하는지
• 파이프라인 패턴(Phase 1→2→4→5)과 생성-검증 패턴(Phase 3)이 하나의 하네스에서 어떻게 조합되는지
• 각 에이전트 정의 파일의 핵심 설계 결정과 그 이유
• 오케스트레이터 스킬(SKILL.md)이 에이전트 간 데이터 흐름을 어떻게 관리하는지
• 산출물 디렉토리 구조와 파일 네이밍 규칙의 설계 원칙
• book-writer 하네스를 처음부터 재현하며 구축하는 과정

본문

이 책은 어떻게 만들어졌는가

이 챕터는 메타적이다. 지금 읽고 있는 이 책 자체가 book-writer 하네스로 만들어졌다. Chapter 1의 개념 설명도, Chapter 3의 패턴 분석도, 지금 이 문장도 — 모두 5명의 에이전트가 협업한 결과물이다.

book-planner가 목차를 설계했고, chapter-writer가 본문을 집필했고, book-editor가 리뷰했고, infographic-creator가 다이어그램을 그렸고, book-publisher가 PDF와 웹 뷰어로 변환한다. 이 과정을 조율한 것이 book-writer 오케스트레이터 스킬이다.

이 챕터에서는 이 하네스의 전체 구조를 해부한다. Chapter 3에서 배운 패턴이 실전에서 어떻게 조합되는지, Part 2에서 배운 에이전트/스킬/오케스트레이터 작성법이 실제로 어떻게 적용되었는지를 하나씩 확인한다.

인포그래픽: book-writer 하네스 전체 아키텍처

book-writer 하네스 전체 구조

에이전트 팀 구성

book-writer 하네스는 5명의 에이전트로 구성된다.

이 구성에서 눈여겨볼 점이 세 가지 있다.

첫째, opus는 chapter-writer에만 사용한다. 5명 중 4명이 sonnet이고, opus는 집필 에이전트 하나뿐이다. 이유는 명확하다 — 집필은 가장 높은 창의성과 맥락 이해를 요구하는 작업이다. 목차 설계, 리뷰, SVG 생성, 조판은 규칙 기반 작업이므로 sonnet으로 충분하다. Chapter 4에서 배운 “비용 대비 품질” 원칙이 여기에 적용된다.

둘째, chapter-writer는 두 개 Phase에 걸쳐 참여한다. Phase 2에서 초안을 쓰고, Phase 3에서 편집자의 피드백을 받아 수정한다. 하나의 에이전트가 여러 Phase에 참여하는 것은 자연스럽다 — 글을 쓴 사람이 수정도 하는 것이 당연하기 때문이다.

셋째, 에이전트 분리 기준이 명확하다. Chapter 2에서 배운 4가지 기준을 대입해보면:

5명이라는 수가 임의적인 것이 아니라, 각 기준에 의해 자연스럽게 도출된 결과다.

디렉토리 구조

프로젝트/
├── .claude/
│   ├── agents/
│   │   ├── book-planner.md
│   │   ├── chapter-writer.md
│   │   ├── book-editor.md
│   │   ├── infographic-creator.md
│   │   └── book-publisher.md
│   └── skills/
│       └── book-writer/
│           └── SKILL.md              # 오케스트레이터
├── book/
│   ├── outline.md                    # Phase 1 산출물
│   ├── chapters/                     # Phase 2~3 산출물
│   │   ├── ch01-agent-and-skill.md
│   │   ├── ch02-harness-concept.md
│   │   └── ...
│   ├── assets/                       # Phase 4 산출물
│   │   ├── infographic-ch01-agent-vs-skill.svg
│   │   └── ...
│   └── output/                       # Phase 5 산출물
│       ├── pdf/
│       │   └── harness-engineering-guide.pdf
│       └── web/
│           └── index.html

이 구조에서 주목할 점은 Phase별로 산출물 위치가 분리되어 있다는 것이다. outline.md는 Phase 1, chapters/는 Phase 2~3, assets/는 Phase 4, output/는 Phase 5의 결과물이 저장된다. 이렇게 하면 어떤 Phase에서 문제가 생겼을 때, 해당 디렉토리만 확인하면 된다.

파일 네이밍에도 규칙이 있다:

{NN}은 두 자리 숫자로 챕터 번호를, {slug}는 하이픈으로 구분된 영문 키워드를 사용한다. 이 규칙 덕분에 파일을 정렬하면 자연스럽게 챕터 순서가 된다.

Phase 1~5 워크플로우 상세 분석

전체 흐름

Phase 1        Phase 2        Phase 3         Phase 4         Phase 5
[planner]  →  [writer]   →  [editor↔writer] → [infographic] → [publisher]
  │              │              │                │                │
  ▼              ▼              ▼                ▼                ▼
outline.md    ch{NN}.md     수정된 ch{NN}.md   SVG 파일들      PDF + 웹
              (초안)        (승인된 원고)

큰 틀은 파이프라인이다. Phase 1의 출력이 Phase 2의 입력이 되고, Phase 2의 출력이 Phase 3의 입력이 되는 식으로 순차적으로 흐른다. 하지만 Phase 3 내부에는 생성-검증 루프가 내포되어 있다. Chapter 3에서 다룬 “패턴 조합”의 전형적인 사례다.

각 Phase를 상세히 분석하자.

Phase 1: 목차 설계 (파이프라인)

### Phase 1: 목차 설계
- **에이전트**: `book-planner`
- **입력**: 책 주제, 대상 독자, 요구사항
- **출력**: `book/outline.md` (목차 + 챕터별 명세)
- **검증**: 사용자가 목차를 확인하고 승인

Phase 1은 전체 파이프라인의 첫 단계다. book-planner가 책의 전체 설계도를 만든다.

이 Phase에서 가장 중요한 것은 출력의 구체성이다. outline.md가 단순히 “Chapter 1: 소개”라고만 적혀 있으면, 뒤이어 집필하는 chapter-writer가 무엇을 어떻게 써야 할지 모른다. 실제 outline.md에는 각 챕터의 목표, 핵심 내용, 예제, 분량이 구체적으로 명시된다.

#### Chapter 6: 사례 1 — 책 집필 하네스 (파이프라인 + 생성-검증)
- 목표: 이 책을 만든 book-writer 하네스의 전체 구조를 이해하고,
        복합 패턴 설계를 할 수 있다
- 핵심 내용:
  - book-writer 하네스 전체 구조 분석
  - 5명의 에이전트: book-planner, chapter-writer, book-editor, ...
  - Phase 1~5 워크플로우 상세 분석
  - ...
- 예제: book-writer 하네스를 처음부터 재현하며 구축
- 분량: 16~18페이지

이것이 chapter-writer에게 전달되는 “작업 지시서”다. 목표가 무엇이고, 어떤 내용을 다뤄야 하고, 어떤 예제가 필요하고, 몇 페이지를 써야 하는지가 명시되어 있다. 뒤에서 살펴볼 book-planner 에이전트의 출력 형식이 이 구조를 강제한다.

검증 방법은 사용자 확인이다. 목차 품질은 주관적 판단이 필요하기 때문에, AI가 자동으로 검증하기보다 사람이 확인하는 것이 적절하다. 이것이 “각 Phase 완료 후 사용자 확인을 받고 다음 Phase로 진행”이라는 원칙의 첫 적용이다.

Phase 2: 챕터 집필 (파이프라인)

### Phase 2: 챕터 집필
- **에이전트**: `chapter-writer`
- **입력**: `book/outline.md`의 챕터별 명세
- **출력**: `book/chapters/ch{NN}-{slug}.md`
- **방식**: 한 챕터씩 순차 집필
- **검증**: 각 챕터 파일이 챕터 구조를 따르는지 확인

Phase 2는 파이프라인의 핵심 단계다. chapter-writer가 outline.md의 명세를 읽고 챕터를 하나씩 집필한다.

“한 챕터씩 순차 집필”이라는 방식에 의문이 들 수 있다. 각 챕터가 독립적이라면 팬아웃/팬인으로 병렬 집필할 수도 있지 않은가? 이론적으로는 가능하지만, 실전에서는 세 가지 이유로 순차가 낫다.

첫째, 챕터 간 참조. Chapter 7이 “Chapter 3에서 배운 패턴”을 언급하려면, Chapter 3의 내용을 알아야 한다. 앞 챕터의 내용이 뒤 챕터에 영향을 미치므로 완전한 독립이 아니다.

둘째, 용어 일관성. “하네스”, “오케스트레이터”, “에이전트” 같은 핵심 용어의 정의와 사용법이 챕터 간에 일관되어야 한다. 병렬로 작성하면 같은 개념을 다른 용어로 설명할 위험이 있다.

셋째, 난이도 곡선. 기술서적은 점진적으로 난이도를 높여가야 한다. 순차 집필이면 앞 챕터의 수준을 확인하면서 다음 챕터의 난이도를 조절할 수 있다.

검증은 구조적 검증이다. 챕터가 chapter-writer의 정의에 명시된 구조(이 챕터에서 배울 것 → 본문 → 정리 → 다음 챕터 미리보기)를 따르는지 확인한다. 내용의 정확성은 Phase 3에서 검증한다.

Phase 3: 리뷰 루프 (생성-검증)

### Phase 3: 리뷰 루프 (생성-검증)
- **에이전트**: `book-editor` → `chapter-writer`
- **입력**: 완성된 챕터
- **프로세스**:
  1. `book-editor`가 챕터 리뷰
  2. CRITICAL 이슈가 있으면 `chapter-writer`에게 수정 요청
  3. 수정본을 `book-editor`가 재리뷰
  4. CRITICAL 이슈 0개일 때 승인
- **검증**: 모든 챕터가 편집자 승인을 받음

Phase 3은 이 하네스의 핵심이다. 파이프라인 안에 생성-검증 패턴이 내포된 지점이다.

흐름을 도식화하면 이렇다:

[chapter-writer]가 ch01.md 작성 (Phase 2)
        │
        ▼
[book-editor]가 ch01.md 리뷰
        │
        ├─ CRITICAL 0개 → 승인 → ch02로 이동
        │
        └─ CRITICAL 1개 이상
              │
              ▼
        피드백 전달 → [chapter-writer]가 ch01.md 수정
              │
              ▼
        [book-editor]가 수정본 재리뷰
              │
              ├─ CRITICAL 0개 → 승인
              └─ CRITICAL 1개 이상 → 재수정 (반복)

Chapter 3의 생성-검증 패턴에서 배운 세 가지 설계 결정이 모두 적용되어 있다.

심각도 분류. book-editor는 이슈를 CRITICAL, WARNING, SUGGESTION으로 분류한다. 루프 종료 조건은 “CRITICAL 이슈 0개”다. 문체나 표현의 소소한 개선(SUGGESTION)은 루프를 돌릴 이유가 되지 않는다.

역할 분리. chapter-writer(opus)는 창의적 집필에 집중하고, book-editor(sonnet)는 냉정한 평가에 집중한다. 같은 에이전트가 쓰면서 동시에 리뷰하는 것보다 역할이 분리되어야 품질이 높아진다. Chapter 2에서 다룬 “역할 충돌” 문제의 해법이다.

루프 종료 보장. 오케스트레이터에 최대 반복 횟수를 설정할 수 있다. 3번의 수정으로도 CRITICAL이 해결되지 않으면, 사용자에게 에스컬레이션한다.

Phase 4: 인포그래픽 생성 (파이프라인, 잠재적 팬아웃)

### Phase 4: 인포그래픽 생성
- **에이전트**: `infographic-creator`
- **입력**: 각 챕터에서 시각화가 필요한 개념
- **출력**: `book/assets/infographic-ch{NN}-{slug}.svg`
- **방식**: 챕터별 병렬 생성 가능
- **검증**: SVG 파일이 유효하고 챕터에서 참조됨

Phase 4는 파이프라인의 한 단계이면서, 내부적으로는 팬아웃/팬인이 가능한 구조다. 각 챕터의 인포그래픽은 서로 독립적이므로 동시에 생성할 수 있다.

“챕터별 병렬 생성 가능”이라는 문구에 주목하자. “가능”이라고 한 것은, 병렬이 필수는 아니기 때문이다. Agent tool의 동시 호출 수에 따라 순차로 진행할 수도 있고, 여러 개를 동시에 생성할 수도 있다. 오케스트레이터가 상황에 따라 유연하게 결정할 수 있는 여지를 남긴 것이다.

검증은 두 가지다: SVG 파일이 유효한 형식인지(파싱 가능한지), 해당 SVG가 챕터 본문에서 실제로 참조되는지. 인포그래픽을 만들어놓고 아무 챕터에서도 언급하지 않으면, 그 인포그래픽은 독자에게 도달하지 못한다.

Phase 5: 출판 (파이프라인)

### Phase 5: 출판
- **에이전트**: `book-publisher`
- **입력**: 완성된 챕터들 + SVG 에셋
- **출력**:
  - `book/output/pdf/harness-engineering-guide.pdf`
  - `book/output/web/index.html`
- **검증**: PDF가 정상 생성되고 웹 뷰어에서 페이지 넘김 동작

Phase 5는 파이프라인의 마지막 단계다. 앞선 4개 Phase의 모든 산출물을 모아 최종 결과물로 변환한다.

이 Phase에서 book-publisher가 받는 입력은 두 종류다: book/chapters/ 디렉토리의 마크다운 파일들과, book/assets/ 디렉토리의 SVG 파일들. 서로 다른 Phase의 산출물이 하나의 Phase에서 통합된다. 이것이 파이프라인에서 “분기 후 합류”가 일어나는 지점이다.

검증도 두 종류다: PDF가 정상 생성되었는지(파일이 존재하고 열리는지), 웹 뷰어가 동작하는지(페이지 넘김이 되는지). 기술적 검증이므로 자동화할 수 있다.

파이프라인과 생성-검증의 조합 분석

전체 워크플로우에서 패턴이 어떻게 조합되는지 정리하자.

Phase 1: 목차 설계       → 파이프라인 (순차)
Phase 2: 챕터 집필       → 파이프라인 (순차)
Phase 3: 리뷰 루프       → 생성-검증 (루프)
Phase 4: 인포그래픽 생성  → 파이프라인 (잠재적 팬아웃)
Phase 5: 출판            → 파이프라인 (순차)

큰 틀은 Phase 1 → 2 → 3 → 4 → 5라는 파이프라인이다. 각 Phase는 앞 Phase의 산출물에 의존한다. Phase 2는 outline.md가 없으면 시작할 수 없고, Phase 5는 챕터와 SVG가 없으면 시작할 수 없다.

이 파이프라인 안에서 Phase 3이 생성-검증 패턴으로 동작한다. 파이프라인의 직선적 흐름 중간에 루프가 삽입된 구조다. Phase 2에서 넘어온 초안이 Phase 3의 루프를 통과하면, 비로소 Phase 4로 넘어간다.

Chapter 3에서 배운 “큰 틀은 파이프라인으로, 각 Phase 안에서 다른 패턴을 적용”하는 원칙이 그대로 적용된 것이다.

왜 이런 조합이 필요한가? 각 패턴의 장점을 조합하기 위해서다:

파이프라인만으로는 품질 보장이 안 되고, 생성-검증만으로는 전체 워크플로우를 관리할 수 없다. 두 패턴의 결합이 “순서도 보장하고 품질도 보장하는” 하네스를 만든다.

각 에이전트의 정의 파일 해부

이제 5명의 에이전트 정의 파일을 하나씩 분석한다. Chapter 4에서 배운 에이전트 파일의 구조(frontmatter + 핵심 역할 + 작업 원칙 + 출력 형식 + 협업)가 실제로 어떻게 적용되었는지 확인하자.

book-planner: 목차/구조 설계 전문가

---
name: book-planner
description: "책의 목차와 구조를 설계하는 에이전트.
              '목차 설계', '책 구조', 'book plan' 요청 시 트리거."
model: sonnet
---

모델 선택: sonnet. 목차 설계는 정해진 형식에 맞춰 구조화하는 작업이다. 창의적 표현보다는 논리적 구성력이 핵심이므로 sonnet이 적합하다.

핵심 역할 4가지를 보자:

1. 독자 분석: 대상 독자의 수준과 기대를 파악
2. 목차 설계: 논리적 흐름을 가진 챕터 구조 설계
3. 챕터 명세: 각 챕터의 목표, 핵심 내용, 예상 분량 정의
4. 학습 경로: 초보자가 따라갈 수 있는 점진적 난이도 구성

역할이 “무엇을 분석하라”가 아니라 “무엇을 만들어라”로 서술되어 있다. “독자 분석”의 결과물, “목차 설계”의 결과물이 명확하다. Chapter 4에서 배운 “행동 가능한 역할 서술” 원칙이 적용된 것이다.

작업 원칙에서 주목할 것은 “예제 중심(Hands-on) 구조를 우선”이라는 항목이다. 이 원칙 하나가 전체 책의 성격을 결정한다. book-planner가 이 원칙을 따르기 때문에, outline.md의 모든 챕터에 “예제” 항목이 포함된다.

출력 형식이 마크다운 템플릿으로 명시되어 있다는 점도 중요하다. 챕터 명세에 “목표”, “핵심 내용”, “예제”, “분량”이 반드시 포함되도록 강제한다. 이 형식 덕분에 chapter-writer가 받는 입력의 품질이 일정하게 유지된다.

chapter-writer: 챕터 집필 전문가

---
name: chapter-writer
description: "책의 챕터를 집필하는 에이전트.
              '챕터 작성', '집필', 'write chapter' 요청 시 트리거."
model: opus
---

모델 선택: opus. 유일하게 opus를 사용하는 에이전트다. 집필은 복잡한 개념을 쉽게 설명하고, 비유를 만들고, 예제를 구성하는 창의적 작업이다. 이 부분에서 비용을 아끼면 책 전체의 품질이 떨어진다.

핵심 설계 결정은 챕터 구조의 명시다:

## 챕터 구조

# Chapter {N}: {제목}

## 이 챕터에서 배울 것
- bullet points

## 본문
### 개념 설명
### 실습: {예제 제목}
### 심화: {고급 주제}

## 정리
- 핵심 요약 (3-5줄)

## 다음 챕터 미리보기
- 다음에 배울 내용 한 줄 소개

이 구조가 에이전트 정의에 명시되어 있기 때문에, 12개 챕터 모두 동일한 패턴을 따른다. “이 챕터에서 배울 것”으로 시작하고, “다음 챕터 미리보기”로 끝나는 일관성이 독자 경험을 높인다.

작업 원칙에서 “왜 이렇게 하는가를 항상 설명”이라는 항목이 눈에 띈다. 기술서적에서 가장 흔한 실수가 “무엇(what)”만 설명하고 “왜(why)”를 빠뜨리는 것이다. 이 원칙이 있기 때문에 chapter-writer는 모든 설계 결정에 대해 이유를 설명한다. 지금 이 문장처럼.

협업 섹션에서는 입출력 관계가 명확하다:

• book-planner의 목차/명세를 입력으로 받음
• book-editor가 작성된 챕터를 리뷰
• 리뷰 피드백에 따라 수정 반영

이 세 줄이 Phase 2~3의 데이터 흐름을 에이전트 관점에서 정의한다.

book-editor: 원고 리뷰/편집 전문가

---
name: book-editor
description: "원고를 리뷰하고 편집하는 에이전트.
              '원고 리뷰', '편집', 'review chapter' 요청 시 트리거."
model: sonnet
---

모델 선택: sonnet. 리뷰는 체크리스트 기반의 구조화된 평가 작업이다. 창의적 판단보다 기준에 따른 일관된 검증이 중요하므로 sonnet이 적합하다.

이 에이전트의 핵심은 심각도 분류 체계다:

## 작업 원칙
- 심각도 분류: CRITICAL / WARNING / SUGGESTION
- 구체적인 수정 제안 포함 (추상적 피드백 금지)
- 좋은 부분도 언급 (균형 잡힌 리뷰)
- 독자 관점에서 리뷰 (저자 관점 아님)

세 가지 원칙이 Phase 3의 생성-검증 루프를 작동하게 만든다:

1. 심각도 분류: CRITICAL만 루프 조건에 포함되므로, 사소한 SUGGESTION 때문에 루프가 끝없이 도는 것을 방지한다.
2. 구체적 수정 제안: “이 부분이 좀 어색합니다”가 아니라 “이 문단의 비유를 X로 바꾸세요”처럼 actionable한 피드백을 준다. chapter-writer가 피드백을 즉시 반영할 수 있다.
3. 독자 관점: 저자(chapter-writer)의 의도가 아니라, 독자가 이해할 수 있는지를 기준으로 평가한다. 역할 분리의 핵심이다.

출력 형식도 리뷰 결과 템플릿으로 명시되어 있다:

## 리뷰: Chapter {N} — {제목}

### 총평
- 완성도: {상/중/하}
- 주요 이슈: {count}개

### 상세 리뷰

#### [CRITICAL] {위치}
- 문제: {설명}
- 제안: {구체적 수정안}

#### [WARNING] {위치}
- 문제: {설명}
- 제안: {수정 방향}

#### [SUGGESTION] {위치}
- 제안: {개선 아이디어}

### 잘된 점
- {긍정적 피드백}

이 형식이 있기 때문에 오케스트레이터가 “CRITICAL 이슈가 0개인가?”를 기계적으로 판단할 수 있다. 리뷰 결과가 자유 서술이었다면, 루프 종료 여부를 자동으로 결정하기 어려웠을 것이다.

infographic-creator: 인포그래픽 생성 전문가

---
name: infographic-creator
description: "인포그래픽과 다이어그램을 SVG로 생성하는 에이전트.
              '인포그래픽', '다이어그램', 'SVG 생성' 요청 시 트리거."
model: sonnet
---

모델 선택: sonnet. SVG 생성은 XML 구조를 정해진 규칙대로 조합하는 작업이다. 시각적 레이아웃 감각보다 규칙 준수가 중요하므로 sonnet이 적합하다.

이 에이전트의 특징은 구체적인 스타일 규칙이 작업 원칙에 포함되어 있다는 점이다:

## 작업 원칙
- SVG 형식으로 생성 (브라우저/PDF 모두 호환)
- 색상 팔레트: 깔끔한 파스텔 톤 (접근성 고려)
- 폰트: sans-serif 계열
- 파일명: assets/infographic-ch{NN}-{slug}.svg
- 한 SVG에 하나의 개념만 표현
- 텍스트는 최소화, 시각적 표현 우선

“파스텔 톤”, “sans-serif”, “하나의 개념만” — 이런 구체적 규칙이 없으면, 챕터마다 인포그래픽 스타일이 달라진다. 에이전트 정의에서 시각적 일관성을 강제하는 것이다.

협업 섹션도 명확하다: book-planner에게서 시각화 대상을 받고, chapter-writer의 본문에서 참조 위치를 확인하고, 결과를 book-publisher에게 전달한다. 3개의 다른 에이전트와 연결되어 있다.

book-publisher: PDF 조판 + 웹 뷰어 전문가

---
name: book-publisher
description: "PDF 조판과 웹 뷰어를 구현하는 에이전트.
              'PDF 생성', '웹 뷰어', 'publish' 요청 시 트리거."
model: sonnet
---

모델 선택: sonnet. 마크다운 → PDF/HTML 변환은 도구 호출과 설정 작업이다. pandoc이나 weasyprint 같은 도구를 정확히 다루는 것이 핵심이므로 sonnet이 적합하다.

이 에이전트의 특징은 두 가지 출력 포맷을 담당한다는 점이다:

## 출력 형식

### PDF
- `output/pdf/harness-engineering-guide.pdf`
- 표지, 목차, 본문, 부록 포함

### 웹 뷰어
- `output/web/index.html` — 메인 페이지
- 챕터별 페이지 네비게이션
- 반응형 디자인

하나의 에이전트가 PDF와 웹 뷰어 두 가지를 모두 담당한다. “출판 기술”이라는 전문성이 동일하고, 입력(마크다운 + SVG)도 동일하기 때문이다. 만약 PDF와 웹 뷰어의 요구사항이 크게 달라진다면, 그때 에이전트를 분리해도 늦지 않다.

오케스트레이터 스킬 해부

5명의 에이전트를 조율하는 오케스트레이터 스킬을 분석하자. .claude/skills/book-writer/SKILL.md 파일이다.

frontmatter

---
name: book-writer
description: "책 집필 오케스트레이터. 에이전트 팀을 조율하여 책 한 권을 완성합니다.
              '책 집필', '책 쓰기', 'write book' 요청 시 트리거."
---

description에 “오케스트레이터”라는 역할과 “에이전트 팀을 조율”이라는 핵심 기능이 명시되어 있다. 트리거 키워드는 “책 집필”, “책 쓰기”, “write book” — 다양한 표현을 커버한다.

에이전트 팀 테이블

## 에이전트 팀 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `book-planner` | 목차/구조 설계 | sonnet | 1 |
| `chapter-writer` | 챕터 집필 | opus | 2, 3 |
| `book-editor` | 원고 리뷰/편집 | sonnet | 3 |
| `infographic-creator` | SVG 인포그래픽 | sonnet | 4 |
| `book-publisher` | PDF + 웹 뷰어 | sonnet | 5 |

이 테이블이 오케스트레이터의 조감도다. 5명의 에이전트가 누구이고, 무엇을 하고, 어떤 모델을 쓰고, 어느 Phase에 참여하는지를 한눈에 볼 수 있다. Chapter 5에서 배운 “에이전트 구성 테이블 작성법”의 실전 적용이다.

특히 Phase 열을 보면, chapter-writer가 Phase 2와 3에 모두 참여하는 것이 즉시 보인다. 에이전트와 Phase의 매핑이 1:1이 아닌 경우를 테이블로 명시한 것이다.

워크플로우 섹션

오케스트레이터의 워크플로우 섹션에서 각 Phase는 동일한 구조를 따른다:

• 에이전트: 어떤 에이전트가 실행되는가
• 입력: 무엇을 읽는가
• 출력: 무엇을 만드는가
• 검증: 어떻게 확인하는가

이 4항목 구조가 Chapter 5에서 배운 “입력, 처리, 출력, 검증” 원칙의 오케스트레이터 버전이다. Phase 3에는 추가로 프로세스 항목이 있어 생성-검증 루프의 흐름을 명시한다.

실행 방법

## 실행 방법

오케스트레이터(사용자 또는 메인 Claude)가 각 Phase를 순서대로 실행:

Phase 1: Agent tool → book-planner → outline.md 생성 → 사용자 승인
Phase 2: Agent tool → chapter-writer → 챕터 1개씩 순차 집필
Phase 3: Agent tool → book-editor → 리뷰 → chapter-writer → 수정 (반복)
Phase 4: Agent tool → infographic-creator → SVG 생성
Phase 5: Agent tool → book-publisher → PDF + 웹 뷰어

각 Phase 완료 후 사용자 확인을 받고 다음 Phase로 진행.

마지막 한 줄이 핵심이다: “각 Phase 완료 후 사용자 확인을 받고 다음 Phase로 진행.” 완전 자동화가 아니라, 사람이 체크포인트를 관리한다. 12개 챕터의 집필은 몇 시간이 걸리는 작업이다. 중간에 방향이 틀어지면 전체를 다시 해야 하므로, Phase마다 확인하는 것이 합리적이다.

실습: book-writer 하네스를 처음부터 재현하기

지금까지 분석한 내용을 바탕으로, book-writer 하네스를 처음부터 구축하는 과정을 따라가보자. 실제로 하네스를 만드는 7단계를 순서대로 진행한다.

Step 1: 도메인 분석

책 집필이라는 도메인을 분석한다.

도메인: 기술서적 집필
작업 유형: 기획 → 집필 → 리뷰 → 시각화 → 출판
순서 의존성: 있음 (목차 → 본문 → 리뷰 → 인포그래픽 → 최종본)
병렬 가능: 인포그래픽 생성 (챕터별 독립)
품질 보장: 필요 (리뷰 루프)

Chapter 3의 패턴 선택 의사결정 트리를 적용하면:

• Q1: 작업 간 순서 의존성이 있는가? → Yes → 파이프라인
• 추가: 특정 단계에서 반복적 품질 개선이 필요한가? → Yes → 생성-검증 내포

결론: 파이프라인 + 생성-검증 조합.

Step 2: 에이전트 식별

도메인의 전문 영역을 분해한다.

1. 목차 기획     → 기획 전문가 필요
2. 본문 집필     → 작가 필요
3. 원고 리뷰     → 편집자 필요 (작가와 분리 — 역할 충돌 방지)
4. 인포그래픽    → 시각 디자이너 필요
5. PDF/웹 변환   → 출판 기술자 필요

5명의 에이전트가 도출된다. 4가지 분리 기준을 적용하여 검증한다:

• 기획자와 작가를 합칠 수 있나? → 전문성이 다르고, 컨텍스트가 과부하됨 → 분리 유지
• 편집자와 작가를 합칠 수 있나? → 역할 충돌이 심함 → 분리 유지
• 디자이너와 출판 기술자를 합칠 수 있나? → 전문 도구가 다름 (SVG vs pandoc) → 분리 유지

Step 3: 에이전트 정의 파일 작성

5개의 에이전트 파일을 .claude/agents/에 생성한다. 각 파일의 작성 원칙:

book-planner.md
├── model: sonnet (구조화 작업)
├── 핵심 역할: 독자 분석, 목차 설계, 챕터 명세, 학습 경로
├── 작업 원칙: 예제 중심, 점진적 난이도
├── 출력 형식: 목차 마크다운 템플릿 (목표/내용/예제/분량)
└── 협업: chapter-writer에게 명세 전달

chapter-writer.md
├── model: opus (창의적 작업)
├── 핵심 역할: 챕터 집필, 예제 작성, 구조화
├── 작업 원칙: "왜"를 설명, 전문 용어 정의, 실행 가능한 코드
├── 출력 형식: 챕터 구조 템플릿 (배울 것/본문/정리/미리보기)
└── 협업: planner에게서 입력, editor에게 리뷰 받음

book-editor.md
├── model: sonnet (구조화된 평가)
├── 핵심 역할: 품질 검증, 가독성, 코드 정확성, 일관성
├── 작업 원칙: CRITICAL/WARNING/SUGGESTION 분류, 구체적 수정안
├── 출력 형식: 리뷰 결과 템플릿 (총평/상세/잘된 점)
└── 협업: writer의 원고 리뷰, 수정 요청

infographic-creator.md
├── model: sonnet (규칙 기반 생성)
├── 핵심 역할: 아키텍처 다이어그램, 프로세스 플로우
├── 작업 원칙: SVG 형식, 파스텔 톤, 하나의 개념
├── 출력 형식: SVG 파일
└── 협업: planner/writer에게서 입력, publisher에게 전달

book-publisher.md
├── model: sonnet (도구 기반 변환)
├── 핵심 역할: PDF 조판, 웹 뷰어, 에셋 통합
├── 작업 원칙: A4 사이즈, 반응형, 구문 강조
├── 출력 형식: PDF + HTML
└── 협업: writer의 마크다운 + infographic의 SVG 통합

Step 4: 디렉토리 구조 설계

산출물이 저장될 위치를 미리 계획한다.

book/
├── outline.md           # Phase 1: 목차
├── chapters/            # Phase 2~3: 챕터
├── assets/              # Phase 4: 인포그래픽
└── output/              # Phase 5: 최종본
    ├── pdf/
    └── web/

설계 원칙:

1. Phase별 분리: 어떤 Phase의 산출물인지 디렉토리만 보고 알 수 있다
2. 네이밍 규칙 통일: ch{NN}-{slug} 패턴으로 정렬과 참조가 쉽다
3. 입출력 경로 명시: 에이전트가 어디서 읽고 어디에 쓰는지 모호함이 없다

Step 5: 오케스트레이터 스킬 작성

.claude/skills/book-writer/SKILL.md를 작성한다. 핵심은 세 가지다:

1. 에이전트 팀 테이블: 5명의 에이전트, 역할, 모델, Phase 매핑
2. Phase별 워크플로우: 각 Phase의 에이전트/입력/출력/검증
3. 실행 방법: Agent tool로 어떤 순서로 호출하는지

특히 Phase 3의 생성-검증 루프를 오케스트레이터에 명시하는 것이 핵심이다:

### Phase 3: 리뷰 루프 (생성-검증)
- **에이전트**: `book-editor` → `chapter-writer`
- **프로세스**:
  1. `book-editor`가 챕터 리뷰
  2. CRITICAL 이슈가 있으면 `chapter-writer`에게 수정 요청
  3. 수정본을 `book-editor`가 재리뷰
  4. CRITICAL 이슈 0개일 때 승인

루프 종료 조건(“CRITICAL 이슈 0개”)이 오케스트레이터 수준에서 명시되어야, 메인 Claude가 언제 루프를 멈출지 판단할 수 있다.

Step 6: 검증

완성된 하네스를 검증한다. Chapter 5에서 다룬 오케스트레이터 검증 체크리스트를 적용한다:

• 모든 에이전트가 팀 테이블에 포함되어 있는가?
• 각 Phase의 입력이 이전 Phase의 출력과 연결되는가?
• Phase 3의 루프 종료 조건이 명확한가?
• 디렉토리 구조와 파일 네이밍 규칙이 워크플로우와 일치하는가?
• 각 에이전트의 협업 섹션이 오케스트레이터의 데이터 흐름과 일치하는가?

Step 7: 실행

Phase 1부터 순서대로 실행한다.

사용자: "책 집필 시작해줘"
         → book-writer 스킬 트리거
         → Phase 1: book-planner 호출 → outline.md 생성
         → 사용자 확인: "목차 괜찮습니다"
         → Phase 2: chapter-writer 호출 → ch01.md 생성
         → Phase 3: book-editor 호출 → ch01 리뷰 → 수정 → 승인
         → Phase 2~3 반복 (ch02, ch03, ...)
         → Phase 4: infographic-creator 호출 → SVG 생성
         → Phase 5: book-publisher 호출 → PDF + 웹 뷰어 생성

실제로 이 책이 이 과정을 거쳐 만들어졌다.

심화: 설계 결정의 대안과 트레이드오프

book-writer 하네스의 현재 설계가 유일한 정답은 아니다. 다른 선택지와 그 트레이드오프를 살펴보자.

대안 1: 에이전트 수 줄이기

“편집자 없이 작가가 스스로 리뷰하면 안 되나?”

가능하다. chapter-writer에게 “작성 후 스스로 리뷰하라”는 원칙을 추가하면 에이전트 수를 4명으로 줄일 수 있다. 하지만 Chapter 2에서 다뤘듯, 역할 충돌 문제가 발생한다. 글을 쓴 에이전트가 자기 글의 문제를 발견하기 어렵다. 같은 컨텍스트에서 “창의적으로 써라”와 “냉정하게 평가해라”를 동시에 기대하면, 둘 다 중간 수준이 된다.

트레이드오프: 에이전트 수 감소 vs 품질 저하. book-writer 하네스는 품질을 선택했다.

대안 2: 챕터 병렬 집필

“12개 챕터를 동시에 쓰면 빠르지 않나?”

이론적으로는 가능하다. 하지만 앞서 분석했듯, 챕터 간 참조, 용어 일관성, 난이도 곡선 문제가 있다. 병렬로 쓰면 “Chapter 3에서 배운 것처럼”이라는 참조를 쓸 수 없고, 같은 개념을 “오케스트레이터”와 “조율자”라는 다른 용어로 설명하는 불일치가 발생할 수 있다.

트레이드오프: 속도 vs 일관성. book-writer 하네스는 일관성을 선택했다.

대안 3: 리뷰 없는 파이프라인

“Phase 3을 생략하고 바로 인포그래픽으로 넘어가면?”

이 경우 파이프라인만으로 하네스가 구성된다. 단순하고 빠르다. 하지만 chapter-writer가 한 번에 완벽한 챕터를 쓸 가능성은 낮다. 기술적 오류, 논리 비약, 핵심 내용 누락 같은 문제가 최종 PDF에 그대로 남게 된다.

트레이드오프: 속도 vs 품질 보장. book-writer 하네스는 품질 보장을 선택했다.

이 세 가지 대안에서 공통적으로 드러나는 원칙이 있다: 복합 패턴은 복잡하지만, 그 복잡성에는 이유가 있다. 파이프라인만으로 충분한 도메인이라면 생성-검증을 추가할 필요가 없다. 하지만 책 집필처럼 품질이 핵심인 도메인에서는, 생성-검증 루프를 추가하는 복잡성의 대가가 품질 향상으로 돌아온다.

심화: 메타적 관점 — 이 챕터는 어떻게 작성되었는가

이 챕터 자체가 book-writer 하네스의 작동 결과물이라는 점을 잊지 말자. 이 챕터가 만들어진 과정을 복기하면:

1. Phase 1: book-planner가 outline.md에 Chapter 6의 명세를 작성했다. “목표: 이 책을 만든 book-writer 하네스의 전체 구조를 이해하고, 복합 패턴 설계를 할 수 있다”, “분량: 16~18페이지”.

2. Phase 2: chapter-writer(지금 이 글을 쓰고 있는 에이전트)가 outline.md의 명세를 읽고, 챕터 구조(배울 것 → 본문 → 정리 → 미리보기)에 맞춰 집필했다.

3. Phase 3: book-editor가 이 원고를 리뷰했다. “CRITICAL: Phase 3의 생성-검증 루프 설명이 Chapter 3의 패턴 설명과 중복됨 — 이 하네스에 특화된 분석으로 차별화 필요”, “WARNING: 대안 분석 섹션의 트레이드오프가 추상적 — 구체적 수치나 예시 추가 권장” 같은 피드백이 나올 수 있다. chapter-writer가 피드백을 반영하여 수정하고, book-editor가 재리뷰하여 승인한다.

이 순환 구조가 메타적으로 흥미로운 점이다: 이 챕터는 자신이 설명하는 프로세스에 의해 만들어졌다. Chapter 6이 book-writer 하네스를 분석하는 동시에, book-writer 하네스가 Chapter 7을 만든다. 마치 컴파일러가 자기 자신을 컴파일하는 셀프 호스팅(self-hosting)과 같다.

이런 자기 참조가 가능한 이유는, 하네스의 구조가 도메인 독립적이기 때문이다. 에이전트 팀, 오케스트레이터, 파이프라인, 생성-검증 — 이 구조는 “책 집필”이라는 도메인에 종속되지 않는다. 같은 구조로 코드 생성 하네스를 만들 수도 있고, 리서치 팀 하네스를 만들 수도 있다. Chapter 7과 9에서 확인하게 될 것이다.

정리

• book-writer 하네스는 5명의 에이전트(book-planner, chapter-writer, book-editor, infographic-creator, book-publisher)로 구성된다.
• 모델 선택: 창의적 작업(집필)만 opus, 나머지 4명은 sonnet. 비용 대비 품질 최적화.
• 전체 구조는 파이프라인(Phase 1→2→3→4→5)이되, Phase 3에 생성-검증 루프가 내포되어 있다.
• 생성-검증의 핵심 설계: CRITICAL/WARNING/SUGGESTION 심각도 분류, CRITICAL 0개가 루프 종료 조건, 역할 분리(writer vs editor).
• 오케스트레이터 스킬이 에이전트 팀 테이블, Phase별 워크플로우, 실행 방법을 한 파일에 정의한다.
• 산출물 디렉토리는 Phase별로 분리되고, 파일 네이밍은 ch{NN}-{slug} 패턴을 따른다.
• 설계 대안을 검토하면 현재 구조의 트레이드오프가 명확해진다: 에이전트 수 vs 품질, 병렬 vs 일관성, 단순함 vs 품질 보장.
• 이 책 자체가 이 하네스의 산출물이라는 메타적 구조가 하네스의 범용성을 증명한다.

다음 챕터 미리보기

• Chapter 7에서는 팬아웃/팬인 패턴이 주연인 리서치 팀 하네스를 설계한다. 병렬로 조사하고 결과를 통합하는 구조가 book-writer의 순차 파이프라인과 어떻게 다른지, 동시 실행과 결과 통합의 설계 포인트를 배운다.

Chapter 7: 사례 2 — 리서치 팀 하네스 (팬아웃/팬인)

이 챕터에서 배울 것

• 리서치 도메인의 특성 분석: 왜 병렬 처리가 자연스러운가
• 팬아웃/팬인 패턴을 실전에 적용하는 구체적 설계 과정
• 3명의 리서처 + 1명의 분석가 + 1명의 보고서 작성자로 구성된 하네스 구축
• 팬아웃 시 작업을 분배하는 전략: 무엇을 기준으로 나누는가
• 팬인 시 결과를 통합하는 전략: 충돌 해결과 우선순위 설정
• 병렬과 순차를 적절히 조합하는 하이브리드 워크플로우 설계

본문

왜 리서치는 팬아웃/팬인인가

Chapter 3에서 팬아웃/팬인 패턴을 배웠다. 독립적인 하위 작업으로 분할할 수 있고, 최종적으로 결과를 하나로 통합해야 하는 도메인에 적합하다고 했다. 리서치는 이 패턴의 가장 자연스러운 적용 대상이다.

실제 리서치팀이 일하는 방식을 떠올려보자. 팀장이 “생성AI의 엔터프라이즈 도입 현황을 조사해주세요”라는 요청을 받으면, 보통 이렇게 진행한다:

1. 팀장이 조사 주제를 하위 관점으로 분해한다 (기술, 시장, 사례)
2. 팀원 3명이 각자 맡은 관점에서 동시에 조사한다
3. 조사 결과를 모아서 하나의 분석 보고서로 통합한다

핵심은 2번이다. 기술 동향을 조사하는 동안 시장 분석을 기다릴 이유가 없다. 각 조사는 독립적이다. 기술 리서처가 “시장 리서처의 결과가 나올 때까지 기다려야 합니다”라고 말하는 일은 없다.

이것이 리서치가 팬아웃/팬인에 딱 맞는 이유다:

반면, 리서치의 전체 흐름은 순차적이다. 조사 주제를 분해하지 않고 바로 조사할 수는 없고, 조사 결과를 통합하지 않고 보고서를 쓸 수는 없다. 따라서 전체 구조는 파이프라인이고, 중간에 팬아웃/팬인이 내포된 하이브리드 구조가 된다:

[주제 분해] → (팬아웃) [리서처 A] ─┐
              (팬아웃) [리서처 B] ─┼→ [분석가] → [보고서 작성자]
              (팬아웃) [리서처 C] ─┘
                                 (팬인)

Chapter 3에서 다룬 패턴 조합 원칙 — “큰 틀은 파이프라인으로 시작하고, 각 Phase 안에서 다른 패턴을 적용한다” — 의 전형적인 예다.

인포그래픽: 팬아웃/팬인 데이터 흐름도

도메인 분석: 리서치 작업의 구조

하네스를 설계하기 전에 리서치 작업의 구조를 분석해야 한다. “어떤 에이전트가 필요한가”를 먼저 물으면 안 된다. “어떤 작업이 있고, 각 작업의 특성이 무엇인가”를 먼저 물어야 한다. 에이전트는 작업에서 파생되는 것이지, 그 반대가 아니다.

리서치 작업을 단계별로 분해하면 다음과 같다:

단계 1: 주제 분해

리서치 요청을 분석하여 조사할 하위 관점을 도출한다. “생성AI의 엔터프라이즈 도입 현황”이라는 요청을 받으면:

• 기술 관점: 어떤 기술이 사용되는가, 성능과 한계는?
• 시장 관점: 시장 규모, 성장률, 주요 플레이어는?
• 사례 관점: 실제 도입 기업의 성과와 교훈은?

이 단계의 특성: 순차적. 분해 없이 조사를 시작할 수 없다. 또한 분해 결과가 뒤 단계의 작업 수를 결정한다.

단계 2: 관점별 조사

각 관점에 대해 독립적으로 조사한다. 웹 검색, 데이터 수집, 1차 정리를 수행한다.

이 단계의 특성: 병렬 가능. 각 조사는 서로의 결과에 의존하지 않는다. 이 단계가 팬아웃의 대상이다.

단계 3: 결과 통합 분석

개별 조사 결과를 모아서 교차 분석한다. 기술 동향과 시장 트렌드 사이의 상관관계, 사례에서 발견된 패턴, 관점 간 모순되는 정보를 식별한다.

이 단계의 특성: 순차적. 모든 조사 결과가 있어야 교차 분석이 가능하다. 이 단계가 팬인이다.

단계 4: 보고서 작성

분석 결과를 구조화된 보고서로 작성한다. 요약, 상세 분석, 시사점, 권장 사항을 포함한다.

이 단계의 특성: 순차적. 분석이 끝나야 보고서를 쓸 수 있다.

이 분석에서 자연스럽게 에이전트 구성이 도출된다:

왜 리서처는 sonnet이고, 분석가와 보고서 작성자는 opus인가? 리서처의 작업은 정보 수집과 정리다. 검색 결과를 읽고 핵심을 추출하는 작업은 sonnet으로 충분하다. 반면, 분석가는 여러 관점의 정보를 교차 분석하고 인사이트를 도출해야 한다. 보고서 작성자는 긴 문서를 구조적이고 논리적으로 작성해야 한다. 이런 고차원 추론과 긴 출력이 필요한 작업에는 opus가 적합하다.

에이전트 설계

도메인 분석에서 도출된 에이전트를 정의 파일로 구체화한다. 각 에이전트의 파일은 .claude/agents/ 디렉토리에 위치한다.

리서처 에이전트

3명의 리서처는 같은 에이전트 정의를 공유한다. 에이전트를 3개 만드는 것이 아니다. 하나의 리서처 에이전트를 정의하고, 팬아웃 시 서로 다른 입력(관점)을 넣어 3번 호출하는 것이다.

왜 에이전트를 분리하지 않는가? 세 리서처의 전문성은 동일하기 때문이다. 모두 “웹 검색으로 정보를 수집하고 구조화하는” 역할이다. 다른 것은 입력(조사 관점)뿐이다. Chapter 4에서 배운 에이전트 분리 기준 — 전문성이 다를 때 분리한다 — 에 따르면, 이 경우는 분리하지 않는 것이 맞다.

---
name: researcher
description: "리서처. 특정 관점에서 웹 검색과 데이터 수집을 수행하고,
              구조화된 조사 결과를 작성합니다.
              '리서치', 'research', '조사', '검색' 요청 시 트리거."
model: sonnet
---

# Researcher — 리서치 전문가

당신은 주어진 관점에서 철저하게 조사하는 리서치 전문가입니다.

## 핵심 역할
1. **웹 검색**: 주어진 관점에 관련된 정보를 웹에서 검색하고 수집
2. **데이터 정리**: 수집된 정보를 구조화하고 핵심을 추출
3. **출처 관리**: 모든 정보에 출처(URL, 발행일)를 명시
4. **신뢰도 평가**: 수집된 정보의 신뢰도를 평가하고 표시

## 작업 원칙
- Always respond in Korean
- 사실과 의견을 구분한다
- 최신 정보를 우선한다 (1년 이내 자료 우선)
- 하나의 출처에만 의존하지 않는다 (최소 3개 출처 교차 확인)
- 확인되지 않은 정보는 "미확인" 태그를 붙인다

## 출력 형식
조사 결과는 다음 구조로 작성한다:

### {관점명} 조사 결과
- **조사 범위**: 어떤 범위를 조사했는지
- **핵심 발견**: 주요 사실 3~5개 (번호 매김)
- **상세 내용**: 각 발견에 대한 상세 설명
- **출처 목록**: [번호] 출처명, URL, 발행일
- **신뢰도 평가**: 높음/중간/낮음 + 근거

## 협업
- 오케스트레이터로부터 조사 관점과 핵심 질문을 입력받음
- 조사 결과를 파일로 저장하여 분석가 에이전트에게 전달

이 에이전트 정의에서 주목할 점이 있다.

출처 관리와 신뢰도 평가를 명시한 이유. 리서치 결과의 품질은 정보의 정확성에 달려 있다. AI가 검색 결과를 요약할 때 출처 없이 서술하면, 나중에 분석가가 사실 관계를 확인할 방법이 없다. 출처를 반드시 명시하도록 원칙에 넣으면, 분석가가 모순된 정보를 발견했을 때 원본을 추적할 수 있다.

“미확인” 태그. AI는 때때로 확실하지 않은 정보를 확정적으로 서술한다. “미확인 정보에는 태그를 붙여라”는 원칙이 이 문제를 완화한다. 분석가는 미확인 태그가 붙은 정보를 별도로 검증하거나, 보고서에서 제외할 수 있다.

분석가 에이전트

---
name: research-analyst
description: "리서치 분석가. 여러 관점의 조사 결과를 교차 분석하고
              인사이트를 도출합니다.
              '분석', 'analyze', '교차 분석', '통합 분석' 요청 시 트리거."
model: opus
---

# Research Analyst — 리서치 분석가

당신은 다양한 관점의 조사 결과를 종합하여 인사이트를 도출하는 분석 전문가입니다.

## 핵심 역할
1. **교차 분석**: 여러 관점의 조사 결과에서 공통점과 차이점을 식별
2. **모순 식별**: 관점 간 모순되는 정보를 발견하고 해결 방안을 제시
3. **패턴 발견**: 개별 조사에서는 보이지 않는 전체적 패턴과 트렌드를 식별
4. **인사이트 도출**: 데이터에 기반한 핵심 시사점을 정리

## 작업 원칙
- Always respond in Korean
- 개별 조사 결과를 그대로 나열하지 않는다 — 반드시 교차 분석의 부가가치를 만든다
- 모순된 정보는 삭제하지 않고, 양쪽 관점을 모두 제시한 뒤 판단을 명시한다
- 인사이트는 근거 없이 주장하지 않는다 — 반드시 조사 결과의 데이터에 기반한다
- 분석의 한계를 명시한다 (데이터 부족, 편향 가능성 등)

## 출력 형식
분석 결과는 다음 구조로 작성한다:

### 통합 분석 결과
- **핵심 인사이트**: 3~5개의 주요 발견 (중요도순)
- **교차 분석**: 관점 간 상관관계와 시너지
- **모순 사항**: 관점 간 불일치 + 해결/판단
- **정보 공백**: 추가 조사가 필요한 영역
- **분석 한계**: 데이터나 방법론의 제약

## 협업
- 리서처 에이전트들의 조사 결과 파일을 입력으로 받음
- 분석 결과를 파일로 저장하여 보고서 작성자 에이전트에게 전달

분석가 에이전트의 핵심은 “부가가치”다. 조사 결과를 단순히 합치는 것은 분석이 아니다. 개별 조사에서는 보이지 않던 것을 발견하는 것이 분석가의 존재 이유다. “개별 조사 결과를 그대로 나열하지 않는다”는 원칙이 이 점을 강제한다.

보고서 작성자 에이전트

---
name: report-writer
description: "보고서 작성자. 분석 결과를 구조화된 보고서로 작성합니다.
              '보고서', 'report', '작성' 요청 시 트리거."
model: opus
---

# Report Writer — 보고서 작성 전문가

당신은 분석 결과를 명확하고 구조화된 보고서로 변환하는 전문가입니다.

## 핵심 역할
1. **구조 설계**: 보고서의 전체 구조(목차)를 독자 관점에서 설계
2. **본문 작성**: 분석 결과를 논리적이고 읽기 쉬운 문체로 작성
3. **시각화 제안**: 데이터를 효과적으로 전달할 표/차트를 설계
4. **권장 사항 작성**: 분석에 기반한 구체적이고 실행 가능한 권장 사항을 제시

## 작업 원칙
- Always respond in Korean
- 독자가 전문가가 아닐 수 있다 — 전문 용어에는 간단한 설명을 덧붙인다
- 요약 → 상세의 순서로 작성한다 (바쁜 독자는 요약만 읽을 수 있어야 한다)
- 모든 주장에는 데이터 근거를 표시한다 (분석 결과의 어느 부분에 기반하는지)
- 보고서 분량은 사용자가 지정하지 않으면 A4 5~10페이지 수준으로 작성한다

## 출력 형식

### {주제} 리서치 보고서
1. **요약 (Executive Summary)**: 핵심 발견과 권장 사항 1페이지 요약
2. **배경**: 조사 배경과 목적
3. **분석 결과**: 주제별 상세 분석 (표, 비교 포함)
4. **시사점**: 분석에서 도출된 의미
5. **권장 사항**: 구체적이고 실행 가능한 행동 제안
6. **부록**: 출처 목록, 조사 방법론, 용어 정의

## 협업
- 분석가 에이전트의 통합 분석 결과를 입력으로 받음
- 최종 보고서를 파일로 저장

보고서 작성자에서 가장 중요한 원칙은 “요약 → 상세” 구조다. 보고서를 읽는 사람은 보통 바쁘다. 10페이지 보고서를 처음부터 끝까지 읽는 사람은 드물다. 첫 페이지의 Executive Summary만으로 핵심을 파악할 수 있어야 한다. 상세 내용은 관심 있는 사람만 읽으면 된다.

오케스트레이터 스킬 설계

에이전트가 정의되었으면, 이들을 조율하는 오케스트레이터 스킬을 설계한다. 오케스트레이터는 .claude/skills/research-team/SKILL.md에 위치한다.

전체 구조

.claude/
├── agents/
│   ├── researcher.md           # 리서처 (3번 병렬 호출)
│   ├── research-analyst.md     # 분석가
│   └── report-writer.md        # 보고서 작성자
└── skills/
    └── research-team/
        ├── SKILL.md             # 오케스트레이터 스킬
        └── references/
            └── report-template.md  # 보고서 템플릿

산출물은 다음 디렉토리에 저장된다:

research/
├── brief.md                    # Phase 1: 주제 분해 결과
├── findings/                   # Phase 2: 리서처별 조사 결과
│   ├── perspective-01.md
│   ├── perspective-02.md
│   └── perspective-03.md
├── analysis.md                 # Phase 3: 통합 분석 결과
└── report.md                   # Phase 4: 최종 보고서

왜 산출물 디렉토리를 이렇게 설계하는가? 두 가지 원칙이 있다.

첫째, Phase별로 산출물이 구분된다. brief.md는 Phase 1, findings/는 Phase 2, analysis.md는 Phase 3, report.md는 Phase 4의 산출물이다. 문제가 생겼을 때 어느 Phase의 결과물에 이슈가 있는지 파일만 보고 특정할 수 있다.

둘째, 팬아웃 결과는 디렉토리로 묶는다. 리서처 3명의 결과물은 findings/ 디렉토리에 모인다. perspective-01.md, perspective-02.md, perspective-03.md로 번호를 매기면 몇 명이 조사했는지, 어떤 결과물이 누락되었는지 한눈에 파악할 수 있다.

오케스트레이터 스킬 전체 코드

이제 오케스트레이터 스킬의 전체 코드를 작성한다. 코드가 길지만, 각 Phase를 별도 섹션으로 분리했으므로 순서대로 읽으면 된다.

---
name: research-team
description: "리서치 팀 오케스트레이터. 리서치 요청을 분석하고,
              3명의 리서처로 병렬 조사한 뒤 분석가가 통합 분석하여
              보고서를 생성합니다.
              '리서치 팀', 'research team', '종합 조사' 요청 시 트리거."
---

# Research Team — 리서치 팀 오케스트레이터

리서치 요청을 받아 주제를 분해하고, 병렬로 조사한 뒤,
결과를 통합 분석하여 구조화된 보고서를 생성하는 워크플로우.

## 에이전트 구성

| 에이전트 | 역할 | 모델 | Phase |
|---------|------|------|-------|
| `researcher` | 관점별 웹 검색 및 조사 | sonnet | 2 (x3 병렬) |
| `research-analyst` | 교차 분석 및 인사이트 도출 | opus | 3 |
| `report-writer` | 최종 보고서 작성 | opus | 4 |

## 워크플로우

### Phase 1: 주제 분해 (오케스트레이터 직접 수행)
- **입력**: 사용자의 리서치 요청
- **처리**:
  1. 리서치 요청을 분석하여 핵심 질문을 도출한다
  2. 핵심 질문을 3개의 독립적인 조사 관점으로 분해한다
  3. 각 관점별로 조사 범위와 핵심 질문을 정리한다
- **출력**: `research/brief.md`
  - 원본 요청
  - 핵심 질문
  - 관점별 조사 지시서 (관점명, 조사 범위, 핵심 질문 3~5개)
- **검증**:
  - 관점들이 서로 겹치지 않는지 확인
  - 모든 관점을 합하면 원본 요청을 충분히 커버하는지 확인
  - 각 관점이 독립적으로 조사 가능한지 확인
- **사용자 확인**: 분해 결과를 사용자에게 보여주고 승인을 받는다

### Phase 2: 관점별 조사 (팬아웃)
- **에이전트**: `researcher` (관점 수만큼 병렬 호출)
- **입력**: `research/brief.md`의 관점별 조사 지시서
- **처리**:
  1. 각 리서처에게 하나의 관점과 핵심 질문을 전달한다
  2. 리서처는 웹 검색으로 정보를 수집하고 구조화한다
  3. 각 리서처는 독립적으로 작업한다 — 다른 리서처의 결과를 참조하지 않는다
- **출력**: `research/findings/perspective-{NN}.md` (관점별 1개)
- **병렬 실행 규칙**:
  - 각 리서처는 서브 에이전트로 호출한다
  - 모든 리서처가 완료될 때까지 Phase 3으로 진행하지 않는다
  - 한 리서처가 실패하면, 해당 관점만 재시도한다 (다른 결과는 유지)
- **검증**:
  - 모든 관점에 대해 조사 결과 파일이 생성되었는지 확인
  - 각 파일에 핵심 발견, 출처 목록, 신뢰도 평가가 포함되었는지 확인
  - 출처가 최소 3개 이상인지 확인

### Phase 3: 통합 분석 (팬인)
- **에이전트**: `research-analyst`
- **입력**: `research/findings/perspective-*.md` (모든 조사 결과)
- **처리**:
  1. 모든 조사 결과를 읽는다
  2. 관점 간 공통점과 차이점을 식별한다
  3. 모순되는 정보를 발견하면 양쪽 근거를 비교하여 판단한다
  4. 개별 조사에서 보이지 않는 전체적 패턴을 도출한다
  5. 추가 조사가 필요한 정보 공백을 식별한다
- **출력**: `research/analysis.md`
- **검증**:
  - 모든 관점의 핵심 발견이 분석에 반영되었는지 확인
  - 모순 사항이 식별되고 판단이 내려졌는지 확인
  - 인사이트에 근거 데이터가 명시되었는지 확인
- **사용자 확인**: 분석 결과를 사용자에게 보여주고 승인을 받는다

### Phase 4: 보고서 작성
- **에이전트**: `report-writer`
- **입력**: `research/analysis.md` + `research/findings/perspective-*.md`
- **처리**:
  1. `references/report-template.md`의 구조를 참고하여 보고서를 작성한다
  2. 분석 결과의 인사이트를 중심으로 서술한다
  3. 필요한 곳에 표를 사용하여 비교/정리한다
  4. Executive Summary를 마지막에 작성한다 (전체 내용 파악 후 요약)
- **출력**: `research/report.md`
- **검증**:
  - Executive Summary가 보고서의 핵심을 정확히 반영하는지 확인
  - 모든 주장에 근거가 표시되었는지 확인
  - 권장 사항이 구체적이고 실행 가능한지 확인
- **사용자 확인**: 최종 보고서를 사용자에게 보여주고 수정 요청을 받는다