semillero-special-hotel/.agents/plugins/harness-plugin/skills/harness/SKILL.md

---
name: harness
description: "하네스를 구성합니다. 전문 서브에이전트 정의(agent.json)와 스킬(SKILL.md)을 플러그인 형태로 생성하는 메타 스킬. (1) '하네스 구성해줘', '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링' 요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화 체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때, (5) '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 등 기존 하네스 운영/유지보수 요청 시 사용."
---

# Harness — Agent Team & Skill Architect for Antigravity CLI

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

**핵심 원칙:**
1. **플러그인 구조로 패키징한다.** — 서브에이전트 정의(`.agents/plugins/{domain}-plugin/agents/{name}/agent.json`)와 스킬(`.agents/plugins/{domain}-plugin/skills/{name}/SKILL.md`)을 하나의 플러그인 폴더에 묶어 생성한다.
2. **`invoke_subagent` 도구를 기본 실행 모드로 사용한다.** — Antigravity CLI의 서브에이전트 위임 메커니즘(`invoke_subagent` 호출 및 `send_message`를 통한 협업)을 활용한다.
3. **AGENTS.md에 하네스 포인터를 등록한다.** — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다.
4. **하네스는 고정물이 아니라 진화하는 시스템이다.** — 매 실행 후 피드백을 반영하고, 에이전트·스킬·AGENTS.md를 지속 갱신한다.
5. **사용자 요청 언어 및 컨텍스트에 맞게 작성 언어를 결정한다.** — 사용자가 영어로 요청을 하거나, 프로젝트의 글로벌 협업 환경, 코드베이스 주석/문서 표준이 영어인 경우, 새로 생성하는 서브에이전트(`agent.json`의 `description` 및 `systemPromptSections` 등), 스킬(`SKILL.md` 본문 및 YAML frontmatter `description` 등), 그리고 오케스트레이터의 모든 텍스트를 영문(English)으로 작성한다.

## 워크플로우

### Phase 0: 현황 감사

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

1. `프로젝트/.agents/plugins/`, `프로젝트/AGENTS.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. 기존 에이전트/스킬 목록과 AGENTS.md 기록을 대조하여 불일치(drift)를 감지한다.
4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다.

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

### Phase 2: 팀 아키텍처 설계

#### 2-1. 실행 모드 선택

**서브에이전트가 기본 실행 모드이다.** 2개 이상의 에이전트가 협업할 때는 Antigravity CLI 서브에이전트를 통해 위임한다. 메인 에이전트가 오케스트레이터 역할을 하며, 각 서브에이전트는 `invoke_subagent` 도구 호출로 생성된 독립적인 컨텍스트에서 작업을 수행하고 결과를 반환한다.

| 모드 | 언제 사용 | 특성 |
|------|----------|------|
| **서브에이전트** (기본) | 2명 이상 협업, 각 에이전트가 독립 컨텍스트에서 작업 | `invoke_subagent` 위임, 파일 기반 결과 공유 |
| **직접 실행** (대안) | 단순 작업, 에이전트 분리가 오버헤드일 때 | 별도 에이전트 없이 메인이 직접 처리 |
| **병렬 서브에이전트** | 독립적인 작업을 동시에 처리 | `invoke_subagent`를 통해 여러 서브에이전트를 동시에 실행하여 결과 수집 |

**의사결정 순서:**
1. 먼저 서브에이전트로 분리 가능한 작업 영역을 식별한다 — 2개 이상의 전문 영역이면 기본값
2. 병렬 실행이 가능한 독립 작업이면 병렬 서브에이전트 고려
3. 단순하고 일회성인 작업은 직접 실행

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

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

1. 작업을 전문 영역으로 분해
2. 서브에이전트 팀 구조 결정 (아키텍처 패턴은 `rules/agent-design-patterns.md` 참조)
   - **파이프라인**: 순차 의존 작업 (서브에이전트 체인)
   - **팬아웃/팬인**: 병렬 독립 작업 (병렬 서브에이전트)
   - **전문가 풀**: 상황별 선택 호출 (조건부 서브에이전트)
   - **생성-검증**: 생성 후 품질 검수 (서브에이전트 루프)
   - **감독자**: 중앙 에이전트가 상태 관리 및 동적 분배 (메인 → 서브)
   - **계층적 위임**: 상위 에이전트가 하위에 재귀적 위임 (서브에이전트 체인)

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

전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 `rules/agent-design-patterns.md`의 "에이전트 분리 기준" 참조.

### Phase 3: 서브에이전트 정의 생성

**모든 서브에이전트는 반드시 `프로젝트/.agents/plugins/{domain}-plugin/agents/{name}/agent.json` 파일로 정의한다.**
서브에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능하며, 역할과 작업 원칙이 명시되어야 협업 품질이 보장된다.

각 서브에이전트의 `agent.json` 필수 구성 요소:
- `name`: 에이전트 이름 (TypeName으로 매핑됨)
- `description`: 사용자가 이 에이전트의 정체성을 한눈에 파악할 수 있는 요약
- `config.customAgent.systemPromptSections`: 에이전트의 구체적 instructions를 섹션 단위로 명시 (핵심 역할, 작업 원칙, 입출력 프로토콜 포함)
- `config.customAgent.toolNames`: 에이전트가 활용할 권장 도구 세트
- `config.customAgent.systemPromptConfig.includeSections`: Antigravity CLI가 제공할 시스템 프롬프트 섹션 목록
- **언어 일관성**: Phase 1에서 결정된 작성 언어(한국어 또는 영어)에 맞게 `description`과 `systemPromptSections` 내부의 system prompt를 일관되게 작성한다. 영어 프로젝트 또는 영어 요청의 경우, 모든 프롬프트와 설명을 자연스러운 영문(Technical English)으로 작성해야 한다.

> 정의 구조와 실제 파일 전문은 `rules/agent-design-patterns.md`의 "서브에이전트 정의 구조" + `rules/team-examples.md` 참조.

**QA 에이전트 포함 시 필수 사항:**
- QA 에이전트는 전체 도구 접근이 필요하므로 읽기 전용 제한을 두지 않는다.
- QA의 핵심은 "존재 확인"이 아니라 **"경계면 교차 비교"** — API 응답과 프론트 훅을 동시에 읽고 shape을 비교.
- QA는 전체 완성 후 1회가 아니라, **각 모듈 완성 직후 점진적으로 실행** (incremental QA).
- 상세 가이드: `rules/qa-agent-guide.md` 참조.

### Phase 4: 스킬 생성

각 서브에이전트가 사용할 스킬을 `프로젝트/.agents/plugins/{domain}-plugin/skills/{name}/SKILL.md`에 생성한다. 상세 작성 가이드는 `rules/skill-writing-guide.md` 참조.

#### 4-1. 스킬 구조

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

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

description은 스킬의 유일한 트리거 메커니즘이다. Antigravity CLI는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정하므로, description을 **적극적("pushy")**으로 작성한다.

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

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

#### 4-3. 본문 작성 원칙

| 원칙 | 설명 |
|------|------|
| **Why를 설명하라** | "ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. |
| **Lean하게 유지** | 컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 rules/로 이동한다. |
| **일반화하라** | 특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지. |
| **반복 코드는 번들링** | 테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 `scripts/`에 미리 번들링한다. |
| **명령형으로 작성** | "~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다. |
| **언어 일관성** | 감지된 언어(한국어/영어)를 일관되게 사용한다. 영문 요청/글로벌 프로젝트의 경우, YAML frontmatter description과 스킬 본문 전체를 완벽한 영어로 작성하며, 설명이 번역기 톤이 아닌 자연스러운 기술 문서 톤이 되도록 한다. |

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

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

| 단계 | 로딩 시점 | 크기 목표 |
|------|----------|----------|
| **Metadata** (name + description) | 항상 컨텍스트에 존재 | ~100단어 |
| **SKILL.md 본문** | 스킬 트리거 시 | <500줄 |
| **rules/** | 필요할 때만 | 무제한 (스크립트는 로딩 없이 실행 가능) |

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

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

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

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

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

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

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

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

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

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

**서브에이전트 패턴 (기본):**
메인 에이전트(오케스트레이터)가 서브에이전트를 `invoke_subagent` 도구 호출로 실행한다. 각 서브에이전트는 독립적인 컨텍스트에서 작업을 수행하고, 결과를 메인에게 반환한다. 파일 기반으로 중간 산출물을 공유한다.

```
[오케스트레이터/메인]
    ├── invoke_subagent(TypeName: "analyst") ──→ _workspace/02_analysis.md
    ├── invoke_subagent(TypeName: "builder") ──→ _workspace/03_build.md
    ├── invoke_subagent(TypeName: "qa") ──────→ _workspace/04_qa_report.md
    └── 결과 수집 및 통합
```

**병렬 서브에이전트 패턴:**
독립적인 작업을 동시에 실행한다. `invoke_subagent`를 통해 여러 에이전트를 순차적으로 호출하여 모두 백그라운드로 보낸 뒤, 모든 결과가 수집될 때까지 대기하고 수집 후 통합한다.

```
[오케스트레이터/메인]
    ├── invoke_subagent(TypeName: "researcher-a") ──→ _workspace/02_research_a.md
    ├── invoke_subagent(TypeName: "researcher-b") ──→ _workspace/02_research_b.md
    ├── invoke_subagent(TypeName: "researcher-c") ──→ _workspace/02_research_c.md
    └── 모든 결과 통합 → 최종 산출물
```

**직접 실행 패턴 (대안):**
단순 작업은 별도 서브에이전트 없이 메인이 직접 처리한다. 서브에이전트 생성 오버헤드가 작업 자체보다 클 때 사용.

```
[메인]
    └── 직접 실행 (도구 호출)
```

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

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

| 전략 | 방식 | 적합한 경우 |
|------|------|-----------|
| **파일 기반** | 약속된 경로에 파일을 쓰고 읽음 | 대용량 데이터, 구조화된 산출물, 감사 추적 필요 |
| **반환값 기반** | 서브에이전트 실행 결과 메시지 활용 | 경량 결과, 간단한 상태 전달 |
| **AGENTS.md 공유** | 프로젝트 AGENTS.md에 컨텍스트 기록 | 장기 보존이 필요한 설정 정보 |

**권장 조합:** 파일 기반(주 산출물) + 반환값 기반(상태 전달)

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

#### 5-2. 에러 핸들링

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

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

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

| 작업 규모 | 권장 서브에이전트 수 | 에이전트당 작업 수 |
|----------|-------------------|--------------|
| 소규모 (5~10개 작업) | 2~3명 | 3~5개 |
| 중규모 (10~20개 작업) | 3~5명 | 4~6개 |
| 대규모 (20개+ 작업) | 5~7명 | 4~5개 |

> 서브에이전트가 많을수록 메인의 조율 부담이 커진다. 3명의 집중된 팀이 5명의 산만한 팀보다 낫다.

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

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

**AGENTS.md 템플릿:**

```markdown
## 하네스: {도메인명}

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

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

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| {YYYY-MM-DD} | 초기 구성 | 전체 | - |
```

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

#### 5-5. 후속 작업 지원

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

**1. 오케스트레이터 description에 후속 키워드 포함:**
초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현:
- "다시 실행", "재실행", "업데이트", "수정", "보완"
- "{도메인}의 {부분작업}만 다시"
- "이전 결과 기반으로", "결과 개선"

**2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가:**
워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:
- `_workspace/` 존재 + 사용자가 부분 수정 요청 → **부분 재실행** (해당 서브에이전트만 재호출)
- `_workspace/` 존재 + 사용자가 새 입력 제공 → **새 실행** (기존 _workspace를 `_workspace_prev/`로 이동)
- `_workspace/` 미존재 → **초기 실행**

**3. 서브에이전트 정의에 재호출 지침 포함:**
각 서브에이전트 `agent.json` 내의 systemPromptSections에 "이전 산출물이 있을 때의 행동"을 명시한다:
- 이전 결과 파일이 존재하면 읽고 개선점을 반영
- 사용자 피드백이 주어지면 해당 부분만 수정

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

### Phase 6: 검증 및 테스트

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

#### 6-1. 구조 검증

- 모든 서브에이전트 `agent.json` 파일이 올바른 위치에 있는지 확인
- 스킬의 frontmatter(name, description) 검증
- 서브에이전트 간 참조 일관성 확인

#### 6-2. 실행 모드별 검증

- **서브에이전트**: 각 에이전트의 입출력 연결, 파일 기반 데이터 흐름 확인
- **병렬 서브에이전트**: 독립성 보장 (동일 파일에 동시 쓰기 방지), 결과 수집 로직 확인
- **직접 실행**: 오케스트레이터가 불필요한 에이전트 분리를 하지 않았는지 확인

#### 6-3. 스킬 실행 테스트

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

1. **테스트 프롬프트 작성** — 각 스킬에 대해 2~3개의 현실적인 테스트 프롬프트를 작성한다. 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장으로 작성한다.
2. **With-skill vs Without-skill 비교 실행** — 가능하면 스킬 있는 실행과 없는 실행을 비교하여 스킬의 부가가치를 확인한다.
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. 피드백 반영 경로

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

| 피드백 유형 | 수정 대상 | 예시 |
|-----------|----------|------|
| 결과물 품질 | 해당 에이전트의 스킬 | "분석이 너무 피상적" → 스킬에 깊이 기준 추가 |
| 에이전트 역할 | 서브에이전트 정의 `agent.json` | "보안 검토도 필요" → 새 에이전트 추가 |
| 워크플로우 순서 | 오케스트레이터 스킬 | "검증을 먼저 해야" → Phase 순서 변경 |
| 팀 구성 | 오케스트레이터 + 에이전트 | "이 둘은 합쳐도 될 듯" → 에이전트 병합 |
| 트리거 누락 | 스킬 description | "이 표현으로 하면 작동 안 함" → description 확장 |

#### 7-3. 변경 이력

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

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

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

#### 7-4. 진화 트리거

사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다:
- 같은 유형의 피드백이 2회 이상 반복될 때
- 서브에이전트가 반복적으로 실패하는 패턴이 발견될 때
- 사용자가 오케스트레이터를 우회하여 수동으로 작업하는 것이 관찰될 때

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

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

**Step 1: 현황 감사**
- 플러그인 디렉토리(`agents/`) 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성
- 플러그인 디렉토리(`skills/`) 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성
- 감사 결과를 사용자에게 보고한다.

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

**Step 3: AGENTS.md 변경 이력 갱신**
- 변경 이력 테이블에 날짜, 변경 내용, 대상, 사유를 기록한다.

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

## 산출물 체크리스트

생성 완료 후 확인:

- [ ] `.agents/plugins/{domain}-plugin/plugin.json` — **플러그인 정의 파일 필수 생성**
- [ ] `.agents/plugins/{domain}-plugin/agents/{name}/agent.json` — **서브에이전트 정의 파일 필수 생성**
- [ ] `.agents/plugins/{domain}-plugin/skills/` — 스킬 파일들 (SKILL.md + rules/)
- [ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함)
- [ ] 실행 모드 명시 (invoke_subagent 기반 서브에이전트 / 병렬 서브에이전트 / 직접 실행 중 선택)
- [ ] 기존 에이전트/스킬과 충돌 없음
- [ ] **작성 언어(한국어/영어) 일관성 및 다국어 대응 규칙 준수** (영문 요청 시 모든 에이전트/스킬 정의 및 오케스트레이터 텍스트 영어 작성)
- [ ] 스킬 description이 적극적("pushy")으로 작성됨 — **후속 작업 키워드 포함**
- [ ] SKILL.md 본문이 500줄 이내, 초과 시 rules/ 분리
- [ ] 테스트 프롬프트 2~3개로 실행 검증 완료
- [ ] 트리거 검증 (should-trigger + should-NOT-trigger) 완료
- [ ] **AGENTS.md에 하네스 포인터 등록** (트리거 규칙 + 변경 이력)
- [ ] **AGENTS.md 변경 이력에 에이전트/스킬 추가/삭제/수정 기록**
- [ ] **오케스트레이터 Phase 1에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별)

## 참고

- 하네스 패턴: `rules/agent-design-patterns.md`
- 기존 하네스 예시 (실제 파일 전문 포함): `rules/team-examples.md`
- 오케스트레이터 템플릿: `rules/orchestrator-template.md`
- **스킬 작성 가이드**: `rules/skill-writing-guide.md` — 작성 패턴, 예시, 데이터 스키마 표준
- **스킬 테스트 가이드**: `rules/skill-testing-guide.md` — 테스트/평가/반복 개선 방법론
- **QA 에이전트 가이드**: `rules/qa-agent-guide.md` — 빌드 하네스에 QA 에이전트를 포함할 때 참조.