From myharness
Configures, expands, and audits agent teams and skills (harness) for Claude Code and Codex. Automates scaffolding of agent definitions, skill files, and runtime pointers for new projects or maintenance.
How this skill is triggered — by the user, by Claude, or both
Slash command
/myharness:myharnessThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**핵심 원칙:**
references/agent-design-patterns.mdreferences/dev-rules.mdreferences/external-review-loop.mdreferences/factory-map.mdreferences/loop-self-eval.mdreferences/orchestrator-template.mdreferences/qa-agent-guide.mdreferences/runtime-adapters.mdreferences/self-improvement-loop.mdreferences/skill-testing-guide.mdreferences/skill-writing-guide.mdreferences/tdd-doctrine.mdreferences/team-examples.mdscripts/build-scorecard.shscripts/check-review-tools.shscripts/run-policy-audit.sh핵심 원칙:
.claude/agents/)와 스킬(.claude/skills/)을 생성한다.references/external-review-loop.md.[[ ]]·플러그인 내부 경로 금지 — 서브에이전트가 해소 못 함). 상세: references/dev-rules.md, references/tdd-doctrine.md..claude/skills/ / .agents/skills/), 에이전트(.md / .codex/agents/*.toml), 오케스트레이션(TeamCreate / Codex subagents·subprocess). 생성 시 양쪽 출력. 상세·검증: references/runtime-adapters.md.팩토리가 커졌어도 기본은 슬림. 게이트·평가·자기개선은 리스크가 오를 때만 켠다(단순 하네스 강제 금지).
| 하네스 유형 | 반드시 | 생략 |
|---|---|---|
| 단순/비코드 · 코드 경량 | Phase 0~7 코어 + 내부 QA (dev-rules만 선택) | 외부 리뷰·TDD·평가·self-improve |
| 코드/설계 표준 | + 외부 리뷰 1회 + dev-rules·tdd 주입 | 자동 환류 |
| 코드/설계 중대 | + 단계마다 외부 리뷰 + 승인 사다리 + scorecard | 자동 채택(실험) |
최소 경로·구현 상태(active vs 🧪실험/📐설계만)·루프 개요 지도는
references/factory-map.md. 🧪/📐 기능은 생성 하네스가 자동 실행 안 함.
하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.
프로젝트/.claude/agents/·skills/·CLAUDE.md를 읽는다. 듀얼 런타임이면 AGENTS.md·.agents/skills/·.codex/agents/도 읽어 양쪽 drift 점검
현황에 따라 실행 모드를 분기한다:
기존 확장 시 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 포함) | 필수 | 필수 |
기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다
감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다
에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.
| 모드 | 언제 사용 | 특성 |
|---|---|---|
| 에이전트 팀 (기본) | 2명 이상 협업, 실시간 조율·피드백 교환이 필요, 중간 산출물 상호 참조 | TeamCreate + SendMessage + TaskCreate로 자체 조율 |
| 서브 에이전트 (대안) | 단일 에이전트 작업, 결과만 메인에 반환하면 충분, 팀 통신 오버헤드가 과할 때 | Agent 도구 직접 호출, run_in_background로 병렬 |
| 하이브리드 | Phase마다 특성이 다를 때 — 예: 병렬 수집(서브) → 합의 기반 통합(팀) | Phase 단위로 팀/서브를 섞어 구성 |
의사결정 순서:
상세 비교표와 패턴별 의사결정 트리는
references/agent-design-patterns.md의 "실행 모드" 참조.
references/agent-design-patterns.md 참조)
전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 references/agent-design-patterns.md의 "에이전트 분리 기준" 참조. 기존 에이전트와의 중복·재사용 검토는 Phase 3-0에서 다룬다.
듀얼 런타임: 아래
.claude/agents/*.md는 Claude 기준. Codex 동시 출력 시 같은 역할을.codex/agents/{name}.toml로도 생성한다 (references/runtime-adapters.md§3-4).
신규 에이전트 생성 전, 프로젝트/.claude/agents/의 기존 에이전트와 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 역할이 겹치는 에이전트가 다른 이름으로 누적되기 쉽다.
중복 분류 기준과 재사용 설계는
references/agent-design-patterns.md의 "에이전트 재사용 설계" 참조.
모든 에이전트는 반드시 프로젝트/.claude/agents/{name}.md 파일로 정의한다. 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:
빌트인 타입(general-purpose, Explore, Plan)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 subagent_type 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다.
모델 설정(라우팅 — 비용 통제): 설계·판정·구현 등 고추론 작업만 model: "opus"(Claude). 단순 작업(grep·구조 검증·트리거 eval·파일 감사)은 경량 모델로 라우팅해 비용 절감. 대규모 팀 실행 전 예상 토큰/비용을 보고·승인받는다. Codex 런타임은 .codex/agents/*.toml·내장 worker/explorer의 현재 모델/설정값을 사용.
팀 재구성: 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다.
각 에이전트를 프로젝트/.claude/agents/{name}.md에 정의한다. 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업. 에이전트 팀 모드에서는 ## 팀 통신 프로토콜 섹션을 추가하여 메시지 수신/발신 대상과 작업 요청 범위를 명시한다.
정의 템플릿과 실제 파일 전문은
references/agent-design-patterns.md의 "에이전트 정의 구조" +references/team-examples.md참조.
QA 에이전트 포함 시 필수 사항:
general-purpose 타입을 사용하라 (Explore는 읽기 전용이므로 검증 스크립트 실행 불가)references/qa-agent-guide.md 참조코드를 쓰거나 고치는 에이전트(빌더·수정·QA)의 ## 작업 원칙에 개발 규칙·TDD 교리를 주입한다. 절차:
references/dev-rules.md, references/tdd-doctrine.md를 타겟 하네스의 프로젝트/.claude/skills/{harness-name}/references/로 복사한다 (Codex 동시 출력 시 .agents/skills/{harness-name}/references/에도 복사, 주입 실경로도 런타임별로 맞춘다).> 개발 규칙: \.claude/skills/{harness-name}/references/dev-rules.md` 준수./> TDD 규율: `.claude/skills/{harness-name}/references/tdd-doctrine.md` 준수.`[[ ]]나 플러그인 내부 경로는 서브에이전트가 해소 못 하므로 금지. 본문 복붙도 금지(DRY).각 에이전트가 사용할 스킬을 프로젝트/.claude/skills/{name}/SKILL.md에 생성한다. 듀얼 런타임이면 .agents/skills/{name}/에도 동시 출력(SKILL.md 포맷 동일, references/runtime-adapters.md §3·5). 상세 작성 가이드는 references/skill-writing-guide.md 참조.
신규 스킬 생성 전, 프로젝트/.claude/skills/의 기존 스킬과 중복 여부를 확인한다. 하네스를 반복 구축하다 보면 기능이 겹치는 스킬이 다른 이름으로 누적되기 쉽다.
중복 분류 기준과 일반화 패턴은
references/skill-writing-guide.md의 "스킬 재사용 설계" 참조.
skill-name/
├── SKILL.md (필수)
│ ├── YAML frontmatter (name, description 필수)
│ └── Markdown 본문
└── Bundled Resources (선택)
├── scripts/ - 반복/결정적 작업용 실행 코드
├── references/ - 조건부 로딩하는 참조 문서
└── assets/ - 출력에 사용되는 파일 (템플릿, 이미지 등)
description은 스킬의 유일한 트리거 메커니즘이다. Claude는 보수적으로 판단하므로 **적극적("pushy")**으로 작성한다. 핵심: 하는 일 + 구체적 트리거 상황을 모두 기술 + 유사하나 트리거 금지인 경우와 구분. (나쁜 예 "PDF 처리 스킬" ↔ 좋은 예 "PDF 읽기·추출·병합·분할·OCR 등 모든 PDF 작업; .pdf 언급/PDF 산출물 요청 시 반드시 사용")
| 원칙 | 설명 |
|---|---|
| Why를 설명하라 | "ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. |
| Lean하게 유지 | 컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 references/로 이동한다. |
| 일반화하라 | 특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지. |
| 반복 코드는 번들링 | 테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 scripts/에 미리 번들링한다. |
| 명령형으로 작성 | "~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다. |
스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:
| 단계 | 로딩 시점 | 크기 목표 |
|---|---|---|
| Metadata (name + description) | 항상 컨텍스트에 존재 | ~100단어 |
| SKILL.md 본문 | 스킬 트리거 시 | <500줄 |
| references/ | 필요할 때만(조건부) | 파일당 권장 300줄, 초과 시 ToC+섹션 라우팅 필수 (스크립트는 로딩 없이 실행) |
크기 관리 규칙:
cloud-deploy/
├── SKILL.md (워크플로우 + 선택 가이드)
└── references/
├── aws.md ← AWS 선택 시만 로드
├── gcp.md
└── azure.md
상세 작성 패턴, 예시, 데이터 스키마 표준은
references/skill-writing-guide.md참조.
코드/설계 도메인이어도 codex/gemini 연동 시에만 만든다(작동 불가 스킬 방지).
bash skills/myharness/scripts/check-review-tools.sh → 끝줄 AVAILABLE:. none=스킬 생성 안 함(내부 QA만, 보고서·CLAUDE.md에 "도구 미연동 생략" 명시) / 하나만=그 도구만 쓰는 저하 모드 생성 / 둘 다=풀 생성.references/external-review-loop.md(방법론 겸 템플릿)를 타겟 .claude/skills/external-review-loop/SKILL.md(듀얼 런타임이면 .agents/skills/external-review-loop/에도)로 생성(frontmatter 포함). check-review-tools.sh·build-scorecard.sh를 그 스킬 scripts/로 복사(런타임 폴백·scorecard용).오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 references/orchestrator-template.md 참조.
기존 확장 시 오케스트레이터 수정: 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다.
Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다:
에이전트 팀 패턴 (기본):
오케스트레이터가 TeamCreate로 팀을 구성하고, TaskCreate로 작업을 할당한다. 팀원들은 SendMessage로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.
흐름: TeamCreate(members) → TaskCreate(의존성) → 팀원 자체 조율(SendMessage) → 결과 수집·종합 → 팀 정리. (상세: references/orchestrator-template.md 템플릿 A)
서브 에이전트 패턴 (대안):
오케스트레이터가 Agent 도구로 서브 에이전트를 직접 호출한다(run_in_background: true 병렬, 결과는 메인 반환). 팀 통신이 불필요할 때. (템플릿 B)
하이브리드 패턴: Phase마다 모드를 섞음(예: 병렬 수집=서브 → 합의 통합=팀 / 팀 초안 → 서브 검증 / Phase 간 TeamDelete+새 TeamCreate). 각 Phase 상단에 실행 모드 명시. 상세: references/orchestrator-template.md 템플릿 C.
오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:
| 전략 | 방식 | 적용 모드 | 적합한 경우 |
|---|---|---|---|
| 메시지 기반 | SendMessage로 팀원 간 직접 통신 | 팀 | 실시간 조율, 피드백 교환, 가벼운 상태 전달 |
| 태스크 기반 | TaskCreate/TaskUpdate로 작업 상태 공유 | 팀 | 진행상황 추적, 의존 관계 관리, 작업 자체 요청 |
| 파일 기반 | 약속된 경로에 파일을 쓰고 읽음 | 팀 + 서브 | 대용량 데이터, 구조화된 산출물, 감사 추적 필요 |
| 반환값 기반 | Agent 도구의 반환 메시지 | 서브 | 서브 에이전트 결과를 메인이 직접 수집 |
권장 조합 (팀 모드): 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통) 권장 조합 (서브 모드): 반환값 기반(결과 수집) + 파일 기반(대용량 산출물) 하이브리드: 각 Phase의 실행 모드에 맞춰 해당 조합 적용
파일 기반 전달 시 규칙:
_workspace/ 폴더를 만들어 중간 산출물 저장{phase}_{agent}_{artifact}.{ext} (예: 01_analyst_requirements.md)_workspace/)은 보존 (사후 검증·감사 추적용)## 다음 단계 참조 블록 의무 — 미해결 이슈·핵심 결정과 이유·다음 단계 안내. 다음 단계 사전작업은 직전 결과서의 이 블록을 먼저 읽고 시작한다(판단 연속성, 맥락 단절 방지, 비용 ~0).오케스트레이터 내에 에러 처리 방침을 포함한다. 핵심 원칙: 1회 재시도 후 재실패 시 해당 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제하지 않고 출처 병기.
에러 유형별 전략표와 구현 상세는
references/orchestrator-template.md의 "에러 핸들링" 참조.
| 작업 규모 | 권장 팀원 수 | 팀원당 작업 수 |
|---|---|---|
| 소규모 (5~10개 작업) | 2~3명 | 3~5개 |
| 중규모 (10~20개 작업) | 3~5명 | 4~6개 |
| 대규모 (20개+ 작업) | 5~7명 | 4~5개 |
팀원이 많을수록 조율 오버헤드가 커진다. 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다. 동시성 cap(백프레셔): 동시 실행 기본 3·최대 5, 외부 리뷰는 별도 2. 초과는 큐잉. 대규모 fan-out의 리소스·API quota·토큰 폭증 방지 (
references/orchestrator-template.md동시성 정책).
하네스 구성 완료 후, 프로젝트의 CLAUDE.md에 최소한의 포인터를 등록한다. CLAUDE.md는 새 세션마다 로딩되므로, 하네스 존재와 트리거 규칙만 기록하면 오케스트레이터 스킬이 나머지를 처리한다.
CLAUDE.md 템플릿:
## 하네스: {도메인명}
**목표:** {하네스의 핵심 목표 한 줄}
**트리거:** {도메인} 관련 작업 요청 시 `{orchestrator-skill-name}` 스킬을 사용하라. 단순 질문은 직접 응답 가능.
**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| {YYYY-MM-DD} | 초기 구성 | 전체 | - |
듀얼 런타임 포인터: Codex용으로 레포 루트 AGENTS.md에도 같은 포인터 + Codex 오케스트레이션 어댑터(subagents/subprocess) 주석을 출력한다(Codex 자동 로드). 둘 다 같은 정본을 가리킴. 한쪽만 갱신=drift. 상세: references/runtime-adapters.md.
CLAUDE.md에 넣지 않는 것: 에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. 이유: 에이전트/스킬 목록은 오케스트레이터 스킬과 .claude/agents/, .claude/skills/에서 관리하므로 중복이다. 디렉토리 구조는 파일 시스템에서 직접 확인 가능하다. CLAUDE.md는 포인터(트리거 규칙) + 변경 이력만 담는다.
오케스트레이터는 초기 실행뿐 아니라 후속 작업도 처리해야 한다. 다음 세 가지를 보장하라:
1. 오케스트레이터 description에 후속 키워드 포함: 초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현:
2. 오케스트레이터 Phase 0에 컨텍스트 확인 단계 추가: 워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:
_workspace/ 존재 + 사용자가 부분 수정 요청 → 부분 재실행 (해당 에이전트만 재호출)_workspace/ 존재 + 사용자가 새 입력 제공 → 새 실행 (기존 _workspace를 _workspace_{YYYYMMDD_HHMMSS}/로 이동 — 반복 실행 덮어쓰기 방지, 템플릿과 일치)_workspace/ 미존재 → 초기 실행3. 에이전트 정의에 재호출 지침 포함:
각 에이전트 .md 파일에 "이전 산출물이 있을 때의 행동"을 명시한다:
오케스트레이터 템플릿의 "Phase 0: 컨텍스트 확인" 섹션 참조:
references/orchestrator-template.md
내부 생성-검증(QA 에이전트)에 더해, 단계 산출물마다 외부 리뷰 게이트를 건다. 무차별 적용은 과의식이므로 리스크 등급으로 강도를 맞춘다.
| 등급 | 조건 | 게이트 |
|---|---|---|
| 경량 | 1파일·가역·테스트 無 (오타·문구·설정) | 내부 QA만 |
| 표준 | 다파일·기능 추가 | 내부 QA + 외부리뷰 1회(단계 끝) |
| 중대 | 계약 변경·비가역·다도메인 | 단계마다 외부리뷰 + 승인 사다리(PRD→계획서→실행: 각 관문마다 사용자 승인+외부리뷰, 반려 시 해당 단계 재작업; 승인 관문 절차는 external-review-loop Step 7 준용) |
단계 마감 게이트(표준·중대): 오케스트레이터가 external-review-loop 스킬 호출 — 라운드 반복 루프(codex/gemini 병렬 → 판정 → 확인분만 TDD 수정·게이트 → 수정 diff 재리뷰). loop-until-dry(신규 확인 0건 K회 연속) 또는 MAX_ROUNDS에서 종료. 판정 원장(verdicts.json)으로 신규만 판정. 근거 수집은 위임 가능하나 최종 확정은 오케스트레이터 비위임. 상세: references/external-review-loop.md.
커밋 순서(순환 제거): 리뷰→판정→수정→게이트 PASS → 승인 관문 → 단일 커밋. (리뷰는 커밋 전 작업트리/스테이지 대상 — "커밋 직후 리뷰" 아님.)
프로젝트/_workspace/.autonomous 마커(또는 "자율로"·"승인 생략" 발화) 시 승인 자동 통과 → 커밋. 권한모드(bypassPermissions)는 스킬이 못 읽으므로 마커/발화로 명시. 마커 ON이어도 외부리뷰·판정·게이트는 그대로(인간 승인 한 스텝만 생략)._workspace/.autonomous-push 마커 시만 자동.리뷰 예산(비용·지연 통제): run당 외부 리뷰 횟수 상한을 두고, 코드 변경 없으면 게이트 생략(skip-when-no-delta). 검증된 반복 구간은 _workspace/.fast-pass 마커로 우회. 이슈 다수(10+)면 판정 보조로 일괄 처리해 오케스트레이터 컨텍스트 비대화를 막는다.
생성된 하네스를 검증한다. 상세 테스트 방법론은 references/skill-testing-guide.md 참조.
주의 — 스코프: 위는 생성된 하네스 검증이다.
scripts/run-policy-audit.sh는 팩토리 레포 자체(skills/myharness 경로·버전 파일) 감사 도구로, 생성된 도메인 하네스에는 경로가 안 맞아 적용하지 않는다. 팩토리 유지보수 시점 호출은 Phase 7-5 Step 4 참조.
run_in_background 설정, 반환값 수집 로직 확인smoke/full 모드(비용 통제): 기본은 smoke — 스킬당 대표 프롬프트 1개 + 정적 트리거 lint. with/without 비교·20개 트리거 eval·반복 최적화 등 full은 명시 요청 또는 릴리스 게이트에서만(스킬 N개면 agent run이 곱셈으로 폭증).
생성된 각 스킬에 대해 실제 실행 테스트를 수행한다:
테스트 프롬프트 작성 — 각 스킬에 대해 2~3개의 현실적인 테스트 프롬프트를 작성한다. 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장으로 작성한다.
With-skill vs Without-skill 비교 실행 — 가능하면 스킬 있는 실행과 없는 실행을 병렬로 수행하여 스킬의 부가가치를 확인한다. 에이전트를 두 개씩 스폰한다:
결과 평가 — 산출물의 품질을 정성적(사용자 리뷰) + 정량적(assertion 기반) 으로 평가한다. 산출물이 객관적으로 검증 가능한 경우(파일 생성, 데이터 추출 등) assertion을 정의하고, 주관적인 경우(문체, 디자인) 사용자 피드백에 의존한다.
반복 개선 루프 — 테스트 결과에서 문제가 발견되면:
반복 패턴 번들링 — 테스트 실행에서 에이전트들이 공통으로 작성하는 코드(예: 모든 테스트에서 동일한 헬퍼 스크립트를 생성)가 발견되면, 해당 코드를 scripts/에 미리 번들링한다.
각 스킬의 description이 올바르게 트리거되는지 검증한다:
near-miss 작성 핵심: "피보나치 함수 작성" 같이 명백히 무관한 쿼리는 테스트 가치가 없다. "이 엑셀 파일의 차트를 PNG로 추출해줘" (xlsx 스킬 vs 이미지 변환)처럼 경계가 모호한 쿼리가 좋은 테스트 케이스다.
기존 스킬과의 트리거 충돌도 이 단계에서 확인한다.
## 테스트 시나리오 섹션 추가하네스는 한 번 만들고 끝나는 정적 산출물이 아니다. 사용자 피드백에 따라 계속 진화하는 시스템이다.
매 하네스 실행 완료 후, 사용자에게 피드백을 요청한다:
피드백이 없으면 넘어간다. 강요하지 않되, 반드시 기회를 제공한다.
피드백 유형에 따라 수정 대상이 다르다:
| 피드백 유형 | 수정 대상 | 예시 |
|---|---|---|
| 결과물 품질 | 해당 에이전트의 스킬 | "분석이 너무 피상적" → 스킬에 깊이 기준 추가 |
| 에이전트 역할 | 에이전트 정의 .md | "보안 검토도 필요" → 새 에이전트 추가 |
| 워크플로우 순서 | 오케스트레이터 스킬 | "검증을 먼저 해야" → Phase 순서 변경 |
| 팀 구성 | 오케스트레이터 + 에이전트 | "이 둘은 합쳐도 될 듯" → 에이전트 병합 |
| 트리거 누락 | 스킬 description | "이 표현으로 하면 작동 안 함" → description 확장 |
모든 변경은 CLAUDE.md의 변경 이력 테이블에 기록한다 (Phase 5-4 템플릿의 "변경 이력" 섹션과 동일 테이블):
**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-04-05 | 초기 구성 | 전체 | - |
| 2026-04-07 | QA 에이전트 추가 | agents/qa.md | 산출물 품질 검증 부족 피드백 |
| 2026-04-10 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 |
이 이력을 통해 하네스가 어떤 방향으로 진화했는지 추적하고, 퇴행(regression)을 방지한다.
사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다:
loop_scorecard.json 추세가 악화: alignment_score 롤링 하락 3회 연속, rounds_normalized 상승 추세, overturned_rejection_rate 임계 초과, 동일 경계 N회 실패. 단, 자동 적용 금지 — 제안만 + 승인 게이트, min_adjudicated_claims≥20 전 발화 금지(플래핑·Goodhart 방지). 상세: references/loop-self-eval.md.기존 하네스의 점검·수정·동기화를 체계적으로 수행한다. Phase 0에서 "운영/유지보수" 분기로 진입했을 때 이 워크플로우를 따른다.
Step 1: 현황 감사
.claude/agents/ 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성.claude/skills/ 디렉토리 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성Step 2: 점진적 추가/수정
Step 3: CLAUDE.md 변경 이력 갱신
Step 4: 변경 검증
bash scripts/run-policy-audit.sh 실행(팩토리 레포 자체 — 링크 정합·SKILL ≤500·stale 식별자·버전 정합·듀얼런타임 parity·JSON·bash -n). 실패 정책: fail(exit 1)이면 차단 → 수정 후 재실행하여 PASS, warn은 사람 검토(차단 안 함). 저비용·정적이라 LLM 토큰 0. 권고 게이트 — 매 변경 후·릴리스 전. (하드 push 게이트는 강제하지 않음)한쪽 런타임(예: .claude/)에서 스킬·에이전트를 수정하면 다른 쪽(.agents/·.codex/)이 stale → 런타임별 행동 불일치(하네스 drift). 모든 수정 후 양쪽 경로(.claude/skills/↔.agents/skills/, .claude/agents/*.md↔.codex/agents/*.toml)의 정합을 대조·동기화한다. CLAUDE.md·AGENTS.md 포인터도 동시 갱신. 심링크 운영(예: .agents/skills/{name}→.claude 또는 공통 출처)이면 자동 동기되므로 권장.
생성 완료 후 확인:
.claude/agents/(정의 파일, 빌트인 타입도 필수) + .claude/skills/(SKILL.md + references/) 생성opus, 단순 작업은 경량 모델 (비용 통제) / Codex는 런타임 모델.claude/commands/ — 아무것도 생성하지 않음.codex/agents/*.toml 생성 + .claude↔.codex 역할 동등성 + .agents/skills/ references/scripts 동봉 검증[[ ]] 금지) + 교리 파일 타겟 복사 (Phase 3-1)check-review-tools.sh) 후 external-review-loop 스킬 생성 — 도구 전무면 생략(불필요 스킬 방지) + 단계 게이트 배선, 단계마다 리스크 등급 판정 (Phase 4-6, 5-6)_workspace/.autonomous)·push 별도 게이트 반영## 다음 단계 참조 블록 (연속성)AGENTS.md + 스킬 .agents/skills/ 출력, 오케스트레이터에 어댑터(TeamCreate / Codex subagents·subprocess) 명시 (references/runtime-adapters.md)references/factory-map.md — 최소 경로(도메인/리스크별 무엇을 쓰나)·구현 상태·루프 개요 지도. 단순 하네스 과부담 방지.references/agent-design-patterns.mdreferences/team-examples.mdreferences/orchestrator-template.mdreferences/skill-writing-guide.md — 작성 패턴, 예시, 데이터 스키마 표준references/skill-testing-guide.md — 테스트/평가/반복 개선 방법론references/qa-agent-guide.md — 빌드 하네스에 QA 에이전트를 포함할 때 참조. 통합 정합성 검증 방법론, 경계면 버그 패턴, QA 에이전트 정의 템플릿 포함. 실제 프로젝트에서 발견된 7개 버그 사례 기반.references/loop-self-eval.md(루프 scorecard·alignment·단계적 — 측정만→수동→제안→자동) + references/self-improvement-loop.md(생성 산출물 벤치→holdout→승인→채택, 설계만·MVP 단계적·자동 적용 아님). 용어: loop_scorecard(루프) vs artifact_benchmark(산출물).references/external-review-loop.md — codex/gemini 독립 검증 단계 게이트. 방법론 겸 생성 템플릿. 루프 제어(loop-until-dry·MAX_ROUNDS·라운드 카운터)·판정 원장(verdicts.json, dedup vs seen)·수정본 재리뷰·근거수집 위임/확정 비위임·기각 사유표·커밋 순서·자율 노브 포함.references/tdd-doctrine.md, references/dev-rules.md — 코드/수정 에이전트 작업 원칙 주입용.references/runtime-adapters.md — Claude Code/Codex 듀얼 런타임 설계. 진입점·오케스트레이션 매핑, AGENTS.md·.agents/skills/ 생성, 설치(Codex 공식 docs 검증).npx claudepluginhub cookyman74/my_harness --plugin myharnessA meta-skill that defines agent teams and skills for domain/project automation. Use for initial harness setup, adding agents, or auditing/maintaining existing agent-skill configurations.
Diagnoses Claude Code harness health (hooks, skills, agents, rules, MCP, eval) across 8 dimensions, scores 0-24 with S-D grades, and provides improvement suggestions. Scans ~/.claude/. Triggers: harness audit, 하네스 진단.
Audits Claude Code harness maturity using 6-axis 24-item checklist and 2x3 matrix (Static/Behavioral/Growth × User/Project), running 4 sub-agents for skill portfolio, sessions, context, and automation. Outputs scorecards, action reports, HTML/MD files.