Harness

Harness — Agent Team & Skill Architect

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

핵심 원칙: 1. 에이전트 정의(.claude/agents/)와 스킬(.claude/skills/)을 생성한다. 2. 에이전트 팀을 기본 실행 모드로 사용한다. 3. CLAUDE.md에 하네스 포인터를 등록한다. — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다. 4. 하네스는 고정물이 아니라 진화하는 시스템이다. — 매 실행 후 피드백을 반영하고, 에이전트·스킬·CLAUDE.md를 지속 갱신한다.

워크플로우

Phase 0: 현황 감사

하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.

1. 프로젝트/.claude/agents/, 프로젝트/.claude/skills/, 프로젝트/CLAUDE.md를 읽는다 2. 현황에 따라 실행 모드를 분기한다:

• 신규 구축: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
• 기존 확장: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
• 운영/유지보수: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동

기존 확장 시 Phase 선택 매트릭스:

3. 기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다 4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다

Phase 1: 도메인 분석

1. 사용자 요청에서 도메인/프로젝트 파악 2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등) 3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석 4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악 5. 사용자 숙련도 감지 — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.

Phase 2: 팀 아키텍처 설계

2-1. 실행 모드 선택

에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.

의사결정 순서: 1. 먼저 에이전트 팀으로 설계 가능한지 검토한다 — 2명 이상이면 기본값 2. 팀 통신이 구조적으로 불필요하고(결과 전달만), 팀 오버헤드가 이득보다 클 때만 서브 에이전트 선택 3. Phase별 특성이 확연히 다르면 하이브리드 고려 — 각 Phase의 실행 모드를 오케스트레이터에 명시

상세 비교표와 패턴별 의사결정 트리는 references/agent-design-patterns.md의 "실행 모드" 참조.

2-2. 아키텍처 패턴 선택

1. 작업을 전문 영역으로 분해 2. 에이전트 팀 구조 결정 (아키텍처 패턴은 references/agent-design-patterns.md 참조)

• 파이프라인: 순차 의존 작업
• 팬아웃/팬인: 병렬 독립 작업
• 전문가 풀: 상황별 선택 호출
• 생성-검증: 생성 후 품질 검수
• 감독자: 중앙 에이전트가 상태 관리 및 동적 분배
• 계층적 위임: 상위 에이전트가 하위에 재귀적 위임

2-3. 에이전트 분리 기준

전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 references/agent-design-patterns.md의 "에이전트 분리 기준" 참조. 기존 에이전트와의 중복·재사용 검토는 Phase 3-0에서 다룬다.

Phase 3: 에이전트 정의 생성

3-0. 기존 에이전트 중복 검토

신규 에이전트 생성 전, 프로젝트/.claude/agents/의 기존 에이전트와 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 역할이 겹치는 에이전트가 다른 이름으로 누적되기 쉽다.

중복 분류 기준과 재사용 설계는 references/agent-design-patterns.md의 "에이전트 재사용 설계" 참조.

모든 에이전트는 반드시 `프로젝트/.claude/agents/{name}.md` 파일로 정의한다. 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:

• 에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능
• 팀 통신 프로토콜이 명시되어야 에이전트 간 협업 품질 보장
• 하네스의 핵심 가치는 에이전트(누가)와 스킬(어떻게)의 분리

빌트인 타입(general-purpose, Explore, Plan)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 subagent_type 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다.

모델 설정: 모든 에이전트는 model: "opus"를 사용한다. Agent 도구 호출 시 반드시 model: "opus" 파라미터를 명시한다. 하네스의 품질은 에이전트의 추론 능력에 직결되며, opus가 최고 품질을 보장한다.

팀 재구성: 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다.

각 에이전트를 프로젝트/.claude/agents/{name}.md에 정의한다. 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업. 에이전트 팀 모드에서는 ## 팀 통신 프로토콜 섹션을 추가하여 메시지 수신/발신 대상과 작업 요청 범위를 명시한다.

정의 템플릿과 실제 파일 전문은 references/agent-design-patterns.md의 "에이전트 정의 구조" + references/team-examples.md 참조.

QA 에이전트 포함 시 필수 사항:

• QA 에이전트는 general-purpose 타입을 사용하라 (Explore는 읽기 전용이므로 검증 스크립트 실행 불가)
• QA의 핵심은 "존재 확인"이 아니라 "경계면 교차 비교" — API 응답과 프론트 훅을 동시에 읽고 shape을 비교
• QA는 전체 완성 후 1회가 아니라, 각 모듈 완성 직후 점진적으로 실행 (incremental QA)
• 상세 가이드: references/qa-agent-guide.md 참조

Phase 4: 스킬 생성

각 에이전트가 사용할 스킬을 프로젝트/.claude/skills/{name}/SKILL.md에 생성한다. 상세 작성 가이드는 references/skill-writing-guide.md 참조.

4-0. 기존 스킬 중복 검토

신규 스킬 생성 전, 프로젝트/.claude/skills/의 기존 스킬과 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 기능이 겹치는 스킬이 다른 이름으로 누적되기 쉽다.

중복 분류 기준과 일반화 패턴은 references/skill-writing-guide.md의 "스킬 재사용 설계" 참조.

4-1. 스킬 구조

skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter (name, description 필수)
│   └── Markdown 본문
└── Bundled Resources (선택)
    ├── scripts/    - 반복/결정적 작업용 실행 코드
    ├── references/ - 조건부 로딩하는 참조 문서
    └── assets/     - 출력에 사용되는 파일 (템플릿, 이미지 등)

4-2. Description 작성 — 적극적 트리거 유도

description은 스킬의 유일한 트리거 메커니즘이다. Claude는 트리거를 보수적으로 판단하는 경향이 있으므로, description을 적극적("pushy")으로 작성한다.

나쁜 예: "PDF 문서를 처리하는 스킬" 좋은 예: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것."

핵심: 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술하고, 유사하지만 트리거하면 안 되는 경우와 구분되도록 작성.

4-3. 본문 작성 원칙

4-4. Progressive Disclosure (단계적 정보 공개)

스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:

크기 관리 규칙:

• SKILL.md가 500줄에 근접하면 세부 내용을 references/로 분리하고, 본문에 "언제 이 파일을 읽으라"는 포인터를 남긴다
• 300줄 이상의 reference 파일에는 상단에 목차(ToC)를 포함한다
• 도메인/프레임워크별 변형이 있으면 references/ 하위에 도메인별로 분리하여, 관련 파일만 로드한다

cloud-deploy/
├── SKILL.md (워크플로우 + 선택 가이드)
└── references/
    ├── aws.md    ← AWS 선택 시만 로드
    ├── gcp.md
    └── azure.md

4-5. 스킬-에이전트 연결 원칙

• 에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다)
• 여러 에이전트가 공유하는 스킬도 가능
• 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다

상세 작성 패턴, 예시, 데이터 스키마 표준은 references/skill-writing-guide.md 참조.

Phase 5: 통합 및 오케스트레이션

오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 references/orchestrator-template.md 참조.

기존 확장 시 오케스트레이터 수정: 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다.

Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다:

5-0. 오케스트레이터 패턴 (모드별)

에이전트 팀 패턴 (기본): 오케스트레이터가 TeamCreate로 팀을 구성하고, TaskCreate로 작업을 할당한다. 팀원들은 SendMessage로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.

[오케스트레이터/리더]
    ├── TeamCreate(team_name, members)
    ├── TaskCreate(tasks with dependencies)
    ├── 팀원들이 자체 조율 (SendMessage)
    ├── 결과 수집 및 종합
    └── 팀 정리

서브 에이전트 패턴 (대안): 오케스트레이터가 Agent 도구로 서브 에이전트를 직접 호출한다. 병렬 실행은 run_in_background: true, 결과는 메인에게만 반환된다. 팀 통신이 불필요하고 오버헤드를 줄이고 싶을 때 사용.

[오케스트레이터]
    ├── Agent(agent-1, run_in_background=true)
    ├── Agent(agent-2, run_in_background=true)
    ├── 결과 대기 및 수집
    └── 통합 산출물 생성

하이브리드 패턴: Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:

• 병렬 수집(서브) → 합의 통합(팀): Phase 2에서 서브 에이전트로 독립 자료를 병렬 수집 → Phase 3에서 팀을 만들어 토론·합의 기반 통합
• 팀 생성(팀) → 검증(서브): Phase 2에서 팀이 초안 생성 → Phase 3에서 단일 서브 에이전트가 독립 검증
• Phase 간 팀 재구성: 각 Phase마다 TeamDelete 후 새 TeamCreate, 사이에 서브 에이전트 호출 삽입

하이브리드 선택 시 오케스트레이터의 각 Phase 섹션 상단에 해당 Phase의 실행 모드를 명시한다 (예: **실행 모드:** 에이전트 팀).

5-1. 데이터 전달 프로토콜

오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:

권장 조합 (팀 모드): 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통) 권장 조합 (서브 모드): 반환값 기반(결과 수집) + 파일 기반(대용량 산출물) 하이브리드: 각 Phase의 실행 모드에 맞춰 해당 조합 적용

파일 기반 전달 시 규칙:

• 작업 디렉토리 하위에 _workspace/ 폴더를 만들어 중간 산출물 저장
• 파일명 컨벤션: {phase}_{agent}_{artifact}.{ext} (예: 01_analyst_requirements.md)
• 최종 산출물만 사용자 지정 경로에 출력, 중간 파일(_workspace/)은 보존 (사후 검증·감사 추적용)

5-2. 에러 핸들링

오케스트레이터 내에 에러 처리 방침을 포함한다. 핵심 원칙: 1회 재시도 후 재실패 시 해당 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제하지 않고 출처 병기.

에러 유형별 전략표와 구현 상세는 references/orchestrator-template.md의 "에러 핸들링" 참조.

5-3. 팀 크기 가이드라인

팀원이 많을수록 조율 오버헤드가 커진다. 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다.

5-4. CLAUDE.md 하네스 포인터 등록

하네스 구성 완료 후, 프로젝트의 CLAUDE.md에 최소한의 포인터를 등록한다. CLAUDE.md는 새 세션마다 로딩되므로, 하네스 존재와 트리거 규칙만 기록하면 오케스트레이터 스킬이 나머지를 처리한다.

CLAUDE.md 템플릿:

````markdown

하네스: {도메인명}

목표: {하네스의 핵심 목표 한 줄}

트리거: {도메인} 관련 작업 요청 시 {orchestrator-skill-name} 스킬을 사용하라. 단순 질문은 직접 응답 가능.

변경 이력:

````

CLAUDE.md에 넣지 않는 것: 에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. 이유: 에이전트/스킬 목록은 오케스트레이터 스킬과 .claude/agents/, .claude/skills/에서 관리하므로 중복이다. 디렉토리 구조는 파일 시스템에서 직접 확인 가능하다. CLAUDE.md는 포인터(트리거 규칙) + 변경 이력만 담는다.

5-5. 후속 작업 지원

오케스트레이터는 초기 실행뿐 아니라 후속 작업도 처리해야 한다. 다음 세 가지를 보장하라:

1. 오케스트레이터 description에 후속 키워드 포함: 초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현:

• "다시 실행", "재실행", "업데이트", "수정", "보완"
• "{도메인}의 {부분작업}만 다시"
• "이전 결과 기반으로", "결과 개선"

2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가: 워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:

• _workspace/ 존재 + 사용자가 부분 수정 요청 → 부분 재실행 (해당 에이전트만 재호출)
• _workspace/ 존재 + 사용자가 새 입력 제공 → 새 실행 (기존 _workspace를 _workspace_prev/로 이동)
• _workspace/ 미존재 → 초기 실행

3. 에이전트 정의에 재호출 지침 포함: 각 에이전트 .md 파일에 "이전 산출물이 있을 때의 행동"을 명시한다:

• 이전 결과 파일이 존재하면 읽고 개선점을 반영
• 사용자 피드백이 주어지면 해당 부분만 수정

오케스트레이터 템플릿의 "Phase 0: 컨텍스트 확인" 섹션 참조: references/orchestrator-template.md

Phase 6: 검증 및 테스트

생성된 하네스를 검증한다. 상세 테스트 방법론은 references/skill-testing-guide.md 참조.

6-1. 구조 검증

• 모든 에이전트 파일이 올바른 위치에 있는지 확인
• 스킬의 frontmatter(name, description) 검증
• 에이전트 간 참조 일관성 확인
• 커맨드가 생성되지 않았는지 확인

6-2. 실행 모드별 검증

• 에이전트 팀: 팀원 간 통신 경로, 작업 의존성, 팀 크기 적정성 확인
• 서브 에이전트: 각 에이전트의 입출력 연결, run_in_background 설정, 반환값 수집 로직 확인
• 하이브리드: 각 Phase의 실행 모드가 오케스트레이터에 명시되었는지, Phase 경계에서 데이터 전달이 끊기지 않는지 확인 (팀 → 서브 전환 시 팀의 산출물이 서브의 입력으로 연결되는지)

6-3. 스킬 실행 테스트

생성된 각 스킬에 대해 실제 실행 테스트를 수행한다:

1. 테스트 프롬프트 작성 — 각 스킬에 대해 2~3개의 현실적인 테스트 프롬프트를 작성한다. 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장으로 작성한다.

2. With-skill vs Without-skill 비교 실행 — 가능하면 스킬 있는 실행과 없는 실행을 병렬로 수행하여 스킬의 부가가치를 확인한다. 에이전트를 두 개씩 스폰한다:

• With-skill: 스킬을 읽고 작업 수행
• Without-skill (baseline): 같은 프롬프트를 스킬 없이 수행

3. 결과 평가 — 산출물의 품질을 정성적(사용자 리뷰) + 정량적(assertion 기반) 으로 평가한다. 산출물이 객관적으로 검증 가능한 경우(파일 생성, 데이터 추출 등) assertion을 정의하고, 주관적인 경우(문체, 디자인) 사용자 피드백에 의존한다.

4. 반복 개선 루프 — 테스트 결과에서 문제가 발견되면:

• 피드백을 일반화하여 스킬을 수정한다 (특정 예시에만 맞는 좁은 수정 금지)
• 수정 후 재테스트한다
• 사용자가 만족하거나 의미 있는 개선이 더 이상 없을 때까지 반복한다

5. 반복 패턴 번들링 — 테스트 실행에서 에이전트들이 공통으로 작성하는 코드(예: 모든 테스트에서 동일한 헬퍼 스크립트를 생성)가 발견되면, 해당 코드를 scripts/에 미리 번들링한다.

6-4. 트리거 검증

각 스킬의 description이 올바르게 트리거되는지 검증한다:

1. Should-trigger 쿼리 (8~10개) — 스킬을 트리거해야 하는 다양한 표현 (공식적/캐주얼, 명시적/암시적) 2. Should-NOT-trigger 쿼리 (8~10개) — 키워드가 유사하지만 이 스킬이 아닌 다른 도구/스킬이 적합한 "near-miss" 쿼리

near-miss 작성 핵심: "피보나치 함수 작성" 같이 명백히 무관한 쿼리는 테스트 가치가 없다. "이 엑셀 파일의 차트를 PNG로 추출해줘" (xlsx 스킬 vs 이미지 변환)처럼 경계가 모호한 쿼리가 좋은 테스트 케이스다.

기존 스킬과의 트리거 충돌도 이 단계에서 확인한다.

6-5. 드라이런 테스트

• 오케스트레이터 스킬의 Phase 순서가 논리적인지 검토
• 데이터 전달 경로에 빈 구간(dead link)이 없는지 확인
• 모든 에이전트의 입력이 이전 Phase의 출력과 매칭되는지 확인
• 에러 시나리오별 폴백 경로가 실행 가능한지 확인

6-6. 테스트 시나리오 작성

• 오케스트레이터 스킬에 ## 테스트 시나리오 섹션 추가
• 정상 흐름 1개 + 에러 흐름 1개 이상 기술

Phase 7: 하네스 진화

하네스는 한 번 만들고 끝나는 정적 산출물이 아니다. 사용자 피드백에 따라 계속 진화하는 시스템이다.

7-1. 실행 후 피드백 수집

매 하네스 실행 완료 후, 사용자에게 피드백을 요청한다:

• "결과에서 개선할 부분이 있나요?"
• "에이전트 팀 구성이나 워크플로우에 바꾸고 싶은 점이 있나요?"

피드백이 없으면 넘어간다. 강요하지 않되, 반드시 기회를 제공한다.

7-2. 피드백 반영 경로

피드백 유형에 따라 수정 대상이 다르다:

7-3. 변경 이력

모든 변경은 CLAUDE.md의 변경 이력 테이블에 기록한다 (Phase 5-4 템플릿의 "변경 이력" 섹션과 동일 테이블):

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-04-05 | 초기 구성 | 전체 | - |
| 2026-04-07 | QA 에이전트 추가 | agents/qa.md | 산출물 품질 검증 부족 피드백 |
| 2026-04-10 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 |

이 이력을 통해 하네스가 어떤 방향으로 진화했는지 추적하고, 퇴행(regression)을 방지한다.

7-4. 진화 트리거

사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다:

• 같은 유형의 피드백이 2회 이상 반복될 때
• 에이전트가 반복적으로 실패하는 패턴이 발견될 때
• 사용자가 오케스트레이터를 우회하여 수동으로 작업하는 것이 관찰될 때

7-5. 운영/유지보수 워크플로우

기존 하네스의 점검·수정·동기화를 체계적으로 수행한다. Phase 0에서 "운영/유지보수" 분기로 진입했을 때 이 워크플로우를 따른다.

Step 1: 현황 감사

• .claude/agents/ 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성
• .claude/skills/ 디렉토리 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성
• 감사 결과를 사용자에게 보고한다

Step 2: 점진적 추가/수정

• 사용자 요청에 따라 에이전트 추가/수정/삭제, 스킬 추가/수정/삭제를 수행한다
• 변경은 한 번에 하나씩, 각 변경 후 즉시 Step 3(동기화)을 실행한다

Step 3: CLAUDE.md 변경 이력 갱신

• 변경 이력 테이블에 날짜, 변경 내용, 대상, 사유를 기록한다

Step 4: 변경 검증

• 수정된 에이전트/스킬의 구조 검증 (Phase 6-1 기준)
• 수정 범위가 트리거에 영향을 주면 트리거 검증 (Phase 6-4 기준)
• 대규모 변경(아키텍처 변경, 에이전트 3개 이상 추가/삭제) 시 Phase 6-3(실행 테스트), 6-5(드라이런)까지 수행
• CLAUDE.md와 실제 파일의 일치 여부 최종 확인

산출물 체크리스트

생성 완료 후 확인:

• [ ] 프로젝트/.claude/agents/ — 에이전트 정의 파일 필수 생성 (빌트인 타입이라도 파일 생성 필수)
• [ ] 프로젝트/.claude/skills/ — 스킬 파일들 (SKILL.md + references/)
• [ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함)
• [ ] 실행 모드 명시 (에이전트 팀 / 서브 에이전트 / 하이브리드 중 선택, 하이브리드면 Phase별 모드 기재)
• [ ] 모든 Agent 호출에 model: "opus" 파라미터 명시
• [ ] 신규 에이전트 생성 전 기존 에이전트 중복 검토 완료 (Phase 3-0)
• [ ] 신규 스킬 생성 전 기존 스킬 중복 검토 완료 (Phase 4-0)
• [ ] .claude/commands/ — 아무것도 생성하지 않음
• [ ] 기존 에이전트/스킬과 충돌 없음
• [ ] 스킬 description이 적극적("pushy")으로 작성됨 — 후속 작업 키워드 포함
• [ ] SKILL.md 본문이 500줄 이내, 초과 시 references/ 분리
• [ ] 테스트 프롬프트 2~3개로 실행 검증 완료
• [ ] 트리거 검증 (should-trigger + should-NOT-trigger) 완료
• [ ] CLAUDE.md에 하네스 포인터 등록 (트리거 규칙 + 변경 이력)
• [ ] CLAUDE.md 변경 이력에 에이전트/스킬 추가/삭제/수정 기록
• [ ] 오케스트레이터 Phase 1에 컨텍스트 확인 단계 (초기/후속/부분 재실행 판별)

참고

• 하네스 패턴: references/agent-design-patterns.md
• 기존 하네스 예시 (실제 파일 전문 포함): references/team-examples.md
• 오케스트레이터 템플릿: references/orchestrator-template.md
• 스킬 작성 가이드: references/skill-writing-guide.md — 작성 패턴, 예시, 데이터 스키마 표준
• 스킬 테스트 가이드: references/skill-testing-guide.md — 테스트/평가/반복 개선 방법론
• QA 에이전트 가이드: references/qa-agent-guide.md — 빌드 하네스에 QA 에이전트를 포함할 때 참조. 통합 정합성 검증 방법론, 경계면 버그 패턴, QA 에이전트 정의 템플릿 포함. 실제 프로젝트에서 발견된 7개 버그 사례 기반.

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 도구, 전용이면 인라인, 대용량이면 레퍼런스 로드.

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

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

• 템플릿 A: 에이전트 팀 모드 (기본) — 2명 이상 협업 시 최우선 선택
• 템플릿 B: 서브 에이전트 모드 (대안) — 팀 통신이 불필요한 경우
• 템플릿 C: 하이브리드 모드 — Phase마다 모드를 섞어 구성

---

템플릿 A: 에이전트 팀 모드 (기본 · 최우선 선택)

2명 이상의 에이전트가 협업할 때 가장 먼저 검토하는 기본 모드. TeamCreate로 팀을 구성하고, 공유 작업 목록과 SendMessage로 조율한다.

---
name: {domain}-orchestrator
description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업: {도메인} 결과 수정, 부분 재실행, 업데이트, 보완, 다시 실행, 이전 결과 개선 요청 시에도 반드시 이 스킬을 사용."
---

# {Domain} Orchestrator

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

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

## 에이전트 구성

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

## 워크플로우

### Phase 0: 컨텍스트 확인 (후속 작업 지원)

기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:

1. `_workspace/` 디렉토리 존재 여부 확인
2. 실행 모드 결정:
   - **`_workspace/` 미존재** → 초기 실행. Phase 1로 진행
   - **`_workspace/` 존재 + 사용자가 부분 수정 요청** → 부분 재실행. 해당 에이전트만 재호출하고, 기존 산출물 중 수정 대상만 덮어쓴다
   - **`_workspace/` 존재 + 새 입력 제공** → 새 실행. 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 이동한 뒤 Phase 1 진행
3. 부분 재실행 시: 이전 산출물 경로를 에이전트 프롬프트에 포함하여, 에이전트가 기존 결과를 읽고 피드백을 반영하도록 지시

### Phase 1: 준비
1. 사용자 입력 분석 — {무엇을 파악하는지}
2. 작업 디렉토리에 `_workspace/` 생성
   - **초기 실행**: 새 `_workspace/` 생성
   - **새 실행**: 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 이동한 직후 새 `_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: "{도메인} 에이전트를 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업 키워드 포함."
---

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

## 에이전트 구성

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

## 워크플로우

### Phase 0: 컨텍스트 확인
(Template A와 동일 — `_workspace/` 존재 여부 분기)

### Phase 1: 준비
1. 입력 분석
2. `_workspace/` 생성 (초기 실행 시, 또는 새 실행에서 기존 `_workspace/`를 보관 디렉토리로 이동한 직후)

### 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 |

### Phase 3: 통합
1. 각 에이전트의 반환값 수집
2. 파일 기반 산출물은 Read로 수집
3. 통합 로직 적용 → 최종 산출물

### Phase 4: 정리
1. `_workspace/` 보존
2. 결과 요약 보고

## 에러 핸들링
- 에이전트 1개 실패: 1회 재시도. 재실패 시 누락 명시하고 진행
- 과반 실패: 사용자에게 알리고 진행 여부 확인
- 타임아웃: 현재까지 수집된 부분 결과 사용

---

템플릿 C: 하이브리드 모드

Phase마다 다른 실행 모드를 사용한다. 각 Phase 상단에 **실행 모드:** {팀 | 서브}를 명시한다.

---
name: {domain}-orchestrator
description: "{도메인} 오케스트레이터 (하이브리드). {키워드}. 후속 작업 키워드 포함."
---

## 실행 모드: 하이브리드

| Phase | 모드 | 이유 |
|-------|------|------|
| Phase 2 (병렬 수집) | 서브 에이전트 | 독립 자료 수집, 팀 통신 불필요 |
| Phase 3 (합의 통합) | 에이전트 팀 | 상충 데이터 토론·합의 필요 |
| Phase 4 (독립 검증) | 서브 에이전트 | QA 에이전트 1명이 객관 검증 |

## 워크플로우

### Phase 2: 병렬 자료 수집
**실행 모드:** 서브 에이전트

단일 메시지에서 Agent 도구로 N개 에이전트 병렬 호출 (`run_in_background: true`).
각 결과는 `_workspace/02_{agent}_raw.md`에 저장.

### Phase 3: 합의 기반 통합
**실행 모드:** 에이전트 팀

1. `TeamCreate`로 통합 팀 구성 (editor + fact-checker + synthesizer)
2. `TaskCreate`로 작업 분배 — 모두 Phase 2의 `_workspace/02_*` 파일을 Read
3. 팀원들이 `SendMessage`로 상충 데이터를 논의, 파일 기반으로 합의안 도출
4. 최종 통합본 `_workspace/03_integrated.md` 생성
5. `TeamDelete`로 팀 정리

### Phase 4: 독립 검증
**실행 모드:** 서브 에이전트

단일 QA 서브 에이전트가 `_workspace/03_integrated.md`를 입력으로 받아 검증 보고서 생성.

하이브리드 전환 규칙:

• 팀 → 서브: 팀을 반드시 TeamDelete로 정리한 후 Agent 도구 호출
• 서브 → 팀: 서브 에이전트의 파일 산출물을 팀원들에게 Read 경로로 전달
• 팀 → 팀: 이전 팀을 정리한 후 새 TeamCreate (세션당 1팀만 활성 가능)

---

작성 원칙

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

description 작성 시 후속 작업 키워드

오케스트레이터 description은 초기 실행 키워드만으로는 부족하다. 다음 후속 작업 표현을 반드시 포함하라:

• 재실행/다시 실행/업데이트/수정/보완
• "{도메인}의 {부분}만 다시"
• "이전 결과 기반으로", "결과 개선"
• 도메인 관련 일상적 요청 (예: 런치 전략 하네스라면 "런치", "홍보", "트렌딩" 등)

후속 키워드가 없으면 첫 실행 후 하네스가 사실상 죽은 코드가 된다.

실제 오케스트레이터 참고

팬아웃/팬인 패턴의 오케스트레이터 기본 구조: 준비 → Phase 0(컨텍스트 확인) → 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에서 발견된 버그

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

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

하네스에서 생성한 스킬의 품질을 검증하고 반복적으로 개선하는 방법론. 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가 알고 있는 일반적 지식

---

9. 스킬 재사용 설계

신규 스킬 생성 전, 기존 스킬과의 중복을 확인한다. 하네스를 반복 구축하다 보면 기능이 겹치는 스킬이 다른 이름으로 누적되기 쉽다.

원칙: 하나의 스킬이 하나의 역할에 집중할수록 재사용성이 높고 중복이 줄어든다. 역할이 두 가지 이상이면 분리할 수 있는지 먼저 검토한다.

어디까지 일반화할지

일반화는 무한히 가능하므로 의도된 책임 범위에서 멈춘다. 의도된 도메인 특화는 유지하고, 우연한 종속만 제거한다.

예: "fintech 리스크 평가 PDF" 스킬

책임 범위가 "fintech 리스크 평가"로 의도된 특화라면 일반화하지 않고 별개 스킬로 유지한다.

해당 스킬에 의존하는 에이전트의 동작이 변경될 수 있다. 확장 전 의존성을 확인하고, description에 확장된 사용 범위를 반영한다.

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 참조. 실행 모드를 반드시 명시 — 에이전트 팀(기본) 또는 서브 에이전트.