harness

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-0 포함)	전용 스킬 필요 시 (4-0 포함)	오케스트레이터 수정	필수
   스킬 추가/수정	건너뜀	건너뜀	건너뜀	필수 (4-0 포함)	연결 변경 시	필수
   아키텍처 변경	건너뜀	필수	영향받는 에이전트만 (3-0 포함)	영향받는 스킬만 (4-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-0에서 다룬다.

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

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

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

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

모든 서브에이전트는 반드시 프로젝트/.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-0. 기존 스킬 중복 검토

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

중복 분류 기준과 일반화 패턴은 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 템플릿:

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

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

**트리거:** {도메인} 관련 작업 요청 시 `{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 템플릿의 "변경 이력" 섹션과 동일 테이블):

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 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 기반 서브에이전트 / 병렬 서브에이전트 / 직접 실행 중 선택)
• 기존 에이전트/스킬과 충돌 없음
• 신규 서브에이전트 생성 전 기존 서브에이전트 중복 검토 완료 (Phase 3-0)
• 신규 스킬 생성 전 기존 스킬 중복 검토 완료 (Phase 4-0)
• 작성 언어(한국어/영어) 일관성 및 다국어 대응 규칙 준수 (영문 요청 시 모든 에이전트/스킬 정의 및 오케스트레이터 텍스트 영어 작성)
• 스킬 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 에이전트를 포함할 때 참조.