my-harness

My Harness — 한국어 우선 슬림 팩토리

업스트림 skills/harness/SKILL.md의 핵심 워크플로우를 보존하되, (1) 한국어 우선, (2) 패턴 3종으로 슬림화, (3) 이 레포 전용 기본값을 프리베이크한 개인 포크.

핵심 원칙:

1. 에이전트 정의(.claude/agents/) + 스킬(.claude/skills/)을 파일로 생성한다.
2. 에이전트 팀이 기본 실행 모드. 2명 이상 협업이면 팀 먼저 검토.
3. CLAUDE.md엔 포인터(트리거 규칙) + 변경 이력만 등록.
4. 하네스는 진화한다 — 실행 후 피드백 반영, 지속 갱신.
5. 모든 Agent 호출에 model: "opus" 명시.
6. 품질 게이트 2층. 코드/설계 도메인이면 내부 생성-검증(같은 세션 QA) 과 외부 리뷰 루프(codex/gemini 독립 검증)를 병행한다. 같은 컨텍스트 QA는 같은 맹점을 공유하므로 외부 독립 관점이 추가 결함을 잡는다.
7. 생성물에 교리 주입. 생성하는 빌더/수정/QA 에이전트의 작업 원칙에 개발 규칙·TDD 교리를 포인터로 주입(복붙 금지, DRY). 서브에이전트는 글로벌 컨텍스트를 못 받으므로 명시 주입 필요.

깊은 디테일이 필요하면 업스트림/로컬 참조를 읽는다 (중복 작성 금지):

• 패턴/분리기준/재사용: skills/harness/references/agent-design-patterns.md
• 스킬 작성: skills/harness/references/skill-writing-guide.md
• 오케스트레이터: skills/harness/references/orchestrator-template.md
• QA: skills/harness/references/qa-agent-guide.md
• 테스트: skills/harness/references/skill-testing-guide.md
• 실제 예시: skills/harness/references/team-examples.md
• 개발 규칙(주입용): references/dev-rules.md ([[dev-rules]])
• TDD 교리(주입용): references/tdd-doctrine.md ([[tdd-doctrine]])
• 외부 리뷰 게이트: external-review-loop 스킬 (단계 산출물마다 codex/gemini 독립 검증)

패턴 3종 (슬림)

패턴	언제	데이터 흐름
파이프라인	순차 의존 작업 (A 산출물 → B 입력)	단방향 체인
팬아웃/팬인	병렬 독립 수집 후 통합	분산 → 수집
생성-검증 (Producer-Reviewer)	생성 후 품질 검수 필수	생성 → 내부 QA 교차검증 (+ 코드/설계면 외부 리뷰 루프 병행)

감독자/전문가풀/계층위임이 정말 필요하면 업스트림 agent-design-patterns.md로 확장. 기본은 위 3종. 생성-검증을 코드/설계 도메인에 쓸 땐 내부 QA 뒤에 external-review-loop(codex/gemini)를 단계 게이트로 붙인다.

워크플로우 (압축)

Phase 0: 현황 감사

.claude/agents/, .claude/skills/, CLAUDE.md 읽기 → 신규/확장/유지보수 분기. drift(파일 vs CLAUDE.md 이력 불일치) 감지 후 사용자에게 요약 보고.

Phase 1: 도메인 분석

요청에서 도메인·핵심 작업유형(생성/검증/편집/분석) 식별 → 코드베이스 탐색(기술스택·데이터모델·주요모듈) → 기존 에이전트/스킬 충돌·중복 점검 → 사용자 숙련도 감지 후 톤 조절. 직전 단계 결과서(_workspace/)의 ## 다음 단계 참조 블록이 있으면 먼저 읽는다(F5 연속성).

Phase 2: 팀 설계

1. 실행모드: 팀 우선. 결과 전달만이면 서브에이전트, Phase별 상이하면 하이브리드.
2. 패턴 선택 (위 3종).
3. 에이전트 분리: 전문성·병렬성·컨텍스트·재사용성 4축. 3-4명 집중 팀 > 산만한 7명.

Phase 3: 에이전트 정의

프로젝트/.claude/agents/{name}.md 파일 필수 (빌트인 타입이라도 파일 생성). 필수 섹션: 핵심 역할, 작업 원칙, 입출력 프로토콜, 에러 핸들링, 협업. 팀 모드면 ## 팀 통신 프로토콜 추가.

• 3-0 중복 검토: 기존 에이전트와 역할 겹치면 재사용/일반화.
• 모델: 전부 model: "opus".
• QA 에이전트: general-purpose 타입(검증 스크립트 실행). "존재 확인" 아닌 경계면 교차 비교. 모듈 완성 직후 점진 실행.
• 교리 주입(코드/수정 에이전트): 빌더·수정·QA 에이전트의 ## 작업 원칙에 실경로 두 줄을 넣는다. 서브에이전트는 [[ ]]를 해소 못 하므로 레포상대 경로 필수 — > 개발 규칙: \.claude/skills/my-harness/references/dev-rules.md` 준수./> TDD 규율: `.claude/skills/my-harness/references/tdd-doctrine.md` 준수.` 본문 복붙 금지(DRY). 비코드 에이전트(문서·리서치)는 dev-rules만 선택 적용.

Phase 4: 스킬 생성

프로젝트/.claude/skills/{name}/SKILL.md. frontmatter name+description 필수.

• 4-0 중복 검토: 기존 스킬과 기능 겹치면 일반화/통합.
• description은 적극적(pushy): 하는 일 + 구체적 트리거 상황 + 후속 키워드("다시/재실행/수정/업데이트") 모두 기술.
• 본문: Why를 설명(강압 지시 X), 500줄 이내, 명령형, 반복코드는 scripts/로 번들.
• Progressive Disclosure: metadata(항상) → SKILL.md(트리거 시) → references/(필요 시).

Phase 5: 오케스트레이션

오케스트레이터 스킬이 팀을 엮는다. 팀 모드: Agent(팀원 spawn)+TaskCreate+SendMessage (구 TeamCreate/TeamDelete는 v2.1.178에서 제거). 데이터 전달: 태스크(조율)+파일(산출물)+메시지(소통). 파일 산출물은 _workspace/{phase}_{agent}_{artifact}.{ext}, 중간물 보존.

• 결과서-RAG 연속성(F5): 각 결과서 상단에 ## 다음 단계 참조 블록 의무 — 미해결 이슈·핵심 결정과 이유·다음 단계 안내. 다음 단계 사전작업은 직전 결과서의 이 블록을 먼저 읽고 시작(판단 연속성). 비용 ~0, 맥락 단절 방지.

• 에러: 1회 재시도 후 실패면 해당 결과 없이 진행+보고서 누락 명시. 상충 데이터는 삭제 X, 출처 병기.

• CLAUDE.md 포인터 등록 (5-4) + 후속 작업 키워드/컨텍스트 확인 단계 (5-5).

• 리스크 등급(게이트 강도 — 오버헤드 보정): 무차별 게이트는 과의식이다. 단계마다 등급을 정해 게이트 강도를 맞춘다.

  등급	조건	게이트
  경량	1파일·가역·테스트 無 (오타·문구·설정)	내부 QA만
  표준	다파일·기능 추가	내부 QA + 외부리뷰 1회(단계 끝)
  중대	계약 변경·비가역·다도메인	단계마다 외부리뷰 + 승인 사다리(PRD→계획서→실행)

• 단계 마감 게이트(표준·중대 등급): 오케스트레이터가 external-review-loop 호출 — codex/gemini 병렬 리뷰 → 전건 판정(확인/부분/이월/기각) → 확인분만 tdd-doctrine로 수정 → 게이트 PASS. 판정 권위는 오케스트레이터(위임 금지). 설계서/코드/문서 어떤 산출물에도 적용.

• 커밋 순서(F2 — 순환 제거): 리뷰→판정→수정→게이트 PASS → 승인 관문 → 단일 커밋. ("커밋 직후 리뷰" 아님 — 리뷰는 커밋 전 작업트리/스테이지 대상.)

  • 승인 관문 기본: 사용자 승인 대기.
  • 자율 노브: _workspace/.autonomous 마커 존재(또는 사용자가 "자율로"·"승인 생략" 발화) 시 승인 자동 통과 → 커밋. (권한모드는 스킬이 못 읽으므로 마커/발화로 명시. 마커가 ON이어도 external-review·판정·게이트는 그대로 — 인간 승인 한 스텝만 생략.)
  • push는 자율이어도 기본 대기(외부 송출·되돌리기 어려움). _workspace/.autonomous-push 마커 시만 자동.

Phase 6: 검증

구조 검증(파일 위치, frontmatter, 커맨드 미생성) → 트리거 검증(should-trigger 8~10 + should-NOT near-miss 8~10) → 드라이런(데이터 dead-link 없는지) → 테스트 시나리오(정상1+에러1).

Phase 7: 진화

실행 후 피드백 수집 → 유형별 반영(품질→스킬, 역할→에이전트정의, 순서→오케스트레이터, 트리거→description) → CLAUDE.md 변경 이력 기록.

이 레포 전용 프리베이크 기본값

이 레포(harness 플러그인)용 하네스를 만들 땐 아래를 기본 제안으로 사용:

작업	에이전트	스킬	패턴
3개국어 문서 동기화 (README/KO/JA + 뱃지)	doc-syncer	doc-sync	파이프라인
버전 릴리스 (plugin.json/marketplace.json/CHANGELOG/태그)	release-manager	release-flow	생성-검증
하네스 스킬 본문 개선 (skills/harness/*)	skill-maintainer	skill-authoring	생성-검증
교차 파일 정합성 검증	repo-qa	(스킬리스, 에이전트 자체 + check 스크립트)	검증

이 레포의 단골 버그: 3중 버전 불일치(README 뱃지 / marketplace.json / plugin.json), 3개국어 문서 drift, CHANGELOG 누락. repo-qa가 항상 교차 검증.

산출물 체크리스트

• [ ] .claude/agents/ 정의 파일 (빌트인이라도 필수)
• [ ] .claude/skills/ SKILL.md (+ references/scripts 선택)
• [ ] 오케스트레이터 1개 (데이터흐름+에러+테스트 시나리오)
• [ ] 실행모드 명시 / 모든 Agent에 model:"opus"
• [ ] 3-0·4-0 중복 검토 완료
• [ ] .claude/commands/ 아무것도 생성 안 함
• [ ] description pushy + 후속 키워드
• [ ] SKILL.md ≤500줄
• [ ] CLAUDE.md 포인터 + 변경 이력
• [ ] 코드/수정 에이전트에 dev-rules·tdd-doctrine 실경로 주입 ([[ ]] 금지 — 서브에이전트 미해소)
• [ ] 단계마다 리스크 등급(경량/표준/중대) 판정 → 게이트 강도 매칭
• [ ] 표준·중대 등급에 external-review-loop 배선 (내부 QA + 외부 리뷰 2층)
• [ ] 커밋 순서: 리뷰→판정→수정→게이트→승인 관문→커밋. 자율 노브(_workspace/.autonomous)·push 별도 게이트 반영
• [ ] 결과서에 ## 다음 단계 참조 블록 (F5 연속성)