Harness Factory

트리거 조건 (1.0 컨벤션 — 본문 참고용, frontmatter description이 권위)

TRIGGER:  '팀 에이전트', 'team agents', 'multi-agent', 'orchestrate agents',
          '서브에이전트 구성' 같이 *여러 에이전트를 묶는* 의도.
SKIP:     단일 skill 작성은 skill-author. 기존 에이전트 사용은 트리거 안 됨.
EXAMPLES:
  - 'PR 응답 검증 팀 만들어줘' → Phase 1 인터뷰 + 7 패턴 중 1 선택
  - 'producer-reviewer 패턴으로' → 인터뷰 단축, 즉시 Phase 2

도메인 설명을 받아 에이전트 팀 + 전용 스킬을 프로젝트 로컬(.claude/)에 생성하는 메타-스킬입니다. revfactory/harness와 같은 L3 meta-factory 역할.

활성화 시 반드시

1. Pre-scan 먼저. Phase 0에서 프로젝트 구조·기존 에이전트·CLAUDE.md를 훑어 Phase 1 답변 초안을 만든 뒤 진입.
2. 도메인 인터뷰 다음, 패턴은 그 후에. Q1~Q6 + 옵션 Deep-dive + Sanity check 순. 작업 특성 답변 전 패턴 확정 금지.
3. 7 패턴 중 1개만 선택. 혼합은 실패 원인. 필요하면 2개 팀으로 분리.
4. 프로젝트 로컬에 작성. 출력은 .claude/agents/, .claude/skills/ (사용자 전역 ~/.claude가 아님).
5. CLI가 있으면 CLI 우선. cfh generate <preset>으로 해결 가능한 경우는 그것을 제안. 커스텀이 필요할 때만 직접 파일 작성.
6. 생성 후 실험 플래그 안내. 에이전트 간 메시지 교환이 필요하면 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 필요함을 알림. Deep-dive D1에서 이미 확인된 경우 중복 안내 생략.
7. (z) 모르겠음 fallback. 모든 Q1Q6·Deep-dive D1D7에 (z) 모르겠음 옵션 기본 탑재. 선택 시 ~/.claude/skills/asset-factory/references/unknown-answer-playbook.md의 3단계 처리 — 예시 2~3개 → 안전한 기본값 제안 → y/n.

7 Phase 워크플로

Phase 0: Pre-scan                (프로젝트 스캔 → Phase 1 답변 초안)
   ↓
Phase 1: Domain Interview        (기본 6 질문 + 옵션 Deep-dive 7 축 + Sanity check)
   ↓
Phase 2: Pattern Selection       (7 패턴 중 1개 추천 + 사용자 확인)
   ↓
Phase 3: Agent Roster            (각 에이전트 책임·도구·입출력 확정)
   ↓
Phase 4: Skill Design            (팀을 트리거할 스킬 + 오케스트레이션 스킬)
   ↓
Phase 5: Scaffold                (cfh generate 또는 직접 Write)
   ↓
Phase 6: Validate + Dry Run      (cfh validate + 샘플 태스크로 시운전)

Phase 복귀 규칙 (공통)

Phase 2 이후에 초반 답변이 틀렸다고 판단되면 아래 트리거로 이전 Phase 복귀:

• "intent 재인터뷰" → Phase 1 Domain Interview로 복귀
• "패턴 재선택" → Phase 2 Pattern Selection으로 복귀
• "roster 수정" → Phase 3 Agent Roster로 복귀
• "skill 재설계" → Phase 4 Skill Design으로 복귀

복귀 시 이전 답변은 참고용으로 남기고 변경 부분만 갱신. 생성된 .claude/agents/*나 .claude/skills/*는 git으로 추적·되돌리기 가능.

Phase 0 — Pre-scan

CLAUDE.md, package.json, ./.claude/agents/, ./.claude/skills/를 훑어 Phase 1 질문의 답변 초안을 만듭니다 (→ references/pre-scan.md). 도메인 경계를 추출해 Q3(전문성 축) 후보를 자동 생성하고, CLAUDE.md에 "프로덕션"·"결제" 등이 보이면 Q4(실패 비용)를 (c) 기본값으로 제시합니다.

빈 프로젝트 또는 스캔할 것이 없으면 "Phase 1 정상 진행"으로 종료.

Phase 1 — Domain Interview

기본 6 질문 → (옵션) Deep-dive 7 축 → Sanity check 순 (→ references/interview-flow.md).

기본 6 질문

1. 태스크 성격 — 반복적/선형적 / 병렬 가능 / 검토·비판이 중요 / 계층적 분해 필요 / 탐색적
2. 입력·출력 — 한 번에 들어오는 입력 단위(파일/PR/요구사항) + 최종 산출물 형태
3. 전문성 축 — 보안·성능·접근성(a11y) / 일관성(consistency) / 멱등성(idempotency) / 지연(latency) / 공정성(fairness) / 타입 / 도메인 — 프로젝트 도메인에 맞게 3~5개 선택. (축은 도메인별로 다르다 — FE: a11y·타입·UX / BE: consistency·idempotency·latency / ML: fairness·robustness / embedded: real-time deadline·footprint.)
4. 실패 비용 — 틀리면 롤백 쉬운가, 아니면 수정 비용이 큰가 (큰 경우 producer-reviewer 강제)
5. 규모 — 에이전트 2~3개로 충분한가, 5개 이상이 필요한가 (5개 넘으면 계층 분해 검토)
6. 관측성 — 실패 시 어떻게 알게 되나 (리턴값 / 로그 / CI / 모니터링 / 없음). Q4=(b)/(c) 와 Q6=(e) 조합은 R8 Sanity check 트리거.

Deep-dive 옵트인 (3지 선택 + CLI bypass)

기본 6 질문 완료 후 사용자에게 (a)/(b)/(c) 3지 선택 제시. CLI --deep/--fast 플래그로 bypass 가능.

자동 추천 규칙:

• Q4=(c) OR Q5=6+ OR Q6=(e) → (b) 모두 yes 권장
• Q1=(e)/(f) → (a) 조건부 권장
• Q5=2~3 AND Q4=(a) AND Q6=(a)/(b)/(c) → (c) skip 권장

(b) 선택 시 아래 7 축 전부 질문. (a) 선택 시 관련된 것만 조건부:

일반적으로 2~4개 축이 활성화됩니다. 7개 전부 묻는 일은 드묾.

Sanity check (요약 카드 직전)

기본 + Deep-dive 답변을 references/sanity-check.md의 R1~R8 룰로 검사:

• R1 규모 vs 축 수
• R2 실패 비용 vs 패턴 후보
• R3 태스크 성격 vs 입출력
• R4 축 겹침
• R5 기존 에이전트 충돌
• R6 Deep-dive 답변 모순 (옵션 수행 시)
• R7 통신 vs 실험 플래그 인식 (옵션 수행 시)
• R8 관측성 공백 vs 실패 비용 (Q6=(e) + Q4=(b)/(c) 시 경고)

모순 발견 시 재확인 → 통과하면 요약 카드 + 패턴 추천 제시하고 사용자 승인.

Phase 2 — Pattern Selection

7 패턴 카탈로그 (→ references/patterns/):

각 패턴 상세는 references/patterns/<pattern>.md. 사용자에게 추천 1개 + 이유 + 대안 1개 제시.

Adversary 추천 신호:

• 확증 편향 위험 (debug 가설 검증·security audit·legal review)
• Q1·Q3에 "반증 시도·취약점 탐색·loophole 찾기" 발화
• Q4 실패 비용이 production 사고 수준 + 가설 ≥ 3

Phase 2.5 — Communication Mode Selection (Pattern 결정 후)

패턴 선택 후 agent 간 통신 mode 명시 선택 (→ ~/.claude/commands/references/agent-team-modes.md).

패턴별 자동 추천

출력 형식 (recommendation+reason)

📌 추천 mode: <subagent | teams>
   이유:
     - 🟢 [verified] 패턴이 <X> → <적합 mode> 매칭
     - 🟡 [inferred] Q5 규모 답이 <N agents> → <subagent 안정 / teams 가치>
     - 🔴 [guessed] (있으면)

다른 옵션:
   - subagent — 토큰 예측 가능·디버깅 쉬움·flag 불필요
   - teams — agent 간 메시지 교환·런타임 동적·단 experimental flag 의존

답변: 추천대로 / subagent / teams / explain

명시 선택 받기 전 Phase 3 진입 금지 (정책 § 0). 짧은 동의(OK·응)는 ambiguous로 대기.

생성 자산 차이

선택된 mode에 따라 Phase 3~5에서 생성되는 자산이 다음을 명시:

• subagent mode: orchestrator가 Agent tool로 N agents 호출. 각 agent input/output contract 명시 (one-shot).
• teams mode:
  • SKILL.md prompt에 통신 패턴 명시 (memo·broadcast·targeted·request-response)
  • max-round budget 명시 (Supervisor 5·Hierarchical 3 per level·Producer-Reviewer 3·Expert Pool 1)
  • flag 활성화 — 두 갈래 모두 명시:
    • 즉시 (세션): export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
    • 영구: ~/.claude/settings.json 또는 ./.claude/settings.json의 "env"에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 추가
  • fallback 정책 명시 (flag 없으면 명시 에러 + 안내)
  • 예상 token range 명시 (사용자 결정 보조)

Phase 3 — Agent Roster

각 에이전트별로 결정 (→ references/agent-contract.md):

• name — kebab-case (예: security-reviewer)
• description — 오케스트레이터가 언제 이 에이전트를 부르는가
• tools — Read, Grep, Glob 등 최소 권한 원칙
• input — 이 에이전트가 받을 것 (경로, 스펙, 이전 단계 출력)
• output — 반환 형식 (단일 메시지 구조: 발견·권고·신뢰도)
• refusal — 거부 조건 (범위 초과, 도구 부족)

Phase 4 — Skill Design

팀을 하나의 스킬로 묶어 트리거 가능하게:

• 트리거 스킬 (필수): 사용자의 의도와 팀의 연결. 예: expert-review-pool SKILL이 사용자 "리뷰해줘"에서 발동.
• 오케스트레이션 스킬 (선택): 패턴이 복잡하면 워크플로를 별도 스킬로. 예: pipeline-flow SKILL.

skill-author의 Phase 2~3 규약을 그대로 적용.

Phase 5 — Scaffold

5a. 이름 충돌 체크 (Scaffold 전 필수)

생성할 각 파일의 경로를 먼저 확인:

• ./.claude/agents/<agent-name>.md × N개 (에이전트마다)
• ./.claude/skills/<team-skill>/SKILL.md

하나라도 이미 존재하면:

⚠️ 이름 충돌 감지
   다음 파일이 이미 존재합니다:
   - ./.claude/agents/<name-1>.md (상태: <managed | user-authored | ...>)
   - ./.claude/skills/<team>/SKILL.md (상태: ...)

어떻게 진행할까요?
  (a) 모든 충돌 이름 변경 — 팀 이름·에이전트 이름 재제안 인터뷰
  (b) 일부만 재사용 — 충돌 파일 개별로 (편집 / 다른 이름 / 덮어쓰기) 결정
  (c) 전부 덮어쓰기 — ⚠️ user-authored 대상은 아래 경고
  (d) 취소

(b) 또는 (c) 덮어쓰기 포함 시 user-authored 파일은 명시적 y/N 확인:

🚨 ./.claude/agents/<name>.md는 사용자 작성물입니다 (삭제 시 복구 불가).
정말 덮어쓰시겠습니까? [y/N]

y만 통과. 그 외 전부 해당 파일 취소.

5b. 실제 생성

충돌 체크 통과 후:

옵션 A — CLI (권장, 프리셋에 맞으면):

cfh generate producer-reviewer
cfh generate pipeline-3stage
cfh generate reviewer-team
cfh generate reviewer-team-backend

덮어쓰기 승인이 있었다면 cfh generate <preset> --force 사용.

옵션 B — Claude가 직접 Write: 프리셋에 없는 커스텀 조합. 파일 구조:

.claude/
├── agents/
│   ├── <agent-1>.md
│   └── <agent-2>.md
└── skills/
    └── <team-skill>/
        └── SKILL.md

각 에이전트 md는 frontmatter name, description, tools를 포함해야 Claude Code가 등록. (→ references/output-contract.md)

Phase 6 — Validate + Dry Run

1. cfh validate 실행.
2. 샘플 태스크 시운전: 사용자에게 "이 팀이 처음으로 풀 작은 태스크 1개"를 요청. 오케스트레이터가 에이전트들을 호출하는 흐름을 실제로 보고 문제점 파악.
3. 실패 시 Phase 3~4로 돌아가 에이전트 책임 분할 조정.

자주 하는 실수

references/

• pre-scan.md — Phase 0 스캔 프로토콜 + Phase 1 초안 매핑
• interview-flow.md — Phase 1 기본 5 질문 + Deep-dive 7 축 + 옵트인 게이트
• sanity-check.md — Phase 1 요약 직전 모순 감지 룰 (R1~R7)
• patterns/pipeline.md — 선형 파이프라인
• patterns/fan-out-fan-in.md — 병렬 분해 + 병합
• patterns/expert-pool.md — 병렬 전문가 풀
• patterns/producer-reviewer.md — 생성-검증 분리
• patterns/supervisor.md — 중앙 배정자
• patterns/hierarchical-delegation.md — 트리 분해
• agent-contract.md — 에이전트 정의 프런트매터·입출력 계약
• output-contract.md — .claude/ 파일 구조와 Claude Code 등록 규칙