harness · diff
git:20260515.0768fcd to git:20260926.928de2c
275 added, 327 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: harness
- description: "하네스를 구성합니다. 전문 에이전트를 정의하며, 해당 에이전트가 사용할 스킬을 생성하는 메타 스킬. (1) '하네스 구성해줘', '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링' 요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화 체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때, (5) '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 등 기존 하네스 운영/유지보수 요청 시 사용."
+ description: "프로젝트에 맞는 하네스를 설계하고, 전문 에이전트와 각 에이전트가 사용할 스킬을 만든다. 사용자가 '하네스 구성해줘', '하네스 구축해줘', '하네스 설계', '하네스 엔지니어링', '에이전트 팀 만들어줘'라고 요청할 때 사용한다. 새로운 분야나 프로젝트의 자동화 체계를 구축하거나 기존 하네스를 재구성·확장할 때도 사용한다. '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화'처럼 기존 하네스를 운영하거나 유지 보수하는 요청에도 사용한다. 실행 결과를 회고하고 피드백을 반영하는 작업에는 harness:evolve 스킬을 사용한다."
---
- # Harness — Agent Team & Skill Architect
+ # Harness v2 — 에이전트 팀과 스킬 설계
- 도메인/프로젝트에 맞는 하네스를 구성하고, 각 에이전트의 역할을 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.
+ 프로젝트에 맞는 하네스를 설계한다. 각 에이전트의 역할을 정의하고, 에이전트가 작업할 때 따를 스킬을 만든다.
- **핵심 원칙:**
- 1. 에이전트 정의(`.claude/agents/`)와 스킬(`.claude/skills/`)을 생성한다.
- 2. **에이전트 팀을 기본 실행 모드로 사용한다.**
- 3. **CLAUDE.md에 하네스 포인터를 등록한다.** — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다.
- 4. **하네스는 고정물이 아니라 진화하는 시스템이다.** — 매 실행 후 피드백을 반영하고, 에이전트·스킬·CLAUDE.md를 지속 갱신한다.
+ ## 핵심 원칙
- ## 워크플로우
+ 1. 에이전트 정의는 `프로젝트/.claude/agents/`에, 스킬은 `프로젝트/.claude/skills/`에 만든다. 에이전트에는 누가 일하는지를, 스킬에는 그 일을 어떻게 하는지를 적는다.
+ 2. 작업 흐름에 따라 실행 모드를 고른다. 순서와 반복 조건을 코드로 정할 수 있으면 워크플로로 조율한다. 같은 전문가와 피드백을 주고받아야 하면 지속형 에이전트를 쓴다. 결과를 한 번만 받으면 되는 작업은 서브에이전트에 맡긴다. 자세한 선택 기준은 2단계에서 다룬다.
+ 3. 업무의 복잡도, 작업 기간, 자율성, 응답 속도에 맞춰 모델을 고른다. 계획을 세워 장기간 자율적으로 실행해야 하는 최고 난도 업무에는 fable, 설계·코드 생성·복잡한 분석·교차 검증에는 opus, 로그 분석·형식 변환·단순 수집 같은 일상 업무에는 sonnet을 쓴다. 자세한 기준은 3단계에서 다룬다.
+ 4. 새 세션에서도 오케스트레이터 스킬을 불러올 수 있도록 `CLAUDE.md`에 호출 조건과 변경 이력만 기록한다.
+ 5. 실행 결과에서 배운 내용을 에이전트·스킬·`CLAUDE.md`에 계속 반영한다. 회고하고 변경 사항을 찾아내는 작업은 `harness:evolve` 스킬이 맡는다.
+ 6. 생성하는 에이전트 정의, 스킬, 오케스트레이터, `CLAUDE.md` 기록은 사용자가 대화에 쓰는 언어로 작성한다. 이 스킬 문서와 `references/`의 템플릿이 한국어로 쓰였다는 이유로 산출물을 한국어로 쓰지 않는다. 템플릿의 제목과 예시 문구도 그 언어로 옮긴다. 사용자가 언어를 따로 정하면 그 언어를 따르고, 따로 정하지 않은 채 기존 하네스를 확장하면 기존 파일의 언어를 따른다.
- ### Phase 0: 현황 감사
+ ## 진행 절차
- 하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.
+ ### 0단계: 현재 상태 점검
- 1. `프로젝트/.claude/agents/`, `프로젝트/.claude/skills/`, `프로젝트/CLAUDE.md`를 읽는다
- 2. 현황에 따라 실행 모드를 분기한다:
- - **신규 구축**: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
- - **기존 확장**: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
- - **운영/유지보수**: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동
+ 하네스 스킬을 불러오면 기존 구성을 먼저 확인한다.
- **기존 확장 시 Phase 선택 매트릭스:**
- | 변경 유형 | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | Phase 6 |
- |----------|---------|---------|---------|---------|---------|---------|
- | 에이전트 추가 | 건너뜀 (Phase 0 결과 활용) | 배치 결정만 | 필수 (3-0 포함) | 전용 스킬 필요 시 (4-0 포함) | 오케스트레이터 수정 | 필수 |
- | 스킬 추가/수정 | 건너뜀 | 건너뜀 | 건너뜀 | 필수 (4-0 포함) | 연결 변경 시 | 필수 |
- | 아키텍처 변경 | 건너뜀 | 필수 | 영향받는 에이전트만 (3-0 포함) | 영향받는 스킬만 (4-0 포함) | 필수 | 필수 |
- 3. 기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다
- 4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다
+ 1. `프로젝트/.claude/agents/`, `프로젝트/.claude/skills/`, `프로젝트/CLAUDE.md`를 읽는다.
+ 2. 현재 상태에 따라 진행할 절차를 고른다.
+ - **새로 구축**: 에이전트나 스킬 디렉터리가 없거나 비어 있으면 1단계부터 모두 실행한다.
+ - **기존 구성 확장**: 기존 하네스에 에이전트나 스킬을 추가해야 하면 아래 표에서 필요한 단계만 실행한다.
+ - **운영·유지 보수**: 기존 하네스를 점검·수정·동기화해야 하면 7단계의 운영 절차로 이동한다.
- ### Phase 1: 도메인 분석
- 1. 사용자 요청에서 도메인/프로젝트 파악
- 2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
- 3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석
- 4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악
- 5. **사용자 숙련도 감지** — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.
+ | 변경 내용 | 1단계 | 2단계 | 3단계 | 4단계 | 5단계 | 6단계 |
+ | --- | --- | --- | --- | --- | --- | --- |
+ | 에이전트 추가 | 생략하고 0단계 결과 사용 | 어떤 실행 모드에서 어느 팀과 단계에 둘지만 결정 | 필수 | 전용 스킬이 필요할 때 | 오케스트레이터 수정 | 필수 |
+ | 스킬 추가·수정 | 생략 | 생략 | 생략 | 필수 | 연결이 바뀔 때 | 필수 |
+ | 구조·실행 모드 변경 | 생략 | 필수 | 영향을 받는 에이전트만 | 영향을 받는 스킬만 | 필수 | 필수 |
- ### Phase 2: 팀 아키텍처 설계
+ 3. 기존 오케스트레이터에 `TeamCreate`, `TeamDelete`, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`가 있으면 v1 산출물이다. 현재 실행 환경에서는 작동하지 않으므로 v2로 옮기자고 제안한다. 자세한 방법은 `references/execution-modes.md`의 「v1에서 v2로 전환」을 따른다.
+ 4. 실제 에이전트·스킬 목록과 `CLAUDE.md` 기록을 대조해 불일치를 찾는다.
+ 5. 점검 결과와 실행 계획을 사용자에게 알리고 확인받는다.
+ ### 1단계: 분야와 작업 분석
+
+ 1. 사용자 요청에서 프로젝트의 분야와 목표를 파악한다.
+ 2. 생성, 검증, 편집, 분석처럼 필요한 작업의 종류를 나눈다.
+ 3. 실행 모드를 고를 수 있도록 작업 흐름을 확인한다.
+ - 처리할 목록을 미리 나열할 수 있는가? 예: 파일 N개를 옮기거나 관점 M개를 검토하는 작업
+ - 산출물을 검증하고 다시 고치는 반복 절차가 필요한가?
+ - 에이전트가 서로 의견을 주고받아야 결과가 좋아지는가?
+ - 한 세션 안에서 같은 전문가와 계속 대화해야 하는가?
+ 4. 0단계에서 확인한 기존 에이전트·스킬과 겹치거나 충돌하는 부분을 찾는다.
+ 5. 코드베이스를 살펴 기술 스택, 데이터 모델, 주요 모듈을 파악한다.
+ 6. 사용자가 쓰는 용어와 질문 수준을 보고 설명의 난이도를 맞춘다. 코딩 경험이 적은 사용자에게 검증 조건(assertion), JSON 스키마(JSON Schema) 같은 용어를 설명 없이 쓰지 않는다.
+
+ ### 2단계: 실행 모드와 팀 구조 설계
+
#### 2-1. 실행 모드 선택
- **에이전트 팀이 최우선 기본값이다.** 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.
+ Harness v2는 Claude Code의 멀티에이전트 기능 세 가지를 사용한다. 작업 흐름에 맞춰 다음 모드 가운데 하나를 고른다.
- | 모드 | 언제 사용 | 특성 |
- |------|----------|------|
- | **에이전트 팀** (기본) | 2명 이상 협업, 실시간 조율·피드백 교환이 필요, 중간 산출물 상호 참조 | `TeamCreate` + `SendMessage` + `TaskCreate`로 자체 조율 |
- | **서브 에이전트** (대안) | 단일 에이전트 작업, 결과만 메인에 반환하면 충분, 팀 통신 오버헤드가 과할 때 | `Agent` 도구 직접 호출, `run_in_background`로 병렬 |
- | **하이브리드** | Phase마다 특성이 다를 때 — 예: 병렬 수집(서브) → 합의 기반 통합(팀) | Phase 단위로 팀/서브를 섞어 구성 |
+ | 실행 모드 | 사용하는 기능 | 알맞은 작업 |
+ | --- | --- | --- |
+ | **워크플로 조율** | `Workflow` 스크립트의 `agent()`, `pipeline()`, `parallel()`, `phase()` | 처리 목록, 검증 절차, 반복 횟수를 코드로 정할 수 있는 작업. 스키마에 맞춘 결과가 필요하거나 `Agent`를 수십 번 이상 호출해야 하는 작업 |
+ | **지속형 에이전트 협업** | `Agent(name:)`, `SendMessage`, `TaskCreate`, `TaskUpdate` | 이름 있는 전문가가 대화 맥락을 유지하면서 피드백·협상·공동 편집을 반복해야 하는 작업 |
+ | **서브에이전트 위임** | `Agent` 한 번 호출. 기본적으로 백그라운드에서 실행하며 병렬 호출 가능 | 에이전트끼리 대화할 필요가 없고 결과만 한 번 받으면 되는 작업 |
- **의사결정 순서:**
- 1. 먼저 에이전트 팀으로 설계 가능한지 검토한다 — 2명 이상이면 기본값
- 2. 팀 통신이 구조적으로 불필요하고(결과 전달만), 팀 오버헤드가 이득보다 클 때만 서브 에이전트 선택
- 3. Phase별 특성이 확연히 다르면 하이브리드 고려 — 각 Phase의 실행 모드를 오케스트레이터에 명시
+ 다음 순서로 결정한다.
- > 상세 비교표와 패턴별 의사결정 트리는 `references/agent-design-patterns.md`의 "실행 모드" 참조.
+ 1. 처리 목록, 검증 기준, 반복 조건을 미리 코드로 표현할 수 있으면 워크플로를 사용한다. 정해진 흐름을 모델의 그때그때 판단에 맡기지 않아야 같은 방식으로 다시 실행할 수 있다.
+ 2. 코드로 정하기 어렵고, 에이전트끼리 대화하거나 이전 맥락을 기억해야 하면 지속형 에이전트를 사용한다.
+ 3. 두 조건에 해당하지 않고 결과만 필요하면 서브에이전트에 맡긴다.
+ 4. 단계마다 작업 성격이 다르면 혼합 모드로 구성한다. 오케스트레이터에 각 단계의 실행 모드를 적는다.
- #### 2-2. 아키텍처 패턴 선택
+ `Workflow` 도구를 쓰려면 사용자가 명시적으로 동의해야 한다. 사용자가 직접 워크플로 실행을 요청했거나, `Workflow` 호출을 지시하는 오케스트레이터 스킬을 사용자가 불러왔다면 동의한 것으로 본다. 기본 실행은 에이전트 몇 명으로 제한하고, 사용자가 "철저히", "전수"처럼 넓은 조사를 요구했을 때만 대규모로 늘린다.
- 1. 작업을 전문 영역으로 분해
- 2. 에이전트 팀 구조 결정 (아키텍처 패턴은 `references/agent-design-patterns.md` 참조)
- - **파이프라인**: 순차 의존 작업
- - **팬아웃/팬인**: 병렬 독립 작업
- - **전문가 풀**: 상황별 선택 호출
- - **생성-검증**: 생성 후 품질 검수
- - **감독자**: 중앙 에이전트가 상태 관리 및 동적 분배
- - **계층적 위임**: 상위 에이전트가 하위에 재귀적 위임
+ > 실행 모드 비교와 동시 실행 상한, 스키마, 토큰 예산, 재개 조건은 `references/execution-modes.md`에서 확인한다.
- #### 2-3. 에이전트 분리 기준
+ #### 2-2. 팀 구성 방식 선택
- 전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 `references/agent-design-patterns.md`의 "에이전트 분리 기준" 참조. 기존 에이전트와의 중복·재사용 검토는 Phase 3-0에서 다룬다.
+ 1. 작업을 전문 분야별로 나눈다.
+ 2. 아래 여섯 가지 방식 가운데 작업에 맞는 구성을 고른다. 자세한 기준은 `references/team-patterns.md`에 있다.
+ - **파이프라인**: 앞 단계의 결과를 받아 순서대로 처리한다. `pipeline()`에 알맞다.
+ - **분산·통합(팬아웃/팬인)**: 독립 작업을 병렬로 처리한 뒤 결과를 합친다. `pipeline()`과 필요할 때만 `parallel()`을 쓴다.
+ - **전문가 풀**: 입력에 맞는 전문가만 골라 호출한다. 서브에이전트나 지속형 에이전트에 알맞다.
+ - **생성·검증**: 한 에이전트가 만들고 다른 에이전트가 검토한다. 워크플로의 적대적 검증이나 지속형 에이전트 한 쌍을 쓴다.
+ - **감독자**: 중앙 에이전트가 진행 상황을 보고 작업을 다시 배분한다. 지속형 에이전트와 공유 작업 목록을 쓴다.
+ - **계층형 위임**: 상위 에이전트가 하위 에이전트에 다시 맡긴다. 두 단계 안에서만 사용하고, 워크플로 중첩은 한 단계로 제한한다.
+ 3. 산출물의 정확성이 중요하면 다음 검증 방식을 조합한다.
+ - **적대적 검증**: 찾은 항목 한 건마다 N명의 적대적 검증 에이전트를 붙이고, 과반이 근거가 충분하다고 `confirmed`로 판정한 항목만 통과시킨다. `refuted`나 `uncertain` 판정은 통과로 세지 않는다.
+ - **심사위원단**: N개의 시안을 따로 만든 뒤 병렬로 심사하고, 가장 좋은 시안을 바탕으로 최종본을 만든다.
+ - **새 항목이 없을 때까지 반복(Loop-until-dry)**: 새로 찾은 항목이 K회 연속 0건이 될 때까지 탐색한다.
+ - **여러 기준으로 탐색**: 컨테이너, 내용, 개체, 시간처럼 서로 다른 기준으로 병렬 조사한다.
+ - **누락 검토자**: 마지막 에이전트에는 빠진 내용만 찾게 한다.
- ### Phase 3: 에이전트 정의 생성
+ #### 2-3. 에이전트를 나누는 기준
- #### 3-0. 기존 에이전트 중복 검토
+ 필요한 전문 지식, 병렬 처리 가능 여부, 유지해야 할 대화 맥락, 다시 쓸 가능성을 기준으로 에이전트를 나눈다. 자세한 표는 `references/team-patterns.md`의 「에이전트 분리 기준」에서 확인한다.
- 신규 에이전트 생성 전, `프로젝트/.claude/agents/`의 기존 에이전트와 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 역할이 겹치는 에이전트가 다른 이름으로 누적되기 쉽다.
+ ### 3단계: 에이전트 정의 작성
- > 중복 분류 기준과 재사용 설계는 `references/agent-design-patterns.md`의 "에이전트 재사용 설계" 참조.
+ 여러 세션에서 재사용할 전문 에이전트는 `프로젝트/.claude/agents/{name}.md` 파일로 정의한다. 반복해서 사용할 역할을 `Agent` 도구의 `prompt`에만 직접 넣지 않는다.
- **모든 에이전트는 반드시 `프로젝트/.claude/agents/{name}.md` 파일로 정의한다.** 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:
- - 에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능
- - 팀 통신 프로토콜이 명시되어야 에이전트 간 협업 품질 보장
- - 하네스의 핵심 가치는 에이전트(누가)와 스킬(어떻게)의 분리
+ - 파일로 정의해야 다음 세션에서도 재사용할 수 있다. `Agent` 도구에서는 `subagent_type: "{name}"`, `Workflow`에서는 `agentType: "{name}"`으로 부른다.
+ - 에이전트가 주고받을 내용을 미리 정해야 협업 결과가 안정적이다.
+ - 에이전트에는 누가 일하는지를, 스킬에는 그 일을 어떻게 하는지를 적어 서로 섞이지 않게 한다.
- 빌트인 타입(`general-purpose`, `Explore`, `Plan`)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 `subagent_type` 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다.
+ 재사용할 전문가 역할은 사용자 정의 유형으로 파일에 만들고, 호출할 때 그 파일의 이름을 `subagent_type`이나 `agentType`에 지정한다. `general-purpose`, `Explore`, `Plan` 같은 기본 제공 유형을 그대로 쓰는 단발 작업에는 별도 정의 파일을 만들지 않는다.
- **모델 설정:** 모든 에이전트는 `model: "opus"`를 사용한다. Agent 도구 호출 시 반드시 `model: "opus"` 파라미터를 명시한다. 하네스의 품질은 에이전트의 추론 능력에 직결되며, opus가 최고 품질을 보장한다.
+ #### 기존 에이전트와 겹치는지 확인
- **팀 재구성:** 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다.
+ 새 에이전트 파일을 만들기 전에 `프로젝트/.claude/agents/`의 기존 에이전트와 역할이 겹치는지 확인한다. 1단계를 생략하고 에이전트만 추가할 때도 이 확인은 건너뛰지 않는다. 하네스를 여러 번 구축하거나 확장하면 같은 역할의 에이전트가 이름만 달리해 쌓일 수 있기 때문이다. 겹치면 새 이름으로 만들지 말고 기존 에이전트를 그대로 쓰거나 확장한다. 판단 기준과 예외(도메인을 의도적으로 특화한 경우)는 `references/team-patterns.md`의 「에이전트 재사용 설계」에서 확인한다.
- 각 에이전트를 `프로젝트/.claude/agents/{name}.md`에 정의한다. 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업. 에이전트 팀 모드에서는 `## 팀 통신 프로토콜` 섹션을 추가하여 메시지 수신/발신 대상과 작업 요청 범위를 명시한다.
+ #### 모델 선택 기준
- > 정의 템플릿과 실제 파일 전문은 `references/agent-design-patterns.md`의 "에이전트 정의 구조" + `references/team-examples.md` 참조.
+ 업무의 복잡도, 작업 기간, 자율성, 응답 속도를 기준으로 에이전트마다 모델을 고른다. YAML 프론트매터(머리말)의 `model:`이나 호출 인자인 `model`, `opts.model`에 지정하고, 선택 이유를 에이전트 정의나 오케스트레이터에 주석으로 남긴다.
- **QA 에이전트 포함 시 필수 사항:**
- - QA 에이전트는 `general-purpose` 타입을 사용하라 (`Explore`는 읽기 전용이므로 검증 스크립트 실행 불가)
- - QA의 핵심은 "존재 확인"이 아니라 **"경계면 교차 비교"** — API 응답과 프론트 훅을 동시에 읽고 shape을 비교
- - QA는 전체 완성 후 1회가 아니라, **각 모듈 완성 직후 점진적으로 실행** (incremental QA)
- - 상세 가이드: `references/qa-agent-guide.md` 참조
+ | 모델 | 선택 기준 | 대표 업무 |
+ | --- | --- | --- |
+ | **fable** | 스스로 계획하고 여러 단계를 연결해 장기간 자율적으로 실행해야 하는 최고 난도 업무 | 에이전트 조율, 계획 수립과 장기 실행, 방대한 자료 통합, 막연한 아이디어 구체화 |
+ | **opus** | 범위는 분명하지만 깊은 추론과 분석이 필요한 전문 업무 | 설계·아키텍처, 코드 생성, 복잡한 분석, 교차 검증, 연구 방법 비판, 창작 |
+ | **sonnet** | 절차가 분명하고 빠른 처리가 중요한 일상 업무 | 로그 분석, 형식 변환, 정적 파일 검사, 배포 스크립트 실행, 단순 수집, 일반 글쓰기·요약 |
- ### Phase 4: 스킬 생성
+ - 앞 단계의 결과에 따라 다음 계획을 바꾸며 장기간 자율적으로 실행해야 하면 fable을 쓴다. 범위가 정해진 문제 하나를 깊이 분석하면 opus를 쓴다. 예를 들어 논문 한 편을 깊이 비판하는 작업에는 opus, 논문 수십 편을 검토해 전략과 보고서까지 만드는 작업에는 fable이 알맞다.
+ - 판단이 애매한 일반 업무에는 sonnet을 기본값으로 쓴다.
+ - 에이전트가 중요하다는 이유만으로 모두 fable이나 opus로 지정하지 않는다. 모델은 에이전트의 위상이 아니라 실제 업무 성격으로 고른다.
+ - 계획과 조율을 맡는 상위 에이전트에 fable을 썼더라도, 하위 작업자는 각 업무에 맞는 모델을 따로 고른다.
- 각 에이전트가 사용할 스킬을 `프로젝트/.claude/skills/{name}/SKILL.md`에 생성한다. 상세 작성 가이드는 `references/skill-writing-guide.md` 참조.
+ > 모델별 자세한 기준은 `references/model-selection-guide.md`에서 확인한다.
- #### 4-0. 기존 스킬 중복 검토
+ #### 정의 파일에 넣을 내용
- 신규 스킬 생성 전, `프로젝트/.claude/skills/`의 기존 스킬과 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 기능이 겹치는 스킬이 다른 이름으로 누적되기 쉽다.
+ YAML 프론트매터에는 `name`과 `description`을 반드시 넣는다. 필요하면 사용할 도구를 제한하는 `tools`와 모델을 바꾸는 `model`을 추가한다. 읽기 전용 검토·분석 에이전트의 `tools`에서는 Edit와 Write를 빼서 파일을 바꾸지 못하게 한다.
- > 중복 분류 기준과 일반화 패턴은 `references/skill-writing-guide.md`의 "스킬 재사용 설계" 참조.
+ 반대로 산출물을 고치는 에이전트에는 Write와 함께 Edit도 준다. Edit가 없으면 한 줄을 고칠 때도 파일 전체를 다시 써야 하므로, 산출물이 크면 에이전트가 수정을 포기하고 우회한다. 또 `tools`에 적은 도구가 실행할 때 주어지지 않은 사례가 있으므로, 지속형 에이전트에게는 첫 보고에서 실제로 쓸 수 있는 도구 목록을 알리게 한다.
- #### 4-1. 스킬 구조
+ 본문에는 핵심 역할, 작업 원칙, 입력·출력 규칙, 오류 처리, 협업 방법을 반드시 적는다. 지속형 에이전트에는 `## 통신 규칙`을 추가해 `SendMessage`를 주고받을 대상과 공유 작업 목록 사용법을 정한다.
+ > 정의 템플릿, 전체 예시, `tools`를 제한할 때 주의할 점은 `references/team-patterns.md`의 「에이전트 정의 구조」에서 확인한다.
+
+ #### QA 에이전트를 둘 때
+
+ - QA 에이전트에는 모든 검증 도구를 쓸 수 있는 유형을 지정한다. `Explore`는 읽기 전용이라 검증 스크립트를 실행할 수 없다.
+ - 파일 존재 여부만 확인하지 않는다. API 응답과 프런트엔드 훅의 응답 구조를 대조한다.
+ - 전체 작업이 끝난 뒤 한 번만 검사하지 않는다. 모듈을 완성할 때마다 바로 검사한다.
+ - 자세한 방법은 `references/qa-agent-guide.md`를 따른다.
+
+ ### 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 필수)
+ ├── SKILL.md # 필수
+ │ ├── YAML 프론트매터 # name과 description 필수
│ └── Markdown 본문
- └── Bundled Resources (선택)
- ├── scripts/ - 반복/결정적 작업용 실행 코드
- ├── references/ - 조건부 로딩하는 참조 문서
- └── assets/ - 출력에 사용되는 파일 (템플릿, 이미지 등)
+ ├── scripts/ # 선택: 반복하거나 결과가 항상 같아야 하는 작업의 실행 코드
+ ├── references/ # 선택: 필요할 때만 읽는 참조 문서
+ └── assets/ # 선택: 템플릿, 이미지처럼 산출물에 쓰는 파일
```
- #### 4-2. Description 작성 — 적극적 트리거 유도
+ #### 4-2. description에 호출 조건 쓰기
- description은 스킬의 유일한 트리거 메커니즘이다. Claude는 트리거를 보수적으로 판단하는 경향이 있으므로, description을 **적극적("pushy")**으로 작성한다.
+ Claude는 스킬의 `name`과 `description`을 보고 어떤 스킬을 불러올지 판단한다. 이 가운데 `description`에는 스킬이 하는 일과 사용해야 하는 상황을 구체적으로 적고, 비슷해 보이지만 사용하면 안 되는 경우도 구분한다.
**나쁜 예:** `"PDF 문서를 처리하는 스킬"`
- **좋은 예:** `"PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것."`
- 핵심: 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술하고, 유사하지만 트리거하면 안 되는 경우와 구분되도록 작성.
+ **좋은 예:** `"PDF 파일 읽기, 텍스트·표 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 PDF 작업을 수행한다. 사용자가 .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 사용한다."`
#### 4-3. 본문 작성 원칙
- | 원칙 | 설명 |
- |------|------|
- | **Why를 설명하라** | "ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. |
- | **Lean하게 유지** | 컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 references/로 이동한다. |
- | **일반화하라** | 특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지. |
- | **반복 코드는 번들링** | 테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 `scripts/`에 미리 번들링한다. |
- | **명령형으로 작성** | "~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다. |
-
- #### 4-4. Progressive Disclosure (단계적 정보 공개)
-
- 스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:
+ | 원칙 | 적용 방법 |
+ | --- | --- |
+ | **이유부터 설명한다** | `ALWAYS`, `NEVER`만 나열하지 말고 왜 필요한 규칙인지 밝힌다. 이유를 알아야 예외 상황에서도 올바르게 판단할 수 있다. |
+ | **간결하게 쓴다** | `SKILL.md`는 500줄 미만으로 유지한다. 판단에 도움이 되지 않는 내용은 지우거나 `references/`로 옮긴다. |
+ | **원리로 일반화한다** | 특정 예시에만 맞는 규칙을 만들지 않는다. 여러 입력에 적용할 수 있는 판단 기준을 적는다. |
+ | **반복 코드는 미리 넣는다** | 테스트할 때 여러 에이전트가 같은 스크립트를 다시 작성한다면 `scripts/`에 넣는다. |
+ | **지시문으로 쓴다** | `~한다`나 `~하라` 가운데 문서에 맞는 한 가지 어미를 골라 통일한다. 해야 할 행동이 분명하게 드러나야 한다. |
- | 단계 | 로딩 시점 | 크기 목표 |
- |------|----------|----------|
- | **Metadata** (name + description) | 항상 컨텍스트에 존재 | ~100단어 |
- | **SKILL.md 본문** | 스킬 트리거 시 | <500줄 |
- | **references/** | 필요할 때만 | 무제한 (스크립트는 로딩 없이 실행 가능) |
+ #### 4-4. 필요한 정보만 단계별로 불러오기
- **크기 관리 규칙:**
- - SKILL.md가 500줄에 근접하면 세부 내용을 references/로 분리하고, 본문에 "언제 이 파일을 읽으라"는 포인터를 남긴다
- - 300줄 이상의 reference 파일에는 상단에 **목차(ToC)**를 포함한다
- - 도메인/프레임워크별 변형이 있으면 references/ 하위에 도메인별로 분리하여, 관련 파일만 로드한다
+ 스킬은 필요한 정보와 실행 코드를 다음 시점에 불러온다.
- ```
- cloud-deploy/
- ├── SKILL.md (워크플로우 + 선택 가이드)
- └── references/
- ├── aws.md ← AWS 선택 시만 로드
- ├── gcp.md
- └── azure.md
- ```
+ | 정보 | 불러오는 시점 | 권장 분량 |
+ | --- | --- | --- |
+ | **메타데이터**(`name`, `description`) | 항상 | 약 100단어 |
+ | **`SKILL.md` 본문** | 스킬을 불러올 때 | 500줄 미만 |
+ | **`references/`** | 해당 자료가 필요할 때 | 제한 없음 |
+ | **`scripts/`** | 반복 작업이나 결과가 항상 같아야 하는 작업을 실행할 때 | 제한 없음. 내용을 읽지 않고 바로 실행할 수 있음 |
- #### 4-5. 스킬-에이전트 연결 원칙
+ - `SKILL.md`가 500줄에 가까워지면 세부 내용을 `references/`로 옮기고, 본문에는 언제 어떤 파일을 읽을지 적는다.
+ - 참조 문서가 300줄을 넘으면 문서 위쪽에 목차를 넣는다.
+ - 분야나 프레임워크마다 지침이 다르면 참조 문서를 나눠 필요한 파일만 읽게 한다.
- - 에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다)
- - 여러 에이전트가 공유하는 스킬도 가능
- - 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다
+ #### 4-5. 에이전트와 스킬 연결
- > 상세 작성 패턴, 예시, 데이터 스키마 표준은 `references/skill-writing-guide.md` 참조.
+ - 에이전트 한 명이 스킬 한 개 이상을 사용할 수 있다.
+ - 여러 에이전트가 같은 스킬을 공유할 수 있다.
+ - 스킬에는 일하는 방법을, 에이전트에는 그 일을 맡는 역할을 적는다.
- ### Phase 5: 통합 및 오케스트레이션
+ ### 5단계: 통합하고 실행 순서 정하기
- 오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 `references/orchestrator-template.md` 참조.
+ 오케스트레이터도 스킬이다. 개별 에이전트와 스킬을 하나의 작업 흐름으로 묶고, 누가 언제 어떤 순서로 협업하는지 정한다. 모드별 전체 템플릿은 `references/orchestrator-template.md`, 워크플로 스크립트 예시는 `references/workflow-recipes.md`에 있다.
- **기존 확장 시 오케스트레이터 수정:** 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다.
+ 기존 하네스를 확장할 때는 오케스트레이터를 새로 만들지 말고 기존 파일을 고친다. 에이전트를 추가하면 구성, 작업 배정, 데이터 전달 순서에 반영하고 `description`에도 새 호출 조건을 넣는다.
- Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다:
+ #### 5-0. 실행 모드별 오케스트레이터
- #### 5-0. 오케스트레이터 패턴 (모드별)
+ **A. 워크플로 조율**
- **에이전트 팀 패턴 (기본):**
- 오케스트레이터가 `TeamCreate`로 팀을 구성하고, `TaskCreate`로 작업을 할당한다. 팀원들은 `SendMessage`로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.
+ 오케스트레이터 스킬에 `Workflow` 스크립트를 정의한다. 스크립트는 `meta`, `phase()`, `pipeline()`, `parallel()`, `agent()`로 구성한다. 사용자 정의 유형은 `agentType`으로 지정하고, 스키마에 맞춘 결과는 `schema`로 받는다.
```
- [오케스트레이터/리더]
- ├── TeamCreate(team_name, members)
- ├── TaskCreate(tasks with dependencies)
- ├── 팀원들이 자체 조율 (SendMessage)
- ├── 결과 수집 및 종합
- └── 팀 정리
+ [오케스트레이터 스킬] → Workflow(script)
+ ├── phase('수집'): pipeline(items, ...) ← 미리 정한 목록을 분산 처리
+ ├── phase('검증'): 적대적 검증 또는 심사위원단
+ └── return 구조화된 결과 → 메인이 종합 보고서 작성
```
- **서브 에이전트 패턴 (대안):**
- 오케스트레이터가 `Agent` 도구로 서브 에이전트를 직접 호출한다. 병렬 실행은 `run_in_background: true`, 결과는 메인에게만 반환된다. 팀 통신이 불필요하고 오버헤드를 줄이고 싶을 때 사용.
+ **B. 지속형 에이전트 협업**
+ 이름 있는 에이전트를 실행한 뒤 공유 작업 목록과 `SendMessage`로 조율한다. `TeamCreate`와 `TeamDelete`는 더 이상 없다. 명시적인 팀 객체를 만들지 않으며, 세션에서 이름을 붙여 실행한 에이전트는 자동으로 구성되는 하나의 협업 그룹에 속한다. 해당 에이전트에는 이전 대화 맥락을 유지한 채 다시 메시지를 보낼 수 있다.
+
```
- [오케스트레이터]
- ├── Agent(agent-1, run_in_background=true)
- ├── Agent(agent-2, run_in_background=true)
- ├── 결과 대기 및 수집
- └── 통합 산출물 생성
+ [메인 에이전트(리더)]
+ ├── Agent(name: "researcher", ...) / Agent(name: "critic", ...) ← 병렬 실행
+ ├── TaskCreate(작업 + 의존 관계)
+ ├── SendMessage({to: "critic"}, "researcher의 초안을 검토하라")
+ └── 결과 수집 및 종합
```
- **하이브리드 패턴:**
- Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
- - **병렬 수집(서브) → 합의 통합(팀)**: Phase 2에서 서브 에이전트로 독립 자료를 병렬 수집 → Phase 3에서 팀을 만들어 토론·합의 기반 통합
- - **팀 생성(팀) → 검증(서브)**: Phase 2에서 팀이 초안 생성 → Phase 3에서 단일 서브 에이전트가 독립 검증
- - **Phase 간 팀 재구성**: 각 Phase마다 `TeamDelete` 후 새 `TeamCreate`, 사이에 서브 에이전트 호출 삽입
+ **C. 서브에이전트 위임**
- 하이브리드 선택 시 오케스트레이터의 각 Phase 섹션 상단에 해당 Phase의 실행 모드를 명시한다 (예: `**실행 모드:** 에이전트 팀`).
+ 메시지 한 번에 `Agent` 도구를 N번 병렬로 호출하고 완료 알림에서 결과를 모은다. 호출한 에이전트는 기본적으로 백그라운드에서 실행된다.
- #### 5-1. 데이터 전달 프로토콜
+ 단계마다 작업 성격이 다르면 혼합 모드로 구성할 수 있다. 예를 들어 워크플로로 자료를 모은 뒤 지속형 에이전트가 합의해 통합하거나, 지속형 에이전트가 만든 결과를 워크플로로 적대적 검증할 수 있다. 각 단계 위에 `**실행 모드:**`를 적는다.
- 오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:
+ #### 5-1. 데이터 전달 방법
- | 전략 | 방식 | 적용 모드 | 적합한 경우 |
- |------|------|----------|-----------|
- | **메시지 기반** | `SendMessage`로 팀원 간 직접 통신 | 팀 | 실시간 조율, 피드백 교환, 가벼운 상태 전달 |
- | **태스크 기반** | `TaskCreate`/`TaskUpdate`로 작업 상태 공유 | 팀 | 진행상황 추적, 의존 관계 관리, 작업 자체 요청 |
- | **파일 기반** | 약속된 경로에 파일을 쓰고 읽음 | 팀 + 서브 | 대용량 데이터, 구조화된 산출물, 감사 추적 필요 |
- | **반환값 기반** | `Agent` 도구의 반환 메시지 | 서브 | 서브 에이전트 결과를 메인이 직접 수집 |
+ | 방법 | 구현 | 알맞은 실행 모드 | 사용할 때 |
+ | --- | --- | --- | --- |
+ | **구조화된 반환값** | `Workflow`의 `agent(prompt, {schema})`가 검증된 JSON 반환 | 워크플로 조율 | 다음 단계가 결과를 코드로 처리해야 할 때 |
+ | **일반 반환값** | `Agent` 도구의 반환 메시지 | 서브에이전트 | 메인이 요약 결과를 직접 모을 때 |
+ | **메시지** | `SendMessage`로 에이전트끼리 직접 전달 | 지속형 에이전트 | 실시간 조율과 피드백이 필요할 때 |
+ | **공유 작업 목록** | `TaskCreate`, `TaskUpdate`로 상태 공유 | 지속형 에이전트 | 진행 상황, 의존 관계, 동적 배정을 관리할 때 |
+ | **파일** | 정해 둔 경로에 쓰고 읽기 | 모든 모드 | 데이터가 크거나 나중에 작업 과정을 확인해야 할 때 |
- **권장 조합 (팀 모드):** 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통)
- **권장 조합 (서브 모드):** 반환값 기반(결과 수집) + 파일 기반(대용량 산출물)
- **하이브리드:** 각 Phase의 실행 모드에 맞춰 해당 조합 적용
+ 파일로 전달할 때는 다음 규칙을 지킨다.
- 파일 기반 전달 시 규칙:
- - 작업 디렉토리 하위에 `_workspace/` 폴더를 만들어 중간 산출물 저장
- - 파일명 컨벤션: `{phase}_{agent}_{artifact}.{ext}` (예: `01_analyst_requirements.md`)
- - 최종 산출물만 사용자 지정 경로에 출력, 중간 파일(`_workspace/`)은 보존 (사후 검증·감사 추적용)
+ - 작업 디렉터리 아래 `_workspace/`에 중간 산출물을 저장한다.
+ - 파일 이름은 `{phase}_{agent}_{artifact}.{ext}` 형식을 쓴다. 예: `01_analyst_requirements.md`
+ - 최종 산출물만 사용자가 지정한 경로에 저장한다. `_workspace/`는 사후 검증을 위해 남긴다.
- #### 5-2. 에러 핸들링
+ #### 5-2. 오류 처리
- 오케스트레이터 내에 에러 처리 방침을 포함한다. 핵심 원칙: 1회 재시도 후 재실패 시 해당 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제하지 않고 출처 병기.
+ 오케스트레이터에 오류 처리 방침을 넣는다.
- > 에러 유형별 전략표와 구현 상세는 `references/orchestrator-template.md`의 "에러 핸들링" 참조.
+ - 한 번 다시 시도하고 또 실패하면 해당 결과 없이 진행하되, 최종 보고서에 누락 사실을 적는다. 서로 충돌하는 데이터는 지우지 말고 출처와 함께 남긴다.
+ - 다만 사용량 한도 소진, 인증 만료, 권한 거부처럼 다시 시도해도 결과가 같은 실패는 다시 시도하지 않는다. 다시 시도하면 남은 한도만 쓴다. 부분 산출물을 직접 열어 실제로 어디까지 진행됐는지 확인하고, 누락 내용을 파일로 기록한 뒤 사용자에게 보고한다. 사용량 한도라면 한도가 풀리는 시각도 함께 알린다.
+ - 멈춘 에이전트가 남긴 빈 곳을 오케스트레이터가 메울 때는 직접 확인한 사실만 대신 반영한다. 에이전트의 판단(예: 어떤 자료를 왜 제외했는지)은 추측해 채우지 않는다. 추측으로 채우면 사후 검증에 쓸 기록을 위조하는 셈이다.
+ - 워크플로에서 실패하거나 건너뛴 `agent()`는 `null`을 반환하고 `parallel()`은 실패를 예외로 던지지 않는다. 결과 배열에 `.filter(Boolean)`을 적용하고 빠진 항목 수를 `log()`로 알려야 한다.
+ - 지속형 에이전트가 응답하지 않으면 `SendMessage`로 상태를 확인하고 다시 지시한다. 그래도 실패하면 같은 사용자 정의 유형을 새 이름으로 실행하고, 필요한 작업 맥락을 프롬프트로 넘긴다.
- #### 5-3. 팀 크기 가이드라인
+ > 오류 유형별 대응 방법은 `references/orchestrator-template.md`에서 해당 실행 모드 템플릿의 「오류 처리」를 확인한다.
- | 작업 규모 | 권장 팀원 수 | 팀원당 작업 수 |
- |----------|------------|--------------|
- | 소규모 (5~10개 작업) | 2~3명 | 3~5개 |
- | 중규모 (10~20개 작업) | 3~5명 | 4~6개 |
- | 대규모 (20개+ 작업) | 5~7명 | 4~5개 |
+ #### 5-3. 작업 규모
- > 팀원이 많을수록 조율 오버헤드가 커진다. 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다.
+ | 작업 규모 | 지속형 에이전트 수 | 워크플로의 `Agent` 호출 규모 |
+ | --- | --- | --- |
+ | 소규모: 작업 10개 미만 | 2~3명 | 2~5건 |
+ | 중규모: 작업 10~20개 | 3~5명 | 약 10건. 동시 실행 상한을 넘으면 자동 대기 |
+ | 대규모: 작업 20개 초과 | 감독자 + 작업자 3~5명 | 수십~수백 건. 전체 상한 1,000건 |
- #### 5-4. CLAUDE.md 하네스 포인터 등록
+ - 에이전트가 많아질수록 관리 비용도 늘어난다. 기본 규모를 작게 유지한다.
+ - 사용자가 `+500k`처럼 토큰 예산을 지정하면 워크플로 스크립트에서 `budget.remaining()`을 확인해 실행 규모를 조절한다.
- 하네스 구성 완료 후, 프로젝트의 `CLAUDE.md`에 최소한의 포인터를 등록한다. CLAUDE.md는 새 세션마다 로딩되므로, 하네스 존재와 트리거 규칙만 기록하면 오케스트레이터 스킬이 나머지를 처리한다.
+ #### 5-4. `CLAUDE.md`에 하네스 연결 정보 기록
- **CLAUDE.md 템플릿:**
+ 구성을 마치면 프로젝트의 `CLAUDE.md`에 하네스가 있다는 사실과 호출 조건을 기록한다. `CLAUDE.md`는 새 세션마다 읽히므로 자세한 실행 규칙을 반복해서 넣지 않는다.
````markdown
## 하네스: {도메인명}
**목표:** {하네스의 핵심 목표 한 줄}
- **트리거:** {도메인} 관련 작업 요청 시 `{orchestrator-skill-name}` 스킬을 사용하라. 단순 질문은 직접 응답 가능.
+ **호출 조건:** {도메인} 관련 작업을 요청받으면 `{orchestrator-skill-name}` 스킬을 사용한다. 단순 질문에는 직접 답해도 된다.
**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
- |------|----------|------|------|
- | {YYYY-MM-DD} | 초기 구성 | 전체 | - |
+ | --- | --- | --- | --- |
+ | {YYYY-MM-DD} | Harness v2로 처음 구성 | 전체 | - |
````
- **CLAUDE.md에 넣지 않는 것:** 에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. 이유: 에이전트/스킬 목록은 오케스트레이터 스킬과 `.claude/agents/`, `.claude/skills/`에서 관리하므로 중복이다. 디렉토리 구조는 파일 시스템에서 직접 확인 가능하다. CLAUDE.md는 **포인터(트리거 규칙) + 변경 이력**만 담는다.
-
- #### 5-5. 후속 작업 지원
-
- 오케스트레이터는 초기 실행뿐 아니라 후속 작업도 처리해야 한다. 다음 세 가지를 보장하라:
-
- **1. 오케스트레이터 description에 후속 키워드 포함:**
- 초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현:
- - "다시 실행", "재실행", "업데이트", "수정", "보완"
- - "{도메인}의 {부분작업}만 다시"
- - "이전 결과 기반으로", "결과 개선"
+ 에이전트·스킬 목록, 디렉터리 구조, 자세한 실행 규칙은 넣지 않는다. 이 정보는 오케스트레이터 스킬과 `.claude/agents/`, `.claude/skills/`에서 관리한다. `CLAUDE.md`에는 호출 조건과 변경 이력만 둔다.
- **2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가:**
- 워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:
- - `_workspace/` 존재 + 사용자가 부분 수정 요청 → **부분 재실행** (해당 에이전트만 재호출)
- - `_workspace/` 존재 + 사용자가 새 입력 제공 → **새 실행** (기존 _workspace를 `_workspace_prev/`로 이동)
- - `_workspace/` 미존재 → **초기 실행**
+ #### 5-5. 후속 요청 처리
- **3. 에이전트 정의에 재호출 지침 포함:**
- 각 에이전트 `.md` 파일에 "이전 산출물이 있을 때의 행동"을 명시한다:
- - 이전 결과 파일이 존재하면 읽고 개선점을 반영
- - 사용자 피드백이 주어지면 해당 부분만 수정
+ 오케스트레이터는 처음 실행할 때뿐 아니라 결과를 다시 고칠 때도 작동해야 한다.
- > 오케스트레이터 템플릿의 "Phase 0: 컨텍스트 확인" 섹션 참조: `references/orchestrator-template.md`
+ 1. `description`에 `다시 실행`, `재실행`, `업데이트`, `수정`, `보완`, `{도메인}의 {부분 작업}만 다시`, `이전 결과를 바탕으로`, `결과 개선` 같은 표현을 넣는다.
+ 2. 오케스트레이터의 0단계에서 기존 작업 맥락을 확인한다.
+ - `_workspace/`가 있고 일부만 고쳐 달라는 요청이면 해당 단계나 에이전트만 다시 실행한다.
+ - `_workspace/`가 있고 새 입력을 받았으면 기존 디렉터리를 타임스탬프가 붙은 디렉터리로 옮긴 뒤 새로 실행한다.
+ - `_workspace/`가 없으면 처음부터 실행한다.
+ - 워크플로의 직전 `runId`가 있으면 `resumeFromRunId`로 재개할 수 있다. 바뀌지 않은 `agent()` 호출은 캐시 결과를 사용한다.
+ 3. 에이전트 정의에 재호출 방법을 적는다. 이전 결과 파일이 있으면 읽고, 사용자 피드백이 있으면 해당 부분만 고친다.
- ### Phase 6: 검증 및 테스트
+ ### 6단계: 검증과 테스트
- 생성된 하네스를 검증한다. 상세 테스트 방법론은 `references/skill-testing-guide.md` 참조.
+ 생성한 하네스를 검증한다. 자세한 방법은 `references/skill-testing-guide.md`를 따른다.
- #### 6-1. 구조 검증
+ #### 6-1. 파일과 참조 검증
- - 모든 에이전트 파일이 올바른 위치에 있는지 확인
- - 스킬의 frontmatter(name, description) 검증
- - 에이전트 간 참조 일관성 확인
- - 커맨드가 생성되지 않았는지 확인
+ - 모든 에이전트 파일이 올바른 위치에 있는지 확인한다.
+ - 스킬의 YAML 프론트매터에 `name`과 `description`이 있는지 확인한다.
+ - 에이전트끼리 서로 참조하는 이름이 일치하는지 확인한다.
+ - `.claude/commands/`에 명령 파일을 만들지 않았는지 확인한다.
+ - 산출물에 v1 방식인 `TeamCreate`, `TeamDelete`, `team_name`, 실험 기능 플래그가 남지 않았는지 확인한다.
#### 6-2. 실행 모드별 검증
- - **에이전트 팀**: 팀원 간 통신 경로, 작업 의존성, 팀 크기 적정성 확인
- - **서브 에이전트**: 각 에이전트의 입출력 연결, `run_in_background` 설정, 반환값 수집 로직 확인
- - **하이브리드**: 각 Phase의 실행 모드가 오케스트레이터에 명시되었는지, Phase 경계에서 데이터 전달이 끊기지 않는지 확인 (팀 → 서브 전환 시 팀의 산출물이 서브의 입력으로 연결되는지)
+ - **워크플로 조율**: `meta`가 값만 담은 리터럴인지, `Date.now()`와 `Math.random()`을 쓰지 않았는지, 전체 결과를 기다려야 할 때만 `parallel()`을 썼는지, `.filter(Boolean)`이 빠지지 않았는지, `phase()` 제목이 `meta.phases`와 일치하는지 확인한다.
+ - **지속형 에이전트 협업**: `SendMessage`의 발신·수신 경로, 작업 의존 관계, 에이전트 수를 확인한다.
+ - **서브에이전트 위임**: 각 에이전트의 입력과 출력이 이어지는지, 병렬 호출을 메시지 한 번에 묶었는지, 결과를 빠짐없이 모으는지 확인한다.
+ - **혼합 모드**: 각 단계에 실행 모드를 적었는지, 단계가 바뀔 때 데이터가 끊기지 않는지 확인한다.
#### 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. 피드백 반영 경로
-
- 피드백 유형에 따라 수정 대상이 다르다:
+ 1. 스킬마다 실제 사용자가 입력할 법한 구체적인 테스트 요청을 2~3개 만든다.
+ 2. 스킬 적용 실행(With-skill)과 기준 실행(Baseline)을 병렬로 수행해 스킬이 결과를 얼마나 개선하는지 비교한다. 반복해야 하면 A/B 비교 자체를 워크플로로 만들 수 있다.
+ 3. 사용자가 직접 검토하는 정성 평가와 검증 조건(assertion)을 사용하는 정량 평가를 함께 쓴다. 객관적인 조건을 만들 수 없으면 사용자 판단을 따른다.
+ 4. 문제가 나오면 특정 예시만 막는 규칙을 넣지 말고 여러 상황에 적용할 수 있는 원리로 고친다. 다시 테스트하고, 더 고쳐도 얻는 효과가 거의 없을 때까지 반복한다.
+ 5. 여러 에이전트가 같은 코드를 반복해서 만들면 `scripts/`에 넣는다.
- | 피드백 유형 | 수정 대상 | 예시 |
- |-----------|----------|------|
- | 결과물 품질 | 해당 에이전트의 스킬 | "분석이 너무 피상적" → 스킬에 깊이 기준 추가 |
- | 에이전트 역할 | 에이전트 정의 `.md` | "보안 검토도 필요" → 새 에이전트 추가 |
- | 워크플로우 순서 | 오케스트레이터 스킬 | "검증을 먼저 해야" → Phase 순서 변경 |
- | 팀 구성 | 오케스트레이터 + 에이전트 | "이 둘은 합쳐도 될 듯" → 에이전트 병합 |
- | 트리거 누락 | 스킬 description | "이 표현으로 하면 작동 안 함" → description 확장 |
+ #### 6-4. 호출 조건 검증
- #### 7-3. 변경 이력
+ 1. 스킬을 불러와야 하는 요청을 서로 다른 말투와 명시 수준으로 10개 만든다.
+ 2. 표현은 비슷하지만 다른 스킬이나 도구를 써야 하는 경계 사례도 10개 만든다.
- 모든 변경은 CLAUDE.md의 **변경 이력** 테이블에 기록한다 (Phase 5-4 템플릿의 "변경 이력" 섹션과 동일 테이블):
+ 명백히 무관한 요청은 경계를 검증하지 못한다. 예를 들어 이미지 생성 스킬을 시험할 때 `피보나치 함수 작성`보다 `이 엑셀 파일의 차트를 PNG로 추출해 줘`가 더 좋은 경계 사례다. 결과는 이미지지만 실제로는 스프레드시트 도구가 더 알맞기 때문이다. 기존 스킬과 호출 조건이 겹치는지도 확인한다.
- ```markdown
- **변경 이력:**
- | 날짜 | 변경 내용 | 대상 | 사유 |
- |------|----------|------|------|
- | 2026-04-05 | 초기 구성 | 전체 | - |
- | 2026-04-07 | QA 에이전트 추가 | agents/qa.md | 산출물 품질 검증 부족 피드백 |
- | 2026-04-10 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 |
- ```
+ #### 6-5. 모의 실행
- 이 이력을 통해 하네스가 어떤 방향으로 진화했는지 추적하고, 퇴행(regression)을 방지한다.
+ - 오케스트레이터의 단계 순서가 논리적인지 확인한다.
+ - 데이터 전달 경로가 중간에 끊기지 않는지 확인한다.
+ - 모든 에이전트의 입력이 앞 단계의 출력과 맞는지 확인한다.
+ - 오류가 났을 때 대체 절차를 실제로 실행할 수 있는지 확인한다.
- #### 7-4. 진화 트리거
+ #### 6-6. 테스트 시나리오 기록
- 사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다:
- - 같은 유형의 피드백이 2회 이상 반복될 때
- - 에이전트가 반복적으로 실패하는 패턴이 발견될 때
- - 사용자가 오케스트레이터를 우회하여 수동으로 작업하는 것이 관찰될 때
+ 오케스트레이터 스킬에 `## 테스트 시나리오`를 만들고 정상 흐름 한 가지와 오류 흐름 한 가지 이상을 적는다.
- #### 7-5. 운영/유지보수 워크플로우
+ ### 7단계: 운영·유지 보수와 개선
- 기존 하네스의 점검·수정·동기화를 체계적으로 수행한다. Phase 0에서 "운영/유지보수" 분기로 진입했을 때 이 워크플로우를 따른다.
+ 하네스는 한 번 만들고 끝나는 산출물이 아니다.
- **Step 1: 현황 감사**
- - `.claude/agents/` 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성
- - `.claude/skills/` 디렉토리 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성
- - 감사 결과를 사용자에게 보고한다
+ 실행 결과를 회고하고 피드백을 반영하는 작업은 `harness:evolve` 스킬이 맡는다. 사용자가 `하네스 회고`, `하네스 진화`, `피드백 반영해줘`라고 요청하면 `harness:evolve`를 사용한다. 이 스킬은 처음 구성과 현재 상태의 차이를 분석하고, 여러 상황에 적용할 수 있도록 피드백을 정리해 에이전트·스킬·오케스트레이터에 반영한다. `CLAUDE.md` 변경 이력도 갱신한다.
- **Step 2: 점진적 추가/수정**
- - 사용자 요청에 따라 에이전트 추가/수정/삭제, 스킬 추가/수정/삭제를 수행한다
- - 변경은 한 번에 하나씩, 각 변경 후 즉시 Step 3(동기화)을 실행한다
+ 이 `harness` 스킬은 기존 하네스를 운영하고 유지 보수하는 다음 절차를 직접 처리한다.
- **Step 3: CLAUDE.md 변경 이력 갱신**
- - 변경 이력 테이블에 날짜, 변경 내용, 대상, 사유를 기록한다
+ 1. **현재 상태 점검**: `.claude/agents/`, `.claude/skills/`, 오케스트레이터 구성을 비교해 불일치 목록을 만들고 사용자에게 알린다.
+ 2. **조금씩 추가·수정**: 한 번에 한 항목만 바꾸고 곧바로 다음 검증을 실행한다.
+ 3. **변경 이력 기록**: `CLAUDE.md`에 날짜, 변경 내용, 대상, 사유를 적는다.
+ 4. **변경 검증**: 파일 구조를 확인한다. 호출 조건에 영향을 주면 호출 테스트도 한다. 변경 범위가 크면 실행 테스트와 모의 실행까지 한 뒤 `CLAUDE.md`와 실제 파일이 일치하는지 마지막으로 확인한다.
- **Step 4: 변경 검증**
- - 수정된 에이전트/스킬의 구조 검증 (Phase 6-1 기준)
- - 수정 범위가 트리거에 영향을 주면 트리거 검증 (Phase 6-4 기준)
- - 대규모 변경(아키텍처 변경, 에이전트 3개 이상 추가/삭제) 시 Phase 6-3(실행 테스트), 6-5(드라이런)까지 수행
- - CLAUDE.md와 실제 파일의 일치 여부 최종 확인
+ 다음 상황에서는 `harness:evolve`로 개선하자고 제안한다.
- ## 산출물 체크리스트
+ - 같은 종류의 피드백이 두 번 이상 나왔다.
+ - 에이전트가 같은 원인으로 반복해서 실패한다.
+ - 사용자가 오케스트레이터를 거치지 않고 같은 작업을 계속 수동으로 처리한다.
- 생성 완료 후 확인:
+ ## 산출물 점검표
- - [ ] `프로젝트/.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에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별)
+ - [ ] `프로젝트/.claude/agents/`에 재사용할 모든 사용자 정의 유형의 파일을 만들었다. 단발 작업에 기본 제공 유형을 그대로 쓰는 경우는 제외했다.
+ - [ ] `프로젝트/.claude/skills/`에 필요한 `SKILL.md`와 참조 문서를 만들었다.
+ - [ ] 오케스트레이터 스킬 한 개에 데이터 전달 방법, 오류 처리, 테스트 시나리오를 넣었다.
+ - [ ] 워크플로 조율, 지속형 에이전트, 서브에이전트 가운데 사용할 실행 모드를 적었다. 혼합 모드라면 단계마다 표시했다.
+ - [ ] 에이전트별 `model:`을 복잡도, 작업 기간, 자율성, 응답 속도에 따라 골랐고 이유를 주석으로 남겼다. 모든 에이전트에 같은 고성능 모델을 일괄 지정하지 않았다.
+ - [ ] 산출물에 `TeamCreate`, `TeamDelete`, 실험 기능 플래그 같은 v1 방식이 남지 않았다.
+ - [ ] 워크플로 스크립트에 `.filter(Boolean)`을 넣고 `meta`에는 리터럴만 썼다. 꼭 필요할 때만 `parallel()`로 전체 결과를 기다린다.
+ - [ ] `.claude/commands/`에 파일을 만들지 않았다.
+ - [ ] 새 에이전트·스킬을 만들기 전에 기존 것과 역할이 겹치는지 확인했다. 도메인을 의도적으로 특화한 경우가 아니면 겹치는 것은 기존 것을 쓰거나 확장했고, 이름이나 역할이 충돌하지 않는다.
+ - [ ] 에이전트 정의, 스킬, 오케스트레이터, `CLAUDE.md` 기록을 사용자가 대화에 쓰는 언어로 작성했다. 사용자가 따로 정한 언어나 기존 하네스 파일의 언어가 있으면 그 언어를 따랐다.
+ - [ ] 스킬 `description`에 해야 할 일과 호출 조건을 구체적으로 적고 후속 요청 표현도 넣었다.
+ - [ ] `SKILL.md` 본문이 500줄 미만이다. 500줄 이상이면 세부 내용을 `references/`로 옮겼다.
+ - [ ] 실제 요청과 비슷한 테스트 문장 2~3개로 실행했다.
+ - [ ] 스킬을 불러와야 하는 요청과 불러오면 안 되는 경계 사례로 호출 조건을 검증했다.
+ - [ ] `CLAUDE.md`에 호출 조건과 변경 이력만 기록했다.
+ - [ ] 오케스트레이터의 0단계에서 처음 실행, 후속 실행, 일부 재실행을 구분한다. 워크플로는 재개 옵션도 다룬다.
- ## 참고
+ ## 참고 문서
- - 하네스 패턴: `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개 버그 사례 기반.
+ - **실행 모드 상세**: `references/execution-modes.md`
+ - **모델 선택 가이드**: `references/model-selection-guide.md`
+ - **팀 구성 방식과 에이전트 정의**: `references/team-patterns.md`
+ - **실전 팀 구성 예시**: `references/team-examples.md`
+ - **워크플로 스크립트 예시와 주의 사항**: `references/workflow-recipes.md`
+ - **오케스트레이터 템플릿**: `references/orchestrator-template.md`
+ - **스킬 작성 가이드**: `references/skill-writing-guide.md`
+ - **스킬 테스트 가이드**: `references/skill-testing-guide.md`
+ - **QA 에이전트 가이드**: `references/qa-agent-guide.md`