Harness

harness - Agent Team & Skill Architect

Keyword: harness · build a harness · design agent team · harness engineering

>

Meta-skill: harness designs the teams and skills that run your domain work.

Harness decomposes complex tasks into coordinated teams of specialized agents. It analyzes your domain, selects the right architecture pattern, generates agent definition files and skills, then validates the harness end-to-end.

Agent Teams require: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

When to use this skill

• Decompose a complex project into a coordinated multi-agent team
• Choose the right architecture: pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor, or hierarchical delegation
• Generate .claude/agents/{name}.md agent definition files
• Generate .claude/skills/{name}/SKILL.md skill files with bundled resources
• Validate trigger conditions, dry-run teams, and compare with/without harness quality
• Build harnesses for: research, coding, content creation, code review, data pipelines, marketing

Instructions

Step 1: Domain Analysis

Analyze the task and project context:

1. Read the codebase or user request to identify the domain, sub-tasks, and outputs 2. Detect user expertise level (beginner → detailed scaffolding; expert → lean definitions) 3. List the distinct task types — these map to agent roles 4. Decide execution mode:

• Agent Team (default): 2+ agents need to communicate or cross-validate → use TeamCreate + SendMessage
• Sub-agents (lightweight): tasks are independent and results only return to orchestrator → use Agent tool

Step 2: Team Architecture Design

Choose a pattern based on task structure (see references/agent-design-patterns.md):

Key rules:

• Agent teams are the default; choose sub-agents only when no inter-agent communication is needed
• All agents must be file-based (.claude/agents/{name}.md) — never embed roles inline in Agent tool prompts
• Avoid nesting teams (team members cannot themselves create teams)
• Maximum 2 levels for hierarchical delegation

Step 3: Generate Agent Definition Files

Create .claude/agents/{agent-name}.md for each agent. Use this template:

---
name: {agent-name}
description: {role and activation conditions}
model: opus
allowed-tools: {tool list}
---

# {Agent Name}

## Core Responsibilities
- {primary responsibility 1}
- {primary responsibility 2}

## Operational Principles
1. {principle 1}
2. {principle 2}

## Input Protocol
- Receives: {what inputs this agent consumes}
- Format: {expected format}

## Output Protocol
- Produces: {what outputs this agent delivers}
- Format: {output format and location}

## Error Handling
- On failure: {recovery behavior}
- Escalation: {when to notify orchestrator}

## Team Communication
- Reports to: {orchestrator or peer}
- Communicates with: {peer agents via SendMessage}
- Completion signal: {how to signal done}

Use model: opus for all agents by default unless speed is critical.

Step 4: Generate Skill Files

For each skill the team needs, create .claude/skills/{skill-name}/SKILL.md following the Agent Skills spec:

1. Write a "pushy" description — actively invites triggering with specific conditions and synonyms 2. Explain why (context), not just what (commands) 3. Keep SKILL.md under 500 lines — move detailed docs to references/ 4. Bundle reusable logic in scripts/ 5. Apply progressive disclosure: metadata → body → references

For the orchestrator skill template, see references/orchestrator-template.md. For team architecture examples, see references/team-examples.md.

Step 5: Integration & Orchestration

Define the full workflow in the orchestrator skill or agent:

Before running: ensure CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set in your environment for agent team mode.

1. Specify phase dependencies (which agents must complete before the next phase starts) 2. Define data passing: use absolute paths anchored to _workspace/ for intermediate artifacts 3. Add error handling for agent failures, timeouts, and data conflicts 4. Preserve intermediate artifacts for post-execution verification — do not delete them

Step 6: Validation & Testing

Run validation to verify the harness before use:

bash scripts/validate-harness.sh .claude/agents/ .claude/skills/

Validation checks:

• Structure: required sections present in agent definition files
• Trigger conditions: 20 eval queries (10 should-trigger + 10 should-NOT-trigger)
• Dry run: simulate team execution without running real tasks
• Comparative: quality with harness vs without (baseline) — target +50% score improvement

For testing methodology, see references/skill-testing-guide.md.

Examples

Example 1: Research Harness (Fan-out/Fan-in)

Prompt: "Build a harness for deep technology research"

Generated agents:
  .claude/agents/official-researcher.md    — documentation & official sources
  .claude/agents/media-researcher.md       — investment trends & news
  .claude/agents/community-researcher.md   — social response & forums
  .claude/agents/background-researcher.md  — competitive landscape
  .claude/agents/research-orchestrator.md  — synthesizes findings

Pattern: Fan-out/Fan-in (4 parallel researchers → orchestrator)

Example 2: Code Review Harness (Expert Pool)

Prompt: "Design an agent team for thorough code review"

Generated agents:
  .claude/agents/security-reviewer.md      — OWASP, injection, secrets
  .claude/agents/performance-reviewer.md   — complexity, memory, latency
  .claude/agents/testing-reviewer.md       — coverage, assertions, mocks
  .claude/agents/review-orchestrator.md    — consolidates findings

Key feature: reviewers communicate directly (cross-domain issue detection)

Example 3: Content Production Harness (Pipeline + Parallel)

Prompt: "Build a harness for webtoon production"

Phase 1 (parallel): worldbuilder + character-designer + plot-architect
Phase 2 (sequential): prose-stylist writes based on Phase 1
Phase 3 (parallel): science-consultant + continuity-manager review
Phase 4 (sequential): prose-stylist incorporates feedback

Best practices

1. File-based agents always — embedding roles inline in Agent tool prompts prevents reuse across sessions 2. Agent teams by default — prefer TeamCreate + SendMessage over sub-agents for any work requiring coordination 3. "Pushy" descriptions — passive descriptions mean skills never activate; write active invitations 4. Explain why, not just what — agents follow reasoning better than rigid commands 5. Preserve intermediate artifacts — _workspace/ files enable post-run verification and debugging 6. Validate before deploy — run trigger eval (20 queries) and dry-run before using the harness in production 7. Max 2 hierarchy levels — deeper nesting creates coordination overhead without quality gains

References

• Agent Design Patterns
• Orchestrator Template
• Team Examples
• Skill Writing Guide
• Skill Testing Guide
• harness GitHub
• Agent Skills Specification

Agent Design Patterns

Reference for harness skill — choose the right execution pattern for your domain.

---

Execution Modes

Agent Teams (Default)

Uses TeamCreate to assemble independent Claude instances. Team members:

• Communicate directly via SendMessage
• Share task lists via TaskCreate / TaskUpdate
• Work semi-autonomously in parallel

Use when: Agents need to cross-validate, share intermediate results, or coordinate without going through an orchestrator.

TeamCreate → assign roles → agents run + communicate via SendMessage → orchestrator synthesizes

Sub-agents (Lightweight)

Uses the Agent tool. Results flow only back to the calling agent.

Use when: Tasks are fully independent and no inter-agent communication is needed.

Agent(task1) + Agent(task2) → results return to main agent only

---

Architecture Patterns

1. Pipeline

Sequential stages where output feeds the next step.

[Stage A] → [Stage B] → [Stage C] → [Output]

Best for: Design → Code → Review → Deploy, document processing, ETL flows.

Key rule: Define clear data contracts between stages. Use _workspace/stage-{n}-output/ paths.

---

2. Fan-out / Fan-in

Parallel independent workers whose outputs are merged by an orchestrator.

             ┌→ [Worker A] →┐
[Input] ──── ├→ [Worker B] →┤ ── [Synthesizer] → [Output]
             └→ [Worker C] →┘

Best for: Multi-angle research, parallel code analysis, competitive landscape scans.

Key rule: Workers must not depend on each other. Synthesizer runs after all workers complete.

---

3. Expert Pool

Context-dependent dynamic routing to the most appropriate specialist.

[Router] ──→ specialist A (if security issue)
         ──→ specialist B (if performance issue)
         ──→ specialist C (if style issue)

Best for: Code review, customer support routing, domain-specific Q&A.

Key rule: Routing criteria must be explicit and deterministic. Specialists may communicate directly for cross-domain issues.

---

4. Producer-Reviewer

Generation paired with validation cycles.

[Producer] → [Reviewer] → feedback → [Producer] → [Reviewer] → ...
                                                              → PASS

Best for: Content creation with quality gates, code generation + testing, spec + implementation.

Key rule: Define PASS/FIX/REDO criteria explicitly. Set a maximum revision loop (recommended: 2–3).

---

5. Supervisor

Central coordinator dynamically assigns work to workers at runtime.

[Supervisor]
    ├── assigns task batch to Worker A
    ├── assigns task batch to Worker B
    └── reallocates based on progress

Best for: Code migrations, large-scale file processing, dynamic workload balancing.

Key rule: Workers claim tasks and report completion. Supervisor must handle reassignment when a worker stalls.

---

6. Hierarchical Delegation

Top-down recursive decomposition. Maximum 2 levels.

[PM / Orchestrator]
    ├── [Tech Lead A] → [Engineer 1] + [Engineer 2]
    └── [Tech Lead B] → [Engineer 3] + [Engineer 4]

Best for: Large engineering projects with sub-teams, nested domain expertise.

Key rule: Never nest beyond 2 levels. Team members cannot create their own teams.

---

Pattern Selection Guide

---

Agent Definition Rules

1. All agents must be file-based: .claude/agents/{name}.md 2. Embedding roles inline in Agent tool prompts is prohibited — file definitions enable session reuse 3. Use model: opus as default; model: sonnet for lighter tasks 4. Every agent definition must include: name, description, model, allowed-tools 5. Recommended sections: Core Responsibilities, Input Protocol, Output Protocol, Error Handling, Team Communication

Harness Architecture Patterns

Use this file when the correct topology is not obvious.

Pattern chooser

Selection rules

1. If tasks must happen in a strict order, use pipeline. 2. If multiple viewpoints can explore the same input independently, use fan-out/fan-in. 3. If quality review must challenge generation before handoff, use producer-reviewer. 4. If only some experts are needed depending on input, use expert-pool. 5. If the work queue changes during execution, use supervisor. 6. If one pattern fits discovery and another fits delivery, use hybrid.

Ownership rule

No matter which pattern you choose, assign file ownership before execution. Two parallel lanes editing the same file is a harness bug, not a coordination detail.

Native vs adapter note

On Claude, these patterns can map closely to Agent Teams. On other platforms, keep the pattern description stable and swap only the transport layer.

Orchestrator Skill Template

Templates for creating orchestrator skills that coordinate agent teams.

---

Template A: Agent Team Mode (Default)

Use when agents need to communicate or cross-validate.

---
name: {domain}-orchestrator
description: >
  Orchestrate the {domain} agent team. Coordinates {N} specialists
  through {pattern} execution. Use when {trigger conditions}.
model: opus
allowed-tools: Bash Read Write Edit Glob Grep Agent TeamCreate TaskCreate TaskUpdate SendMessage
---

# {Domain} Orchestrator

## Phase 0: Preparation

1. Analyze input and define workspace root: `_workspace/{run-id}/`
2. Create task manifest: `_workspace/{run-id}/tasks.json`
3. Initialize output directories for each agent

## Phase 1: Team Assembly

TeamCreate: members:

• name: {agent-a}

definition: .claude/agents/{agent-a}.md

• name: {agent-b}

definition: .claude/agents/{agent-b}.md

Assign initial tasks via TaskCreate. Set status to `pending`.

## Phase 2: Parallel Execution

Each agent:
1. Claims tasks (TaskUpdate → in_progress)
2. Does work, writes outputs to `_workspace/{run-id}/{agent-name}/`
3. Communicates discoveries to peers via SendMessage (if fan-out or expert pool)
4. Marks tasks done (TaskUpdate → completed)
5. Signals orchestrator

## Phase 3: Integration

After all agents complete:
1. Read outputs from `_workspace/{run-id}/*/`
2. Merge, deduplicate, resolve conflicts
3. Generate final deliverable at `_workspace/{run-id}/final-output.{ext}`

## Phase 4: Cleanup

1. Archive `_workspace/{run-id}/` — do not delete intermediate artifacts
2. Write summary to `_workspace/{run-id}/run-summary.md`
3. Report results to user

---

Template B: Sub-Agent Mode (Lightweight)

Use when tasks are independent and no cross-agent communication is needed.

---
name: {domain}-runner
description: >
  Run {N} independent {domain} sub-tasks in parallel. Use when
  {trigger conditions} and agents do not need to communicate.
model: sonnet
allowed-tools: Bash Read Write Edit Glob Grep Agent
---

# {Domain} Runner

## Step 1: Preparation

Parse input, define output paths, create `_workspace/{run-id}/`.

## Step 2: Sub-Agent Invocation

Invoke agents via Agent tool. Run independent agents in parallel:

Agent(task="...", definition=".claude/agents/{agent-a}.md") Agent(task="...", definition=".claude/agents/{agent-b}.md")

Wait for all to complete before proceeding.

## Step 3: Integration

Collect results from each agent's output path.
Merge into final deliverable.

## Step 4: Output

Write `_workspace/{run-id}/final-output.{ext}` and summarize for user.

---

Data Passing Conventions

Always use absolute paths. Relative paths break when agents change working directory.

---

Error Handling Scenarios

Harness Platform Adaptation

Use this note when the user wants Harness ideas outside Claude Code.

Core translation rule

Harness is fundamentally:

• agent roster design
• orchestration pattern selection
• skill scaffolding
• validation loop definition

Those ideas are portable even when file paths are not.

Mapping

Claude Code

• closest to upstream revfactory/harness
• use .claude/agents/ and .claude/skills/

Codex CLI

• map agent roster to .codex/agents/ or equivalent role prompts
• map skill scaffolding to .codex/skills/
• keep orchestration rules in repo-level docs when direct equivalents are missing

Gemini / Antigravity

• preserve the orchestration pattern
• adapt output to the Antigravity workflow or skill surface

OpenCode / Pi / Claw

• prioritize reusable prompts, skill docs, and deterministic scripts
• document missing native features rather than inventing fake compatibility

Non-goal

Do not claim that every platform supports the same team APIs or plugin commands.

Platform Adapters

Use this file when the target runtime is not Claude-native.

Principle

Keep the harness neutral under .harness/ and map execution at the edge. Do not bake vendor-specific transport primitives into the architecture itself.

Adapter matrix

Portable artifact contract

Create these directories first:

.harness/
├── agents/
├── skills/
├── workspace/
└── manifests/

Then add platform-specific entry points only if the runtime needs them.

What to avoid

• claiming TeamCreate, shared task lists, or teammate messaging outside native runtimes
• mixing platform config with the portable harness specification
• forcing every runtime to use the same file path conventions

Skill Writing Guide

How to write effective skill files for agent teams generated by harness.

---

Core Principle: Description Quality

Claude decides whether to use a skill based on name + description alone (Tier 1 catalog). A weak description means the skill never activates.

Write descriptions that are "pushy" — actively invite triggering with:

• What the skill does (specific operations)
• When to trigger (conditions, not just domain)
• Synonyms and alternative phrasings users might type

# WEAK — never triggers
description: Helps with API design.

# STRONG — reliably triggers
description: >
  Design and document REST and GraphQL APIs: endpoint structure, request/response
  schemas, versioning, auth patterns, OpenAPI spec generation, and error conventions.
  Use when you need to design a new API, review an existing one, or generate
  OpenAPI documentation. Triggers on: api design, rest endpoint, graphql schema,
  openapi spec, swagger, api versioning, http method, api contract.

---

Body Style

1. Imperative — "Run X", "Read Y", not "You should run X" 2. Why before what — explain the reason; agents follow reasoning better than commands 3. Concrete over abstract — specific file paths, flag names, command examples 4. Context-budget-aware — explain where mistakes are likely; skip obvious steps

---

Progressive Disclosure Structure

Move detailed docs to references/ to keep SKILL.md under 500 lines.

---

Standard SKILL.md Template

---
name: {skill-name}
description: >
  {What it does — specific operations.}
  Use when {trigger conditions}. Triggers on: {keyword list}.
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  tags: tag1, tag2, tag3
  version: "1.0"
---

# {Skill Title}

## When to use this skill
- {Scenario 1}
- {Scenario 2}

## Instructions

### Step 1: {Action}
Why: {reason this step matters}
How: {concrete command or action}

### Step 2: {Action}
...

## Examples

### Example 1: {Scenario}
Input: ...
Expected output: ...

## Best practices
1. {Practice 1}
2. {Practice 2}

## References
- [{Reference title}](references/{file}.md)

---

Bundling Scripts

Reusable or complex shell logic belongs in scripts/:

skill-name/
├── SKILL.md
├── scripts/
│   ├── install.sh        # setup / dependency check
│   └── run-{task}.sh     # primary operation wrapper
├── references/
│   └── {topic}.md
└── evals/
    └── evals.json

Script rules:

• No interactive prompts — agents run in non-interactive shells; use flag inputs only
• Structured output — prefer JSON/CSV to stdout; diagnostics to stderr
• Exit codes — 0 = success, 1 = error, 2 = findings/warnings (same convention as strix, validate-harness)
• Absolute paths — never assume current working directory

---

Evaluation Test Cases

Create evals/evals.json with 2–5 realistic prompts before publishing:

{
  "skill_name": "your-skill-name",
  "evals": [
    {
      "id": 1,
      "prompt": "Realistic user message that should trigger this skill",
      "expected_output": "What success looks like",
      "assertions": [
        "Specific verifiable claim (file exists, command present, count correct)",
        "Another verifiable claim"
      ]
    }
  ]
}

Good assertions are verifiable: file exists, JSON is valid, command flag appears. Bad assertions: "output is good", "response is helpful".

Trigger validation: write 20 queries (10 should-trigger + 10 should-NOT-trigger) to confirm the description activates on the right prompts and not on unrelated ones.

---

What NOT to include in a skill

• README or CHANGELOG content
• Test results or benchmark data
• User-facing manuals
• General knowledge that Claude already knows
• Anything that changes faster than the skill update cycle (use references/ for volatile content)

Team Examples

Real-world harness configurations for common domains.

---

Example 1: Deep Research Team (Fan-out/Fan-in)

Domain: Technology or market research Pattern: Fan-out/Fan-in Mode: Agent Team

Agent definitions:

.claude/agents/official-researcher.md      — documentation, official sources, whitepapers
.claude/agents/media-researcher.md         — investment trends, news, analyst coverage
.claude/agents/community-researcher.md     — forums, social media, practitioner sentiment
.claude/agents/background-researcher.md    — competitive landscape, historical context
.claude/agents/research-orchestrator.md    — synthesizes all four lanes into report

Workflow: 1. Orchestrator assigns one topic to each researcher 2. Four researchers run in parallel 3. Researchers may SendMessage to share cross-domain discoveries 4. After all complete, orchestrator synthesizes findings 5. Final output: _workspace/{run-id}/research-report.md

---

Example 2: Website Development Team (Pipeline)

Domain: Full-stack web development Pattern: Pipeline with parallel phases Mode: Agent Team

.claude/agents/ux-designer.md              — wireframes, component spec, accessibility
.claude/agents/frontend-engineer.md        — React/Next.js implementation
.claude/agents/backend-engineer.md         — API design and implementation
.claude/agents/qa-engineer.md              — testing, validation, cross-checking
.claude/agents/dev-orchestrator.md         — coordinates phases and integrates

Workflow:

Phase 1: ux-designer produces spec
Phase 2: frontend + backend run in parallel (both consume Phase 1 spec)
Phase 3: qa-engineer validates both outputs
Phase 4: dev-orchestrator integrates and delivers

---

Example 3: Code Review Team (Expert Pool)

Domain: Code quality assurance Pattern: Expert Pool Mode: Agent Team (direct peer communication)

.claude/agents/security-reviewer.md        — OWASP Top 10, injection, secrets, auth
.claude/agents/performance-reviewer.md     — complexity, memory leaks, latency, caching
.claude/agents/testing-reviewer.md         — coverage, assertions, mocks, edge cases
.claude/agents/review-orchestrator.md      — routes issues, consolidates report

Key feature: Reviewers communicate directly with each other (no orchestrator mediation) for cross-domain issues:

security-reviewer sends: "Found unvalidated input at line 42 — may affect performance caching too"
performance-reviewer responds: "Confirmed — affects query cache invalidation logic"

---

Example 4: Content Production Team (Producer-Reviewer)

Domain: Webtoon / comic production Pattern: Pipeline + Producer-Reviewer Mode: Sub-agent (simpler for sequential work)

.claude/agents/story-writer.md             — plot, dialogue, narrative arc
.claude/agents/visual-director.md          — panel layout, scene descriptions
.claude/agents/continuity-reviewer.md      — consistency check (characters, plot, style)

Workflow:

story-writer → visual-director → continuity-reviewer
                                      ↓ (PASS or FIX)
                              story-writer (revision)
                                      ↓ (max 2 loops)
                              Final output

Reviewer evaluation framework:

• PASS — meets all quality criteria, proceed
• FIX — specific issues listed, one revision needed
• REDO — fundamental problems, restart from previous phase

---

Example 5: Supervisor Pattern — Code Migration (Supervisor)

Domain: Large-scale refactoring or migration Pattern: Supervisor Mode: Agent Team

.claude/agents/migration-supervisor.md     — analyzes files, estimates complexity, assigns batches
.claude/agents/migrator-a.md               — claims and processes assigned file batches
.claude/agents/migrator-b.md               — claims and processes assigned file batches

Workflow:

Supervisor:
  1. Scans all files to migrate
  2. Estimates complexity per file
  3. Assigns batch to Migrator A (low-complexity files)
  4. Assigns batch to Migrator B (high-complexity files)
  5. Monitors progress via TaskGet
  6. Reallocates stalled tasks to available migrators

Migrators:
  1. TaskUpdate → in_progress
  2. Process file
  3. Write output to _workspace/migrations/{filename}
  4. TaskUpdate → completed
  5. Report to Supervisor via SendMessage

---

Agent Definition Template

Full example for the worldbuilder agent:

---
name: worldbuilder
description: >
  Build the world context for a creative project — setting, rules, history, geography.
  Activate when a creative project needs coherent world-building before writing begins.
model: opus
allowed-tools: Read Write Bash
---

# Worldbuilder

## Core Responsibilities
- Define setting: time period, geography, social structure, technology level
- Establish world rules: physics, magic systems, political systems
- Document history: key events that shaped the current state
- Ensure internal consistency across all world elements

## Operational Principles
1. Ground every element in cause-and-effect logic — no arbitrary rules
2. Create constraints that generate interesting narrative tension
3. Leave deliberate gaps for other agents (character-designer, plot-architect) to fill

## Input Protocol
- Receives: project brief, genre, tone, target audience from orchestrator
- Format: plain text or structured brief in `_workspace/{run-id}/brief.md`

## Output Protocol
- Produces: `_workspace/{run-id}/worldbuilder/world-bible.md`
- Format: structured markdown with sections for Setting, Rules, History, Geography

## Error Handling
- On ambiguity: make explicit assumption and document it in world-bible
- On conflict with other agents: flag in `_workspace/{run-id}/conflicts.md`

## Team Communication
- Reports to: creative-orchestrator
- Communicates with: character-designer (character constraints), plot-architect (world events)
- Completion signal: SendMessage to orchestrator with path to world-bible.md

Agent Team Design Patterns

실행 모드: 에이전트 팀 vs 서브 에이전트

두 가지 실행 모드의 핵심 차이를 이해하고 적합한 모드를 선택한다.

에이전트 팀 (Agent Teams) — 기본 모드

팀 리더가 TeamCreate로 팀을 구성하고, 팀원들은 독립적인 Claude Code 인스턴스로 실행된다. 팀원들은 SendMessage로 직접 통신하고, 공유 작업 목록(TaskCreate/TaskUpdate)으로 자체 조율한다.

[리더] ←→ [팀원A] ←→ [팀원B]
  ↕          ↕          ↕
  └──── 공유 작업 목록 ────┘

핵심 도구:

• TeamCreate: 팀 생성 + 팀원 스폰
• SendMessage({to: name}): 특정 팀원에게 메시지
• SendMessage({to: "all"}): 브로드캐스트 (비용 높음, 드물게)
• TaskCreate/TaskUpdate: 공유 작업 목록 관리

특징:

• 팀원끼리 직접 대화, 도전, 검증 가능
• 리더가 거치지 않고 팀원 간 정보 교환
• 공유 작업 목록으로 자체 조율 (자체 작업 요청 가능)
• 팀원이 유휴 상태가 되면 자동으로 리더에게 알림
• 계획 승인 모드로 위험한 작업 전 검토 가능

제약:

• 세션당 한 팀만 활성화 가능 (단, Phase 간에 팀을 해체하고 새 팀 구성은 가능)
• 중첩 팀 불가 (팀원이 자신의 팀 생성 불가)
• 리더 고정 (이전 불가)
• 토큰 비용 높음

팀 재구성 패턴: Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장 → 팀 정리 → 새 팀 생성 순서로 진행한다. 이전 팀의 산출물은 _workspace/ 에 보존되므로 새 팀이 Read로 접근 가능하다.

서브 에이전트 (Sub-agents) — 경량 모드

메인 에이전트가 Agent 도구로 서브 에이전트를 생성한다. 서브 에이전트는 작업 결과를 메인에게만 반환하고 서로 통신하지 않는다.

[메인] → [서브A] → 결과 반환
      → [서브B] → 결과 반환
      → [서브C] → 결과 반환

핵심 도구:

• Agent(prompt, subagent_type, run_in_background): 서브 에이전트 생성

특징:

• 가볍고 빠름
• 결과가 메인 컨텍스트로 요약 반환
• 토큰 효율적

제약:

• 서브 에이전트 간 통신 불가
• 메인이 모든 조율 담당
• 실시간 협업/도전 불가

모드 선택 의사결정 트리

에이전트가 2개 이상인가?
├── Yes → 에이전트 간 통신이 필요한가?
│         ├── Yes → 에이전트 팀 (기본값)
│         │         교차 검증·발견 공유·실시간 피드백으로 품질 향상.
│         │
│         └── No → 서브 에이전트도 가능
│                  결과 전달만 필요한 생성-검증, 전문가 풀 등.
│
└── No (1개) → 서브 에이전트
              단일 에이전트는 팀 구성 불필요.

핵심 원칙: 에이전트 팀이 기본이다. 서브 에이전트를 선택할 때는 "팀원 간 통신이 정말 불필요한가?"를 자문한다.

---

에이전트 팀 아키텍처 유형

1. 파이프라인 (Pipeline)

순차적 작업 흐름. 이전 에이전트의 출력이 다음 에이전트의 입력.

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

적합한 경우: 각 단계가 이전 단계의 산출물에 강하게 의존 예시: 소설 집필 — 세계관 → 캐릭터 → 플롯 → 집필 → 편집 주의: 병목이 전체 파이프라인을 지연시킴. 각 단계를 가능한 독립적으로 설계할 것. 팀 모드 적합성: 순차 의존이 강해 팀 모드의 이점이 제한적. 단, 파이프라인 내 병렬 구간이 있으면 팀 모드 유용.

2. 팬아웃/팬인 (Fan-out/Fan-in)

병렬 처리 후 결과 통합. 독립적 작업을 동시 수행.

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

적합한 경우: 동일 입력에 대해 서로 다른 관점/영역의 분석이 필요 예시: 종합 리서치 — 공식/미디어/커뮤니티/배경 동시 조사 → 통합 보고 주의: 통합 단계의 품질이 전체 품질을 결정. 팀 모드 적합성: 에이전트 팀의 가장 자연스러운 패턴. 반드시 에이전트 팀으로 구성해야 한다. 팀원들이 서로 발견을 공유하고 도전하며, 한 에이전트의 발견이 다른 에이전트의 조사 방향을 실시간으로 수정할 수 있어 단독 조사 대비 품질이 크게 향상된다.

3. 전문가 풀 (Expert Pool)

상황에 따라 적절한 전문가를 선택 호출.

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

적합한 경우: 입력 유형에 따라 다른 처리가 필요 예시: 코드 리뷰 — 보안/성능/아키텍처 전문가 중 해당 영역만 호출 주의: 라우터의 분류 정확도가 핵심. 팀 모드 적합성: 서브 에이전트가 더 적합. 필요한 전문가만 호출하므로 상시 팀이 불필요.

4. 생성-검증 (Producer-Reviewer)

생성 에이전트와 검증 에이전트가 쌍으로 동작.

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

적합한 경우: 산출물의 품질 보장이 중요하고 객관적 검증 기준이 존재 예시: 웹툰 — artist 생성 → reviewer 검수 → 문제 패널 재생성 주의: 무한 루프 방지를 위해 최대 재시도 횟수(2~3회) 설정 필수. 팀 모드 적합성: 에이전트 팀이 유용. SendMessage로 생성자↔검증자 간 실시간 피드백 교환.

5. 감독자 (Supervisor)

중앙 에이전트가 작업 상태를 관리하며 하위 에이전트에 동적으로 작업을 분배.

         ┌→ [워커A]
[감독자] ─┼→ [워커B]    ← 감독자가 상태를 보고 동적 분배
         └→ [워커C]

적합한 경우: 작업량이 가변적이거나 런타임에 작업 분배를 결정해야 할 때 예시: 대규모 코드 마이그레이션 — 감독자가 파일 목록을 분석하고 워커들에게 배치 할당 팬아웃과의 차이: 팬아웃은 사전에 작업을 고정 분배, 감독자는 진행 상황을 보며 동적 조정 주의: 감독자가 병목이 되지 않도록 위임 단위를 충분히 크게 설정. 팀 모드 적합성: 에이전트 팀의 공유 작업 목록이 감독자 패턴과 자연스럽게 매칭. TaskCreate로 작업 등록, 팀원들이 자체 요청.

6. 계층적 위임 (Hierarchical Delegation)

상위 에이전트가 하위 에이전트에 재귀적으로 위임. 복잡한 문제를 단계적으로 분해.

[총괄] → [팀장A] → [실무자A1]
                  → [실무자A2]
       → [팀장B] → [실무자B1]

적합한 경우: 문제가 자연스럽게 계층적으로 분해되는 구조 예시: 풀스택 앱 개발 — 총괄 → 프론트엔드팀장 → (UI/로직/테스트) + 백엔드팀장 → (API/DB/테스트) 주의: 깊이 3단계 이상은 지연과 컨텍스트 손실이 커짐. 2단계 이내 권장. 팀 모드 적합성: 에이전트 팀은 중첩 불가 (팀원이 팀 생성 불가). 1단계는 팀, 2단계는 서브 에이전트로 구현하거나, 평탄화하여 단일 팀으로 구성.

복합 패턴

실전에서는 단일 패턴보다 복합 패턴이 흔하다:

복합 패턴에서의 실행 모드

기본적으로 모든 복합 패턴에 에이전트 팀을 사용한다. 팀원 간 활발한 커뮤니케이션이 결과 품질의 핵심 동력이다.

서브 에이전트로의 혼합은 단일 에이전트가 완전히 격리된 단발성 작업을 수행할 때만 고려한다.

에이전트 타입 선택

에이전트를 호출할 때 Agent 도구의 subagent_type 파라미터로 타입을 지정한다. 에이전트 팀의 팀원도 커스텀 에이전트 정의를 사용할 수 있다.

빌트인 타입

커스텀 타입

.claude/agents/{name}.md에 에이전트를 정의하면 subagent_type: "{name}"으로 호출할 수 있다. 커스텀 에이전트는 전체 도구에 접근 가능.

선택 기준

원칙: 모든 에이전트는 반드시 .claude/agents/{name}.md 파일로 정의한다. 빌트인 타입이라도 에이전트 정의 파일을 생성하여 역할·원칙·프로토콜을 명시한다. 파일로 존재해야 다음 세션에서 재사용 가능하고, 팀 통신 프로토콜이 명시되어야 협업 품질이 보장된다.

모델: 모든 에이전트는 model: "opus"를 사용한다. Agent 도구 호출 시 반드시 model: "opus" 파라미터를 명시한다.

에이전트 정의 구조

---
name: agent-name
description: "1-2문장 역할 설명. 트리거 키워드 나열."
---

# Agent Name — 역할 한줄 요약

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

## 핵심 역할
1. 역할1
2. 역할2

## 작업 원칙
- 원칙1
- 원칙2

## 입력/출력 프로토콜
- 입력: [어디서 무엇을 받는지]
- 출력: [어디에 무엇을 쓰는지]
- 형식: [파일 포맷, 구조]

## 팀 통신 프로토콜 (에이전트 팀 모드)
- 메시지 수신: [누구로부터 어떤 메시지를 받는지]
- 메시지 발신: [누구에게 어떤 메시지를 보내는지]
- 작업 요청: [공유 작업 목록에서 어떤 유형의 작업을 요청하는지]

## 에러 핸들링
- [실패 시 행동]
- [타임아웃 시 행동]

## 협업
- 다른 에이전트와의 관계

에이전트 분리 기준

스킬 vs 에이전트 구분

스킬은 에이전트가 작업을 수행할 때 참조하는 절차적 가이드. 에이전트는 스킬을 활용하는 전문가 역할 정의.

스킬 ↔ 에이전트 연결 방식

에이전트가 스킬을 활용하는 3가지 방식:

권장: 재사용성이 높으면 Skill 도구, 전용이면 인라인, 대용량이면 레퍼런스 로드.

오케스트레이터 스킬 템플릿

오케스트레이터는 팀 전체를 조율하는 상위 스킬이다. 실행 모드에 따라 두 가지 템플릿을 제공한다.

---

템플릿 A: 에이전트 팀 모드 (기본)

에이전트 팀은 TeamCreate로 팀을 구성하고, 공유 작업 목록과 SendMessage로 조율한다.

---
name: {domain}-orchestrator
description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터. {트리거 키워드}."
---

# {Domain} Orchestrator

{도메인}의 에이전트 팀을 조율하여 {최종 산출물}을 생성하는 통합 스킬.

## 실행 모드: 에이전트 팀

## 에이전트 구성

| 팀원 | 에이전트 타입 | 역할 | 스킬 | 출력 |
|------|-------------|------|------|------|
| {teammate-1} | {커스텀 또는 빌트인} | {역할} | {skill} | {output-file} |
| {teammate-2} | {커스텀 또는 빌트인} | {역할} | {skill} | {output-file} |
| ... | | | | |

## 워크플로우

### Phase 1: 준비
1. 사용자 입력 분석 — {무엇을 파악하는지}
2. 작업 디렉토리에 `_workspace/` 생성
3. 입력 데이터를 `_workspace/00_input/`에 저장

### Phase 2: 팀 구성

1. 팀 생성:

TeamCreate( team_name: "{domain}-team", members: [ { name: "{teammate-1}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, { name: "{teammate-2}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, ... ] )

2. 작업 등록:

TaskCreate(tasks: [ { title: "{작업1}", description: "{상세}", assignee: "{teammate-1}" }, { title: "{작업2}", description: "{상세}", assignee: "{teammate-2}" }, { title: "{작업3}", description: "{상세}", depends_on: ["{작업1}"] }, ... ])

   > 팀원당 5~6개 작업이 적정. 의존성이 있는 작업은 `depends_on`으로 명시.

### Phase 3: {주요 작업 — 예: 조사/생성/분석}

**실행 방식:** 팀원들이 자체 조율

팀원들은 공유 작업 목록에서 작업을 요청(claim)하고 독립적으로 수행한다.
리더는 진행 상황을 모니터링하며 필요 시 개입한다.

**팀원 간 통신 규칙:**
- {teammate-1}은 {teammate-2}에게 {어떤 정보}를 SendMessage로 전달
- {teammate-2}는 작업 완료 시 결과를 파일로 저장하고 리더에게 알림
- 팀원이 다른 팀원의 결과가 필요하면 SendMessage로 요청

**산출물 저장:**

| 팀원 | 출력 경로 |
|------|----------|
| {teammate-1} | `_workspace/{phase}_{teammate-1}_{artifact}.md` |
| {teammate-2} | `_workspace/{phase}_{teammate-2}_{artifact}.md` |

**리더 모니터링:**
- 팀원이 유휴 상태가 되면 자동 알림 수신
- 특정 팀원이 막혔을 때 SendMessage로 지시 또는 작업 재할당
- 전체 진행률은 TaskGet으로 확인

### Phase 4: {후속 작업 — 예: 검증/통합}
1. 모든 팀원의 작업 완료 대기 (TaskGet으로 상태 확인)
2. 각 팀원의 산출물을 Read로 수집
3. {통합/검증 로직}
4. 최종 산출물 생성: `{output-path}/{filename}`

### Phase 5: 정리
1. 팀원들에게 종료 요청 (SendMessage)
2. 팀 정리 (TeamDelete)
3. `_workspace/` 디렉토리 보존 (중간 산출물은 삭제하지 않음 — 사후 검증·감사 추적용)
4. 사용자에게 결과 요약 보고

> **팀 재구성이 필요한 경우:** Phase별로 다른 전문가 조합이 필요하면, 현재 팀을 TeamDelete로 정리한 뒤 새 TeamCreate로 다음 Phase의 팀을 구성한다. 이전 팀의 산출물은 `_workspace/`에 보존되므로 새 팀이 Read로 접근 가능.

## 데이터 흐름

[리더] → TeamCreate → [teammate-1] ←SendMessage→ [teammate-2] │ │ ↓ ↓ artifact-1.md artifact-2.md │ │ └───────── Read ────────────┘ ↓ [리더: 통합] ↓ 최종 산출물

## 에러 핸들링

| 상황 | 전략 |
|------|------|
| 팀원 1명 실패/중지 | 리더가 감지 → SendMessage로 상태 확인 → 재시작 또는 대체 팀원 생성 |
| 팀원 과반 실패 | 사용자에게 알리고 진행 여부 확인 |
| 타임아웃 | 현재까지 수집된 부분 결과 사용, 미완료 팀원 종료 |
| 팀원 간 데이터 충돌 | 출처 명시 후 병기, 삭제하지 않음 |
| 작업 상태 지연 | 리더가 TaskGet으로 확인 후 수동으로 TaskUpdate |

## 테스트 시나리오

### 정상 흐름
1. 사용자가 {입력}을 제공
2. Phase 1에서 {분석 결과} 도출
3. Phase 2에서 팀 구성 ({N}명 팀원 + {M}개 작업)
4. Phase 3에서 팀원들이 자체 조율하며 작업 수행
5. Phase 4에서 산출물 통합하여 최종 결과 생성
6. Phase 5에서 팀 정리
7. 예상 결과: `{output-path}/{filename}` 생성

### 에러 흐름
1. Phase 3에서 {teammate-2}가 에러로 중지
2. 리더가 유휴 알림 수신
3. SendMessage로 상태 확인 → 재시작 시도
4. 재시작 실패 시 {teammate-2} 작업을 {teammate-1}에게 재할당
5. 나머지 결과로 Phase 4 진행
6. 최종 보고서에 "{teammate-2} 영역 일부 미수집" 명시

---

템플릿 B: 서브 에이전트 모드 (경량)

서브 에이전트는 Agent 도구로 직접 호출하고, 결과를 메인에게만 반환한다.

---
name: {domain}-orchestrator
description: "{도메인} 에이전트를 조율하는 오케스트레이터. {트리거 키워드}."
---

# {Domain} Orchestrator

{도메인}의 에이전트를 조율하여 {최종 산출물}을 생성하는 통합 스킬.

## 실행 모드: 서브 에이전트

## 에이전트 구성

| 에이전트 | subagent_type | 역할 | 스킬 | 출력 |
|---------|--------------|------|------|------|
| {agent-1} | {커스텀 또는 빌트인 타입} | {역할} | {skill} | {output-file} |
| {agent-2} | {커스텀 또는 빌트인 타입} | {역할} | {skill} | {output-file} |
| ... | | | | |

## 워크플로우

### Phase 1: 준비
1. 사용자 입력 분석 — {무엇을 파악하는지}
2. 작업 디렉토리에 `_workspace/` 생성
3. 입력 데이터를 `_workspace/00_input/`에 저장

### Phase 2: {주요 작업 — 예: 조사/생성/분석}

**실행 방식:** {병렬 | 순차 | 조건부}

{병렬인 경우}
단일 메시지에서 N개 Agent 도구를 동시 호출:

| 에이전트 | 입력 | 출력 | model | run_in_background |
|---------|------|------|-------|-------------------|
| {agent-1} | {입력 소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus | true |
| {agent-2} | {입력 소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus | true |

{순차인 경우}
이전 에이전트의 출력을 다음 에이전트의 입력으로 전달:

1. {agent-1} 실행 → `_workspace/01_{artifact}.md` 생성
2. {agent-2} 실행 (입력: 01의 출력) → `_workspace/02_{artifact}.md` 생성

### Phase 3: {후속 작업 — 예: 검증/통합}
1. Phase 2의 산출물을 Read로 수집
2. {통합/검증 로직}
3. 최종 산출물 생성: `{output-path}/{filename}`

### Phase 4: 정리
1. `_workspace/` 디렉토리 보존 (중간 산출물은 삭제하지 않음 — 사후 검증·감사 추적용)
2. 사용자에게 결과 요약 보고

## 데이터 흐름

입력 → [agent-1] → artifact-1 ─┐ ├→ [통합] → 최종 산출물 입력 → [agent-2] → artifact-2 ─┘

## 에러 핸들링

| 상황 | 전략 |
|------|------|
| 에이전트 1개 실패 | 1회 재시도. 재실패 시 해당 결과 없이 진행, 보고서에 누락 명시 |
| 에이전트 과반 실패 | 사용자에게 알리고 진행 여부 확인 |
| 타임아웃 | 현재까지 수집된 부분 결과 사용 |
| 에이전트 간 데이터 충돌 | 출처 명시 후 병기, 삭제하지 않음 |

## 테스트 시나리오

### 정상 흐름
1. 사용자가 {입력}을 제공
2. Phase 1에서 {분석 결과} 도출
3. Phase 2에서 {N}개 에이전트가 병렬 실행, 각각 산출물 생성
4. Phase 3에서 산출물 통합하여 최종 보고서 생성
5. 예상 결과: `{output-path}/{filename}` 생성

### 에러 흐름
1. Phase 2에서 {agent-2}가 실패
2. 1회 재시도 후에도 실패
3. {agent-2} 결과 없이 나머지 결과로 Phase 3 진행
4. 최종 보고서에 "{agent-2} 영역 데이터 미수집" 명시
5. 사용자에게 부분 완료 알림

---

작성 원칙

1. 실행 모드를 먼저 명시 — 오케스트레이터 상단에 "에이전트 팀" 또는 "서브 에이전트" 명시 2. 에이전트 팀 모드에서는 TeamCreate/SendMessage/TaskCreate 사용법을 구체적으로 — 팀 구성, 작업 등록, 통신 규칙 3. 서브 에이전트 모드에서는 Agent 도구의 모든 파라미터 명시 — name, subagent_type, prompt, run_in_background 4. 파일 경로는 절대적으로 — 상대 경로 금지, _workspace/ 기준 명확한 경로 5. Phase 간 의존성 명시 — 어떤 Phase가 어떤 Phase의 결과에 의존하는지 6. 에러 핸들링은 현실적으로 — "모든 것이 성공한다"고 가정하지 않음 7. 테스트 시나리오 필수 — 정상 1 + 에러 1 이상

실제 오케스트레이터 참고

팬아웃/팬인 패턴의 오케스트레이터 기본 구조: 준비 → TeamCreate + TaskCreate → N개 팀원 병렬 실행 → Read + 통합 → 정리. references/team-examples.md의 리서치 팀 예시를 참조.

QA 에이전트 설계 가이드

빌드 하네스에 QA 에이전트를 포함할 때 참고하는 가이드. 실제 프로젝트(SatangSlide)에서 발견된 버그 패턴과 그 근본 원인 분석을 바탕으로, QA가 놓치기 쉬운 결함을 체계적으로 잡는 검증 방법론을 제공한다.

---

목차

1. QA 에이전트가 놓치는 결함의 패턴 2. 통합 정합성 검증 (Integration Coherence Verification) 3. QA 에이전트 설계 원칙 4. 검증 체크리스트 템플릿 5. QA 에이전트 정의 템플릿

---

1. QA 에이전트가 놓치는 결함의 패턴

1-1. 경계면 불일치 (Boundary Mismatch)

가장 빈번한 결함. 두 컴포넌트가 각각 "올바르게" 구현되어 있지만, 연결 지점에서 계약이 어긋남.

1-2. 왜 정적 코드 리뷰로 못 잡나

• TypeScript 제네릭의 한계: fetchJson<SlideProject[]>() — 런타임 응답이 { projects: [...] }여도 컴파일 통과
• `npm run build` 통과 ≠ 정상 동작: 타입 캐스팅, any, 제네릭이 사용되면 빌드는 성공하지만 런타임에 실패
• 존재 검증 vs 연결 검증의 차이: "API가 있는가?"와 "API의 응답이 호출측의 기대와 일치하는가?"는 전혀 다른 검증

---

2. 통합 정합성 검증 (Integration Coherence Verification)

QA 에이전트에 반드시 포함해야 하는 교차 비교 검증 영역.

2-1. API 응답 ↔ 프론트 훅 타입 교차 검증

방법: 각 API route의 NextResponse.json() 호출부와 대응 훅의 fetchJson<T> 타입 파라미터를 비교.

검증 단계:
1. API route에서 NextResponse.json()에 전달하는 객체의 shape 추출
2. 대응 훅에서 fetchJson<T>의 T 타입 확인
3. shape과 T가 일치하는지 비교
4. 래핑 여부 확인 (API가 { data: [...] }를 반환하면 훅이 .data를 꺼내는지)

특히 주의할 패턴:

• 페이지네이션 API: { items: [], total, page } vs 프론트가 배열 기대
• snake_case DB 필드 → camelCase API 응답 → 프론트 타입 정의 간 불일치
• 즉시 응답 (202 Accepted) vs 최종 결과의 shape 차이

2-2. 파일 경로 ↔ 링크/라우터 경로 매핑

방법: src/app/ 하위 page 파일의 URL 경로를 추출하고, 코드 내 모든 href, router.push(), redirect() 값과 대조.

검증 단계:
1. src/app/ 하위 page.tsx 파일 경로에서 URL 패턴 추출
   - (group) → URL에서 제거
   - [param] → 동적 세그먼트
2. 코드 내 모든 href=, router.push(, redirect( 값 수집
3. 각 링크가 실제 존재하는 page 경로와 매칭되는지 확인
4. route group 내부 페이지의 URL 접두사 주의 (예: dashboard/ 하위)

2-3. 상태 전이 완전성 추적

방법: 코드에서 모든 status: 업데이트를 추출하여 상태 전이 맵과 대조.

검증 단계:
1. 상태 전이 맵(STATE_TRANSITIONS)에서 허용된 전이 목록 추출
2. 모든 API route에서 .update({ status: "..." }) 패턴 검색
3. 각 전이가 맵에 정의되어 있는지 확인
4. 맵에 정의된 전이 중 코드에서 실행되지 않는 것 식별 (죽은 전이)
5. 특히: 중간 상태(예: generating_template)에서 최종 상태(template_approved)로의 전환이 누락되지 않았는지

2-4. API 엔드포인트 ↔ 프론트 훅 1:1 매핑

방법: 모든 API route와 프론트 훅을 나열하여 짝이 맞는지 확인.

검증 단계:
1. src/app/api/ 하위 route.ts에서 HTTP 메서드별 엔드포인트 목록 추출
2. src/hooks/ 하위 use*.ts에서 fetch 호출 URL 목록 추출
3. API 엔드포인트 중 훅에서 호출하지 않는 것 식별 → "사용 안 됨" 플래그
4. "사용 안 됨"이 의도적인지 (관리 API 등) 아닌지 (호출 누락) 판단

---

3. QA 에이전트 설계 원칙

3-1. Explore 타입이 아닌 general-purpose 타입을 사용하라

QA 에이전트가 Explore 타입이면 읽기만 가능하다. 하지만 효과적인 QA는:

• Grep으로 패턴 검색 (모든 NextResponse.json() 추출)
• 스크립트 실행으로 자동 대조 (API shape vs 훅 타입)
• 필요 시 수정까지 가능

권장: general-purpose 타입으로 설정하되, 에이전트 정의에서 "검증 → 리포트 → 수정 요청" 프로토콜을 명시.

3-2. 체크리스트는 "존재 확인"보다 "교차 비교"를 우선하라

3-3. "양쪽을 동시에 읽어라" 원칙

QA가 경계면 버그를 잡으려면, 한쪽만 읽어선 안 된다. 반드시:

• API route 와 대응 훅을 같이 읽고
• 상태 전이 맵 와 실제 업데이트 코드를 같이 읽고
• 파일 구조 와 링크 경로를 같이 읽어야 한다

에이전트 정의에 이 원칙을 명시적으로 기재하라.

3-4. QA는 빌드 후가 아니라, 각 모듈 완성 직후에 실행하라

오케스트레이터에서 QA를 "Phase 4: 전체 완성 후"에만 배치하면:

• 버그가 누적되어 수정 비용이 높아짐
• 초기 경계면 불일치가 후속 모듈에 전파됨

권장 패턴: 각 백엔드 API 완성 시 즉시 해당 API + 대응 훅의 교차 검증 수행 (incremental QA).

---

4. 검증 체크리스트 템플릿

QA 에이전트 정의에 포함할 웹 애플리케이션용 통합 정합성 체크리스트.

### 통합 정합성 검증 (웹 앱)

#### API ↔ 프론트엔드 연결
- [ ] 모든 API route의 응답 shape과 대응 훅의 제네릭 타입이 일치
- [ ] 래핑된 응답({ items: [...] })은 훅에서 unwrap하는지 확인
- [ ] snake_case ↔ camelCase 변환이 일관되게 적용
- [ ] 즉시 응답(202)과 최종 결과의 shape이 프론트에서 구분되는지 확인
- [ ] 모든 API 엔드포인트에 대응하는 프론트 훅이 존재하고 실제로 호출됨

#### 라우팅 정합성
- [ ] 코드 내 모든 href/router.push 값이 실제 page 파일 경로와 매칭
- [ ] route group ((group))이 URL에서 제거되는 것을 고려한 경로 검증
- [ ] 동적 세그먼트([id])가 올바른 파라미터로 채워지는지 확인

#### 상태 머신 정합성
- [ ] 정의된 모든 상태 전이가 코드에서 실행됨 (죽은 전이 없음)
- [ ] 코드의 모든 status 업데이트가 전이 맵에 정의됨 (무단 전이 없음)
- [ ] 중간 상태에서 최종 상태로의 전환이 누락되지 않음
- [ ] 프론트에서 상태 기반 분기(if status === "X")의 X가 실제 도달 가능

#### 데이터 흐름 정합성
- [ ] DB 스키마 필드명과 API 응답 필드명의 매핑이 일관됨
- [ ] 프론트 타입 정의와 API 응답의 필드명이 일치
- [ ] 옵셔널 필드에 대한 null/undefined 처리가 양쪽에서 일관됨

---

5. QA 에이전트 정의 템플릿

빌드 하네스의 QA 에이전트에 포함할 핵심 섹션.

---
name: qa-inspector
description: "QA 검증 전문가. 스펙 준수, 통합 정합성, 디자인 품질을 검증."
---

# QA Inspector

## 핵심 역할
스펙 대비 구현 품질과 **모듈 간 통합 정합성**을 검증한다.

## 검증 우선순위

1. **통합 정합성** (가장 높음) — 경계면 불일치가 런타임 에러의 주요 원인
2. **기능 스펙 준수** — API/상태머신/데이터모델
3. **디자인 품질** — 색상/타이포/반응형
4. **코드 품질** — 미사용 코드, 명명 규칙

## 검증 방법: "양쪽 동시 읽기"

경계면 검증은 반드시 **양쪽 코드를 동시에 열어** 비교한다:

| 검증 대상 | 왼쪽 (생산자) | 오른쪽 (소비자) |
|----------|-------------|---------------|
| API 응답 shape | route.ts의 NextResponse.json() | hooks/의 fetchJson<T> |
| 라우팅 | src/app/ page 파일 경로 | href, router.push 값 |
| 상태 전이 | STATE_TRANSITIONS 맵 | .update({ status }) 코드 |
| DB → API → UI | 테이블 컬럼명 | API 응답 필드 → 타입 정의 |

## 팀 통신 프로토콜

- 발견 즉시 해당 에이전트에게 구체적 수정 요청 (파일:라인 + 수정 방법)
- 경계면 이슈는 양쪽 에이전트 **모두**에게 알림
- 리더에게: 검증 리포트 (통과/실패/미검증 항목 구분)

---

실제 사례: SatangSlide에서 발견된 버그

이 가이드의 모든 내용은 아래 실제 버그에서 추출한 교훈이다:

<p align="center"> <img src="harness_banner.png" alt="Harness Banner" width="600"> </p>

<p align="center"> <img src="https://img.shields.io/badge/Version-1.0.1-brightgreen.svg" alt="Version"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a> <img src="https://img.shields.io/badge/Claude_Code-Plugin-purple.svg" alt="Claude Code Plugin"> <img src="https://img.shields.io/badge/Patterns-6_Architectures-orange.svg" alt="6 Architecture Patterns"> <img src="https://img.shields.io/badge/Mode-Agent_Teams-green.svg" alt="Agent Teams"> <a href="https://github.com/revfactory/harness/stargazers"><img src="https://img.shields.io/github/stars/revfactory/harness?style=social" alt="GitHub Stars"></a> </p>

Harness

Agent Team & Skill Architect — A Claude Code Plugin

English | 한국어 | 日本語

A meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.

Overview

Harness leverages Claude Code's agent team system to decompose complex tasks into coordinated teams of specialized agents. Say "build a harness for this project" and it automatically generates agent definitions (.claude/agents/) and skills (.claude/skills/) tailored to your domain.

Key Features

• Agent Team Design — 6 architectural patterns: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, and Hierarchical Delegation
• Skill Generation — Auto-generates skills with Progressive Disclosure for efficient context management
• Orchestration — Inter-agent data passing, error handling, and team coordination protocols
• Validation — Trigger verification, dry-run testing, and with-skill vs without-skill comparison tests

Workflow

Phase 1: Domain Analysis
    ↓
Phase 2: Team Architecture Design (Agent Teams vs Subagents)
    ↓
Phase 3: Agent Definition Generation (.claude/agents/)
    ↓
Phase 4: Skill Generation (.claude/skills/)
    ↓
Phase 5: Integration & Orchestration
    ↓
Phase 6: Validation & Testing

Installation

Via Marketplace

Add the marketplace

/plugin marketplace add revfactory/harness

Install the plugin

/plugin install harness@harness

Direct Installation as Global Skill

# Copy the skills directory to ~/.claude/skills/harness/
cp -r skills/harness ~/.claude/skills/harness

Plugin Structure

harness/
├── .claude-plugin/
│   └── plugin.json                 # Plugin manifest
├── skills/
│   └── harness/
│       ├── SKILL.md                # Main skill definition (6-Phase workflow)
│       └── references/
│           ├── agent-design-patterns.md   # 6 architectural patterns
│           ├── orchestrator-template.md   # Team/subagent orchestrator templates
│           ├── team-examples.md           # 5 real-world team configurations
│           ├── skill-writing-guide.md     # Skill authoring guide
│           ├── skill-testing-guide.md     # Testing & evaluation methodology
│           └── qa-agent-guide.md          # QA agent integration guide
└── README.md

Usage

Trigger in Claude Code with prompts like:

Build a harness for this project
Design an agent team for this domain
Set up a harness

Execution Modes

<p align="center"> <img src="harness_team.png" alt="Harness Agent Team" width="500"> </p>

Architecture Patterns

Output

Files generated by Harness:

your-project/
├── .claude/
│   ├── agents/          # Agent definition files
│   │   ├── analyst.md
│   │   ├── builder.md
│   │   └── qa.md
│   └── skills/          # Skill files
│       ├── analyze/
│       │   └── skill.md
│       └── build/
│           ├── skill.md
│           └── references/

Use Cases — Try These Prompts

Copy any prompt below into Claude Code after installing Harness:

Deep Research

Build a harness for deep research. I need an agent team that can investigate
any topic from multiple angles — web search, academic sources, community
sentiment — then cross-validate findings and produce a comprehensive report.

Website Development

Build a harness for full-stack website development. The team should handle
design, frontend (React/Next.js), backend (API), and QA testing in a
coordinated pipeline from wireframe to deployment.

Webtoon / Comic Production

Build a harness for webtoon episode production. I need agents for story
writing, character design prompts, panel layout planning, and dialogue
editing. They should review each other's work for style consistency.

YouTube Content Planning

Build a harness for YouTube content creation. The team should research
trending topics, write scripts, optimize titles/tags for SEO, and plan
thumbnail concepts — all coordinated by a supervisor agent.

Code Review & Refactoring

Build a harness for comprehensive code review. I want parallel agents
checking architecture, security vulnerabilities, performance bottlenecks,
and code style — then merging all findings into a single report.

Technical Documentation

Build a harness that generates API documentation from this codebase.
Agents should analyze endpoints, write descriptions, generate usage
examples, and review for completeness.

Data Pipeline Design

Build a harness for designing data pipelines. I need agents for schema
design, ETL logic, data validation rules, and monitoring setup that
delegate sub-tasks hierarchically.

Marketing Campaign

Build a harness for marketing campaign creation. The team should research
the target market, write ad copy, design visual concepts, and set up
A/B test plans with iterative quality review.

Built with Harness

Harness 100

[revfactory/harness-100](https://github.com/revfactory/harness-100) — 100 production-ready agent team harnesses across 10 domains, available in both English and Korean (200 packages total). Each harness ships with 4-5 specialist agents, an orchestrator skill, and domain-specific skills — all generated by this plugin. 1,808 markdown files covering content creation, software development, data/AI, business strategy, education, legal, health, and more.

Research: A/B Testing Harness Effectiveness

[revfactory/claude-code-harness](https://github.com/revfactory/claude-code-harness) — A controlled experiment across 15 software engineering tasks measuring the impact of structured pre-configuration on LLM code agent output quality.

Key finding: effectiveness scales with task complexity — the harder the task, the greater the improvement (+23.8 Basic, +29.6 Advanced, +36.2 Expert).

Full paper: Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality.

Requirements

• Agent Teams enabled: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

License

Apache 2.0

스킬 테스트 & 반복 개선 가이드

하네스에서 생성한 스킬의 품질을 검증하고 반복적으로 개선하는 방법론. SKILL.md Phase 6의 보충 레퍼런스.

---

목차

1. 테스트 프레임워크 개요 2. 테스트 프롬프트 작성법 3. 실행 테스트: With-skill vs Baseline 4. 정량적 평가: Assertion 기반 채점 5. 전문 에이전트 활용 6. 반복 개선 루프 7. Description 트리거 검증 8. 워크스페이스 구조

---

1. 테스트 프레임워크 개요

스킬 품질 검증은 정성적 평가와 정량적 평가의 조합이다.

핵심 루프: 작성 → 테스트 실행 → 평가 → 개선 → 재테스트

---

2. 테스트 프롬프트 작성법

원칙

테스트 프롬프트는 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장이어야 한다. 추상적이거나 인공적인 프롬프트는 테스트 가치가 낮다.

나쁜 예

"PDF를 처리하라"
"데이터를 추출하라"
"차트를 생성하라"

좋은 예

"다운로드 폴더에 있는 'Q4_매출_최종_v2.xlsx'에서 C열(매출)과 D열(비용)을
사용해서 이익률(%) 열을 추가해줘. 그리고 이익률 기준으로 내림차순 정렬."

"이 PDF에서 3페이지 표를 추출해서 CSV로 변환해줘. 표 헤더가 2줄로
되어 있어서 첫 번째 줄은 카테고리, 두 번째 줄이 실제 열 이름이야."

프롬프트 다양성

• 공식적 / 캐주얼 톤 혼합
• 명시적 / 암시적 의도 혼합 (파일 형식을 직접 말하는 경우 vs 맥락으로 추론해야 하는 경우)
• 단순 / 복잡 작업 혼합
• 일부는 약어, 오타, 캐주얼한 표현 포함

커버리지

2~3개 프롬프트로 시작하되, 다음을 커버하도록 설계:

• 핵심 사용 사례 1개
• 엣지 케이스 1개
• (선택) 복합 작업 1개

---

3. 실행 테스트: With-skill vs Baseline

3-1. 비교 실행 구조

각 테스트 프롬프트에 대해 두 개의 서브에이전트를 동시에 스폰한다:

With-skill 실행:

프롬프트: "{테스트 프롬프트}"
스킬 경로: {스킬 경로}
출력 경로: _workspace/iteration-N/eval-{id}/with_skill/outputs/

Baseline 실행:

프롬프트: "{테스트 프롬프트}"  (동일)
스킬: 없음
출력 경로: _workspace/iteration-N/eval-{id}/without_skill/outputs/

3-2. Baseline 선택

3-3. 타이밍 데이터 캡처

서브에이전트 완료 알림에서 total_tokens와 duration_ms를 즉시 저장한다. 이 데이터는 알림 시점에만 접근 가능하고 이후 복구할 수 없다.

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

---

4. 정량적 평가: Assertion 기반 채점

4-1. Assertion 작성

산출물이 객관적으로 검증 가능한 경우, 자동 채점을 위한 assertion을 정의한다.

좋은 assertion:

• 객관적으로 참/거짓 판별 가능
• 서술적인 이름으로 결과만 봐도 무엇을 검사하는지 명확
• 스킬의 핵심 가치를 검증

나쁜 assertion:

• 스킬 유무와 무관하게 항상 통과하는 것 (예: "출력이 존재한다")
• 주관적 판단이 필요한 것 (예: "잘 작성되었다")

4-2. 프로그래밍 가능한 검증

assertion이 코드로 검증 가능하면 스크립트로 작성한다. 눈으로 확인하는 것보다 빠르고 신뢰성 있으며, iteration마다 재사용 가능.

4-3. Non-discriminating assertion 주의

"두 구성 모두에서 100% 통과"하는 assertion은 스킬의 차별적 가치를 측정하지 못한다. 이런 assertion을 발견하면 제거하거나, 더 도전적인 assertion으로 교체한다.

4-4. 채점 결과 스키마

{
  "expectations": [
    {
      "text": "이익률 열이 추가됨",
      "passed": true,
      "evidence": "E열에 'profit_margin_pct' 열 확인"
    },
    {
      "text": "이익률 기준 내림차순 정렬",
      "passed": false,
      "evidence": "정렬 없이 원본 순서 유지됨"
    }
  ],
  "summary": {
    "passed": 1,
    "failed": 1,
    "total": 2,
    "pass_rate": 0.50
  }
}

---

5. 전문 에이전트 활용

테스트/평가 과정에서 전문 역할의 에이전트를 활용하면 품질이 향상된다.

5-1. Grader (채점자)

assertion 기반 채점을 수행하고, 산출물에서 검증 가능한 주장(claim)을 추출하여 교차 검증한다.

역할:

• assertion별 통과/실패 판정 + 근거 제시
• 산출물에서 사실적 주장을 추출하고 검증
• eval 자체의 품질에 대한 피드백 (assertion이 너무 쉽거나 모호한 경우 제안)

5-2. Comparator (블라인드 비교자)

두 산출물을 A/B로 익명화하여, 어떤 것이 스킬을 사용한 결과인지 모르는 상태에서 품질을 판정한다.

활용 시점: "새 버전이 정말 더 나은가?"를 엄밀하게 확인하고 싶을 때. 일반적인 반복 개선에서는 생략 가능.

판정 기준:

• 내용: 정확성, 완성도
• 구조: 조직화, 포맷팅, 사용성
• 종합 점수

5-3. Analyzer (분석자)

벤치마크 데이터에서 통계적 패턴을 분석한다:

• Non-discriminating assertion (두 구성 모두 통과 → 차별력 없음)
• 고분산 eval (결과가 실행마다 크게 달라짐 → 불안정)
• 시간/토큰 트레이드오프 (스킬이 품질은 높이지만 비용도 높이는 경우)

---

6. 반복 개선 루프

6-1. 피드백 수집

사용자에게 산출물을 보여주고 피드백을 받는다. 빈 피드백은 "이상 없음"으로 해석한다.

6-2. 개선 원칙

1. 피드백을 일반화하라 — 테스트 예시에만 맞는 좁은 수정은 오버피팅이다. 원리 수준에서 수정한다. 2. 무게를 벌지 않는 것은 제거하라 — 트랜스크립트를 읽고, 스킬이 에이전트에게 비생산적인 작업을 시키고 있다면 해당 부분을 삭제한다. 3. Why를 설명하라 — 사용자의 피드백이 간결하더라도, 왜 그것이 중요한지 이해하고 그 이해를 스킬에 반영한다. 4. 반복 작업은 번들링하라 — 모든 테스트 실행에서 동일한 헬퍼 스크립트가 생성되면, scripts/에 미리 포함한다.

6-3. 반복 절차

1. 스킬 수정
2. 새 iteration-N+1/ 디렉토리에 모든 테스트 케이스 재실행
3. 사용자에게 결과 제시 (이전 iteration과 비교)
4. 피드백 수집
5. 다시 수정 → 반복

종료 조건:

• 사용자가 만족
• 피드백이 모두 비어 있음 (모든 산출물 이상 없음)
• 의미 있는 개선이 더 이상 없음

6-4. 초안 → 재검토 패턴

스킬 수정 시, 초안을 작성한 후 새로운 시각으로 다시 읽고 개선한다. 한 번에 완벽하게 쓰려 하지 말고, 초안-검토 사이클을 거친다.

---

7. Description 트리거 검증

7-1. 트리거 Eval 쿼리 작성

20개의 eval 쿼리를 작성한다 — should-trigger 10개 + should-NOT-trigger 10개.

쿼리 품질 기준:

• 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장
• 파일 경로, 개인적 맥락, 열 이름, 회사명 등 구체적 디테일 포함
• 길이, 톤, 형식 다양하게 혼합
• 명확한 정답보다 경계 케이스(edge case)에 집중

Should-trigger 쿼리 (8~10개):

• 다양한 표현의 같은 의도 (공식적/캐주얼)
• 스킬/파일 유형을 명시적으로 말하지 않지만 분명히 필요한 경우
• 비주류 사용 사례
• 다른 스킬과 경쟁하지만 이 스킬이 이겨야 하는 경우

Should-NOT-trigger 쿼리 (8~10개):

• Near-miss가 핵심 — 키워드가 유사하지만 다른 도구/스킬이 적합한 쿼리
• 명백히 무관한 쿼리("피보나치 함수 작성")는 테스트 가치 없음
• 인접 도메인, 모호한 표현, 키워드 겹침 but 맥락이 다른 경우

7-2. 기존 스킬 충돌 검증

새 스킬의 description이 기존 스킬의 트리거 영역과 겹치지 않는지 확인한다:

1. 기존 스킬 목록의 description을 수집 2. 새 스킬의 should-trigger 쿼리가 기존 스킬을 잘못 트리거하지 않는지 확인 3. 충돌 발견 시 description의 경계 조건을 더 명확히 기술

7-3. 자동 최적화 (선택적 고급 기능)

description 최적화가 필요한 경우:

1. 20개 eval 쿼리를 Train(60%) / Test(40%) split 2. 현재 description으로 트리거 정확도 측정 3. 실패 케이스를 분석하여 개선된 description 생성 4. Test set 기준으로 best description 선택 (Train set 기준이 아님 — 과적합 방지) 5. 최대 5회 반복

이 과정은 claude -p를 사용하는 자동화 스크립트로 수행한다. 토큰 비용이 높으므로 스킬이 충분히 안정화된 후 최종 단계에서 실행한다.

---

8. 워크스페이스 구조

테스트/평가 결과를 체계적으로 관리하는 디렉토리 구조:

{skill-name}-workspace/
├── iteration-1/
│   ├── eval-descriptive-name-1/
│   │   ├── eval_metadata.json
│   │   ├── with_skill/
│   │   │   ├── outputs/
│   │   │   ├── timing.json
│   │   │   └── grading.json
│   │   └── without_skill/
│   │       ├── outputs/
│   │       ├── timing.json
│   │       └── grading.json
│   ├── eval-descriptive-name-2/
│   │   └── ...
│   └── benchmark.json
├── iteration-2/
│   └── ...
└── evals/
    └── evals.json

규칙:

• eval 디렉토리는 숫자가 아닌 서술적 이름 사용 (예: eval-multi-page-table-extraction)
• 각 iteration은 독립 디렉토리에 보존 (이전 iteration 덮어쓰기 금지)
• _workspace/는 삭제하지 않음 — 사후 검증 및 감사 추적용

스킬 작성 가이드

하네스에서 생성하는 스킬의 품질을 높이기 위한 상세 작성 가이드. SKILL.md Phase 4의 보충 레퍼런스.

---

목차

1. Description 작성 패턴 2. 본문 작성 스타일 3. 출력 형식 정의 패턴 4. 예시 작성 패턴 5. Progressive Disclosure 패턴 6. 스크립트 번들링 판단 기준 7. 데이터 스키마 표준 8. 스킬에 포함하지 않을 것

---

1. Description 작성 패턴

Description은 스킬의 유일한 트리거 메커니즘이다. Claude는 available_skills 목록에서 name + description만 보고 스킬 사용 여부를 결정한다.

트리거 메커니즘 이해

Claude는 자신의 기본 도구로 쉽게 처리할 수 있는 단순 작업에는 스킬을 호출하지 않는 경향이 있다. "이 PDF 읽어줘" 같은 단순 요청은 description이 완벽해도 트리거되지 않을 수 있다. 복잡하고 다단계이며 전문적인 작업일수록 스킬 트리거 확률이 높다.

작성 원칙

1. 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술 2. 유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시 3. 약간 "pushy"하게 — Claude가 트리거를 보수적으로 판단하는 경향을 보상

좋은 예시

description: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크,
  암호화/복호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나
  PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것. 단순히 PDF를
  '읽어달라'는 요청이 아닌 변환/편집/분석이 필요할 때 특히 유용."

description: "엑셀/CSV/TSV 파일의 열 추가, 수식 계산, 서식, 차트,
  데이터 정제를 포함한 모든 스프레드시트 작업. 사용자가 스프레드시트
  파일을 언급하면 — 심지어 캐주얼하게('다운로드 폴더의 xlsx')라고만
  해도 — 이 스킬을 사용할 것."

나쁜 예시

• "데이터를 처리하는 스킬" — 너무 모호, 어떤 파일/작업인지 불분명
• "PDF 관련 작업" — 구체적 동작 나열 없음, 트리거 상황 미기술

---

2. 본문 작성 스타일

Why-First 원칙

LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. 강압적 규칙보다 맥락 전달이 효과적이다.

나쁜 예:

ALWAYS use pdfplumber for table extraction. NEVER use PyPDF2 for tables.

좋은 예:

테이블 추출에는 pdfplumber를 사용한다. PyPDF2는 텍스트 추출에 특화되어
있어 테이블의 행/열 구조를 보존하지 못하기 때문이다. pdfplumber는
셀 경계를 인식하여 구조화된 데이터를 반환한다.

일반화 원칙

피드백이나 테스트 결과에서 문제가 발견되면, 특정 예시에만 맞는 좁은 수정 대신 원리 수준에서 일반화한다.

오버피팅 수정:

"Q4 매출" 열이 있으면 해당 열을 숫자로 변환하라.

일반화된 수정:

열 이름에 "매출", "금액", "수량" 등 수치를 암시하는 키워드가 있으면
해당 열을 숫자 타입으로 변환한다. 변환 실패 시 원본 값을 유지한다.

명령형 어조

"~합니다", "~할 수 있습니다" 대신 "~한다", "~하라" 형태를 사용한다. 스킬은 지시서이다.

컨텍스트 절약

컨텍스트 윈도우는 공공재다. 모든 문장이 토큰 비용을 정당화하는지 자문한다:

• "Claude가 이미 알고 있는 내용인가?" → 삭제
• "이 설명이 없으면 Claude가 실수하는가?" → 유지
• "구체적 예시 하나가 긴 설명보다 효과적인가?" → 예시로 대체

---

3. 출력 형식 정의 패턴

산출물의 형식이 중요한 스킬에서 사용:

## 보고서 구조
다음 템플릿을 정확히 따른다:

# [제목]
## 요약
## 핵심 발견
## 권장 사항

형식 정의는 간결하게, 실제 예시를 포함하면 더 효과적이다.

---

4. 예시 작성 패턴

예시는 긴 설명보다 효과적이다:

## 커밋 메시지 형식

**예시 1:**
입력: JWT 토큰 기반 사용자 인증 추가
출력: feat(auth): JWT 기반 인증 구현

**예시 2:**
입력: 로그인 페이지에서 비밀번호 표시 버튼이 동작하지 않는 버그 수정
출력: fix(login): 비밀번호 표시 토글 버튼 동작 수정

---

5. Progressive Disclosure 패턴

패턴 1: 도메인별 분리

bigquery-skill/
├── skill.md (개요 + 도메인 선택 가이드)
└── references/
    ├── finance.md (매출, 빌링 메트릭)
    ├── sales.md (기회, 파이프라인)
    └── product.md (API 사용량, 기능)

사용자가 매출에 대해 물으면 finance.md만 로드.

패턴 2: 조건부 상세

# DOCX 처리

## 문서 생성
docx-js로 새 문서를 생성한다. → [DOCX-JS.md](references/docx-js.md) 참조.

## 문서 편집
단순 편집은 XML을 직접 수정.
**추적 변경이 필요하면**: [REDLINING.md](references/redlining.md) 참조

패턴 3: 대형 레퍼런스 파일 구조

300줄 이상의 reference 파일은 상단에 목차를 포함한다:

# API 레퍼런스

## 목차
1. [인증](#인증)
2. [엔드포인트 목록](#엔드포인트-목록)
3. [에러 코드](#에러-코드)
4. [레이트 리밋](#레이트-리밋)

---

## 인증
...

---

6. 스크립트 번들링 판단 기준

테스트 실행에서 에이전트들의 트랜스크립트를 관찰한다. 다음 패턴이 보이면 번들링 대상:

번들링된 스크립트는 반드시 실행 테스트를 거친다.

---

7. 데이터 스키마 표준

스킬 간 데이터 교환의 일관성을 위해 표준 스키마를 사용한다. 하네스에서 생성하는 스킬의 테스트/평가에 사용할 수 있다.

eval_metadata.json

각 테스트 케이스의 메타데이터:

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "사용자의 작업 프롬프트",
  "assertions": [
    "산출물에 X가 포함되어 있다",
    "Y 형식으로 파일이 생성되었다"
  ]
}

grading.json

assertion 기반 채점 결과:

{
  "expectations": [
    {
      "text": "산출물에 '서울'이 포함됨",
      "passed": true,
      "evidence": "3번째 단계에서 '서울 지역 데이터 추출' 확인"
    }
  ],
  "summary": {
    "passed": 2,
    "failed": 1,
    "total": 3,
    "pass_rate": 0.67
  }
}

필드명 주의: text, passed, evidence를 정확히 사용한다 (name/met/details 등 변형 금지).

timing.json

실행 시간/토큰 측정:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

서브에이전트 완료 알림에서 total_tokens와 duration_ms를 즉시 저장한다. 이 데이터는 알림 시점에만 접근 가능하고 이후 복구 불가.

---

8. 스킬에 포함하지 않을 것

• README.md, CHANGELOG.md, INSTALLATION_GUIDE.md 등 부가 문서
• 스킬 생성 과정의 메타 정보 (테스트 결과, 반복 이력)
• 사용자 대상 설명서 (스킬은 AI 에이전트를 위한 지시서)
• 이미 Claude가 알고 있는 일반적 지식

Agent Team Examples

---

예시 1: 리서치 팀 (에이전트 팀 모드)

팀 아키텍처: 팬아웃/팬인

실행 모드: 에이전트 팀

[리더/오케스트레이터]
    ├── TeamCreate(research-team)
    ├── TaskCreate(4개 조사 작업)
    ├── 팀원들이 자체 조율 (SendMessage)
    ├── 결과 수집 (Read)
    └── 종합 보고서 생성

에이전트 구성

리서치 에이전트는 general-purpose 빌트인 타입을 사용하되, 반드시 .claude/agents/{name}.md 파일로 정의한다. 파일에는 역할·조사 범위·팀 통신 프로토콜을 명시하여 재사용성과 협업 품질을 보장한다.

오케스트레이터 워크플로우 (에이전트 팀)

Phase 1: 준비
  - 사용자 입력 분석 (주제, 조사 모드 파악)
  - _workspace/ 생성

Phase 2: 팀 구성
  - TeamCreate(team_name: "research-team", members: [
      { name: "official", prompt: "공식 채널 조사..." },
      { name: "media", prompt: "미디어/투자 동향 조사..." },
      { name: "community", prompt: "커뮤니티 반응 조사..." },
      { name: "background", prompt: "배경/경쟁 환경 조사..." }
    ])
  - TaskCreate(tasks: [
      { title: "공식 채널 조사", assignee: "official" },
      { title: "미디어 동향 조사", assignee: "media" },
      { title: "커뮤니티 반응 조사", assignee: "community" },
      { title: "배경 환경 조사", assignee: "background" }
    ])

Phase 3: 조사 수행
  - 4명의 팀원이 독립적으로 조사
  - 흥미로운 발견이 있으면 팀원 간 SendMessage로 공유
    (예: media가 발견한 투자 뉴스를 background에게 전달)
  - 상충 정보 발견 시 팀원 간 직접 토론
  - 각 팀원은 완료 시 파일 저장 + 리더에게 알림

Phase 4: 통합
  - 리더가 4개 산출물 Read
  - 종합 보고서 생성
  - 상충 정보는 출처 병기

Phase 5: 정리
  - 팀원들 종료 요청
  - 팀 정리
  - _workspace/ 보존 (사후 검증·감사 추적용)

팀 통신 패턴

official ──SendMessage──→ background  (관련 공식 발표 공유)
media ────SendMessage──→ background  (투자/인수 정보 공유)
community ─SendMessage──→ media      (커뮤니티 반응 중 미디어 관련 정보)
모든 팀원 ──TaskUpdate──→ 공유 작업 목록  (진행률 업데이트)
리더 ←───── 유휴 알림 ──── 완료된 팀원   (자동)

---

예시 2: SF 소설 집필 팀 (에이전트 팀 모드)

팀 아키텍처: 파이프라인 + 팬아웃

실행 모드: 에이전트 팀

Phase 1 (병렬 — 에이전트 팀): worldbuilder + character-designer + plot-architect
  → 서로 SendMessage로 일관성 조율
Phase 2 (순차): prose-stylist (집필)
Phase 3 (병렬 — 에이전트 팀): science-consultant + continuity-manager (리뷰)
  → 서로 SendMessage로 발견 공유
Phase 4 (순차): prose-stylist (리뷰 반영 수정)

에이전트 구성

에이전트 파일 전문 예시: worldbuilder.md

---
name: worldbuilder
description: "SF 소설의 세계관을 구축하는 전문가. 물리 법칙, 사회 구조, 기술 수준, 역사를 설계한다."
---

# Worldbuilder — SF 세계관 설계 전문가

당신은 SF 소설의 세계관 설계 전문가입니다. 과학적 사실에 기반하되 상상력을 확장하여, 이야기가 펼쳐질 세계의 물리적·사회적·기술적 토대를 구축합니다.

## 핵심 역할
1. 세계의 물리 법칙과 기술 수준 정의
2. 사회 구조, 정치 체계, 경제 시스템 설계
3. 역사적 맥락과 현재 갈등 구조 수립
4. 장소별 환경과 분위기 묘사

## 작업 원칙
- 내적 일관성 최우선 — 설정 간 모순이 없어야 한다
- "만약 이 기술이 있다면?" 연쇄 질문으로 세계의 파급 효과를 추론
- 이야기에 봉사하는 세계관 — 플롯을 방해하는 과도한 설정은 지양

## 입력/출력 프로토콜
- 입력: 사용자의 세계관 컨셉, 장르 요구사항
- 출력: `_workspace/01_worldbuilder_setting.md`
- 형식: 마크다운. 섹션별 (물리/사회/기술/역사/장소)

## 팀 통신 프로토콜
- character-designer에게: 사회 구조, 계급 시스템, 직업군 정보 SendMessage
- plot-architect에게: 세계의 주요 갈등 구조, 위기 요소 SendMessage
- science-consultant로부터: 과학적 오류 피드백 수신 → 설정 수정
- 세계관 변경 시 관련 팀원 전체에 브로드캐스트

## 에러 핸들링
- 컨셉이 모호하면 3가지 방향을 제안하고 선택 요청
- 과학적 오류 발견 시 대안을 함께 제시

## 협업
- character-designer에게 사회 구조 정보 제공
- plot-architect에게 갈등 구조 정보 제공
- science-consultant의 피드백을 반영하여 설정 수정

팀 워크플로우 상세

Phase 1: TeamCreate(team_name: "novel-team", members: [worldbuilder, character-designer, plot-architect])
         TaskCreate([세계관 구축, 캐릭터 설계, 플롯 구조])
         → 팀원들이 자체 조율하며 병렬 작업
         → worldbuilder가 사회 구조 완성 시 character-designer에게 SendMessage
         → character-designer가 주인공 설정 시 plot-architect에게 SendMessage

Phase 2: Phase 1 팀 정리 → prose-stylist를 서브 에이전트로 호출 (단독 집필이므로 팀 불필요)
         prose-stylist가 _workspace/의 3개 산출물을 Read하여 집필
         → 결과를 _workspace/02_prose_draft.md에 저장

Phase 3: 새 팀 생성 — TeamCreate(team_name: "review-team", members: [science-consultant, continuity-manager])
         (세션당 한 팀만 활성이지만, Phase 1 팀을 정리했으므로 새 팀 생성 가능)
         → 두 리뷰어가 draft를 검토, 서로 발견을 공유
         → science-consultant가 물리 오류 발견 시 continuity-manager에게도 알림
         → 리뷰 완료 후 팀 정리

Phase 4: prose-stylist를 서브 에이전트로 호출, 리뷰 결과 반영하여 최종 수정

---

예시 3: 웹툰 제작 팀 (서브 에이전트 모드)

팀 아키텍처: 생성-검증

실행 모드: 서브 에이전트

생성-검증 패턴에서 에이전트가 2개뿐이고, 통신보다는 결과 전달이 핵심이므로 서브 에이전트가 적합.

Phase 1: Agent(webtoon-artist) → 패널 생성
Phase 2: Agent(webtoon-reviewer) → 검수
Phase 3: Agent(webtoon-artist) → 문제 패널 재생성 (최대 2회)

에이전트 구성

에이전트 파일 전문 예시: webtoon-reviewer.md

---
name: webtoon-reviewer
description: "웹툰 패널의 품질을 검수하는 전문가. 구도, 캐릭터 일관성, 텍스트 가독성, 연출을 평가한다."
---

# Webtoon Reviewer — 웹툰 품질 검수 전문가

당신은 웹툰 패널의 품질을 검수하는 전문가입니다. 시각적 완성도, 스토리 전달력, 캐릭터 일관성을 기준으로 패널을 평가합니다.

## 핵심 역할
1. 각 패널의 구도와 시각적 완성도 평가
2. 캐릭터 외형의 패널 간 일관성 검증
3. 말풍선 텍스트의 가독성과 배치 평가
4. 전체 에피소드의 연출 흐름과 페이싱 검토

## 작업 원칙
- PASS/FIX/REDO 3단계로 명확히 판정
- FIX는 부분 수정으로 해결 가능한 경우, REDO는 전면 재생성 필요
- 주관적 취향이 아닌 객관적 기준(일관성, 가독성, 구도)으로 판단

## 입력/출력 프로토콜
- 입력: `_workspace/panels/` 디렉토리의 패널 이미지들
- 출력: `_workspace/review_report.md`
- 형식:

Panel {N}

• 판정: PASS | FIX | REDO
• 사유: [구체적 이유]
• 수정 지시: [FIX/REDO인 경우 구체적 수정 방향]

## 에러 핸들링
- 이미지 로드 실패 시 해당 패널을 REDO로 판정
- 2회 재생성 후에도 REDO인 패널은 경고와 함께 PASS 처리

## 협업
- webtoon-artist에게 수정 지시서 전달 (결과 파일 기반)
- 재생성된 패널을 다시 검수 (최대 2회 루프)

에러 핸들링

재시도 정책:
- REDO 판정 패널 → artist에게 재생성 요청 (구체적 수정 지시 포함)
- 최대 2회 루프 후 강제 PASS
- 전체 패널의 50% 이상이 REDO면 사용자에게 프롬프트 수정 제안

---

예시 4: 코드 리뷰 팀 (에이전트 팀 모드)

팀 아키텍처: 팬아웃/팬인 + 토론

실행 모드: 에이전트 팀

코드 리뷰는 에이전트 팀이 빛나는 대표적 사례. 서로 다른 관점의 리뷰어들이 발견을 공유하고 도전하면서 더 깊은 리뷰가 가능.

[리더] → TeamCreate(review-team)
    ├── security-reviewer: 보안 취약점 점검
    ├── performance-reviewer: 성능 영향 분석
    └── test-reviewer: 테스트 커버리지 검증
    → 리뷰어들이 서로 발견 공유 (SendMessage)
    → 리더가 결과 종합

팀 통신 패턴

security ──SendMessage──→ performance  ("이 SQL 쿼리 주입 가능, 성능 측면에서도 확인 필요")
performance ──SendMessage──→ test      ("N+1 쿼리 발견, 관련 테스트 있는지 확인 부탁")
test ────SendMessage──→ security      ("인증 모듈 테스트 없음, 보안 관점에서 우선순위 의견?")

핵심: 리뷰어들이 리더를 거치지 않고 직접 소통하여 교차 영역 이슈를 빠르게 포착.

---

예시 5: 감독자 패턴 — 코드 마이그레이션 팀 (에이전트 팀 모드)

팀 아키텍처: 감독자

실행 모드: 에이전트 팀

[supervisor/리더] → 파일 목록 분석 → 배치 할당
    ├→ [migrator-1] (batch A)
    ├→ [migrator-2] (batch B)
    └→ [migrator-3] (batch C)
    ← TaskUpdate 수신 → 추가 배치 할당 또는 재할당

에이전트 구성

감독자의 동적 분배 로직 (에이전트 팀 활용)

1. 전체 대상 파일 목록 수집
2. 복잡도 추정 (파일 크기, import 수, 의존성)
3. TaskCreate로 파일 배치를 작업으로 등록 (의존성 포함)
4. 팀원들이 자체적으로 작업 요청 (claim)
5. 팀원이 TaskUpdate로 완료 보고 시:
   - 성공 → 다음 작업 자동 요청
   - 실패 → 리더가 SendMessage로 원인 확인 → 재할당 또는 다른 팀원에게 배정
6. 모든 작업 완료 → 리더가 통합 테스트 실행

팬아웃과의 차이: 작업이 사전 고정이 아니라 런타임에 동적으로 할당된다. 공유 작업 목록의 자체 요청(claim) 기능이 감독자 패턴과 자연스럽게 매칭.

---

산출물 패턴 요약

에이전트 정의 파일

위치: 프로젝트/.claude/agents/{agent-name}.md 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업 팀 모드 추가 섹션: 팀 통신 프로토콜 (메시지 수신/발신, 작업 요청 범위)

스킬 파일 구조

위치: 프로젝트/.claude/skills/{skill-name}/skill.md (프로젝트 레벨) 또는: ~/.claude/skills/{skill-name}/skill.md (글로벌 레벨)

통합 스킬 (오케스트레이터)

팀 전체를 조율하는 상위 스킬. 시나리오별 에이전트 구성과 워크플로우를 정의. 템플릿: references/orchestrator-template.md 참조. 실행 모드를 반드시 명시 — 에이전트 팀(기본) 또는 서브 에이전트.

Validation Playbook

Validate the harness itself before trusting it.

Required checks

1. Trigger checks

Write:

• 3 to 5 prompts that should trigger the harness
• 3 to 5 prompts that should not

The goal is to verify description clarity, not just keyword presence.

2. With-skill vs baseline

Compare:

• a run where the harness guidance is loaded
• a run where the same task is attempted without the harness

Look for differences in topology clarity, ownership boundaries, and validation coverage.

3. Artifact completeness

The harness should define:

• agents
• skills
• orchestrator or coordination contract
• validation plan

If any of these are missing, the harness is incomplete.

4. Portability review

Ask whether the design still makes sense if you strip out vendor names. If the answer is no, the harness is too coupled to one runtime.

5. Collision review

For every concurrent lane, list the files or directories it owns. Any overlap should be justified or removed.

Exit condition

The harness is ready when it is:

• clear enough to execute
• scoped enough to avoid collisions
• validated enough to compare against a baseline
• honest about native support vs adapter behavior

skill-autoresearch changelog: harness

Experiment 0 — baseline

Score: 12/15 (80%) Change: none (baseline) Reasoning: initial scoring of original SKILL.md Result: E1–E4 all pass across 3 test inputs. E5 fails on all 3: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 appears only in the intro header, not in any step instruction. Agents following the step-by-step workflow skip the header and never surface the env var in their output. Remaining failures: E5 on all 3 workflow test inputs

Experiment 1 — keep

Score: 15/15 (100%) Change: Added CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 reminder to Step 5 Integration & Orchestration Reasoning: Step 5 is where the orchestration workflow is defined and where the env var is most actionable. Adding it here ensures it appears in the generated output whenever an agent team is being created. Result: E5 now passes all 3 workflow test inputs. No regressions on E1–E4. Remaining failures: none