harness-maker: Instructions file for Claude Code

CLAUDE.md — harness-maker

이 파일은 Claude / autoloop CODER agent 가 본 프로젝트에서 작업할 때 따라야 하는 규칙·관례 모음. 모든 결정은 사용자가 사전에 lock-in 했음. autoloop 빌드 중에는 AskUserQuestion 호출 금지 — 모호하면 본 문서 + TECH_SPEC.md 우선.

제1목표

harness-maker 의 제1목표는 기본 품질을 지키면서 빠르고 효율적인 워크플로를 만드는 것이며, 복잡한 설계를 지양하고 단순하고 효율적인 쪽을 택한다. HOW 는 AI 가 최대한 가져가되 WHY·WHAT·트레이드오프는 사람이 소유하고, 작업이 끝나면 코드와 함께 사람의 시스템 이해도 갱신되게 한다.

아래의 모든 원칙·게이트·에이전트는 이 목표에 종속된다. 어떤 장치가 품질을 지키는 것보다 워크플로를 느리고 복잡하게 만드는 데 더 기여한다면, 그 장치를 줄이거나 없애는 것이 옳은 방향이다.

대상은 1인 시니어 개발자다. 시니어에게 필요한 건 설명이 아니라 바뀐 가정과 위험을 드러내는 것이다. 그래서 학습·코칭 모드, 역량 평가, 팀 협업 기능은 만들지 않는다. 결정 주체 규칙과 지표는 .claude/intent.yaml 에 있다.

LLM 활용 원칙 (최우선)

harness-maker 는 Claude Code + Codex 의 플러그인으로, LLM 판단력을 최대한 활용하여 품질을 극대화한다.

• 규칙 기반 대신 LLM 판단: 패턴 매칭·키워드 필터로 해결할 수 있는 것도, LLM 이 더 정확하게 판단할 수 있으면 LLM 에 위임
• 모호함 감지: 답변이 충분히 actionable 한지 판정은 LLM 이 직접 수행 (regex 로 vague 판정 금지)
• 질문 생성: 인터뷰 follow-up 질문은 LLM 이 컨텍스트를 읽고 동적으로 생성 (고정 스크립트 금지)
• 추출·요약: 소스 문서에서 목적·불변조건·우선순위 등을 뽑는 작업은 LLM 이 전체 문서를 읽고 추출
• 수렴 판단: stopping criteria 만족 여부는 LLM 이 현재 상태를 읽고 판단

템플릿(.j2)이 생성하는 슬래시 명령 안에서 Claude 가 직접 판단·추출·생성하도록 프롬프트를 설계할 것. Python 레이어는 타입 계약·저장·안전 레일만 담당.

프로젝트 정체성

• 이름: harness-maker (Claude Code + Codex 플러그인)
• 단일 메타 명령: /harness-maker:make (audit/add/remove/promote 플래그)
• 사용자 명령은 /hm: prefix — Claude Code 는 /hm:<name>, Codex 는 $hm-<name>
• 언어: English-default (locale=en 디폴트). interview 첫 질문이 locale (free-text). 한국어 등 다른 locale 도 입력 가능, unknown locale 은 en 으로 silent fallback
• 타깃 IDE: targets 축으로 사용자가 명시 선택 (아래 §Targets 정책 참조)

Targets 정책

harness.yaml.targets: list[Target] — 사용자 하네스가 어느 IDE 에서 작동할지 결정하는 축. preset 과 직교.

• 값: claude-code | codex (multi-select)
• 인터뷰 정책: 명시 multi-select 강제. auto-detect 금지 (디렉토리 존재 여부 등으로 추론하지 않음). 사용자 의도 확인 필수.
• Default fallback: 옛 harness.yaml 에 targets 키 없을 때만 [claude-code] silent fallback + 경고 로그. 신규 인터뷰는 항상 명시 선택.
• Cursor 제거 (0.63.0, SPEC-hm-overhaul-p1 IRR-001): harness.yaml 또는 --targets 의 cursor 는 make 1회당 경고 1줄 후 제거 (빈 목록 → [claude-code]), agent_models.*.cursor 는 경고 후 tier alias 일 때만 Claude 모델로 쓰임 (0.62 동작). 남은 .cursor/ 파일은 pristine (manifest + 0.62 출하 entry 그대로) 일 때만 삭제, 그 외는 KEPT (cursor_retire). hook_host 는 hook 별로 판단 — kept 파일이 그 모듈을 살아있는 --with 로 돌릴 때만 Claude 사본이 물러남.
• Codex dual role (PLAN-codex-second-llm-integration ADR-009): codex 는 IDE asset 렌더링 (.codex/) 뿐 아니라 second-LLM provider 역할도 한다. 이 provider 축은 harness.yaml.second_opinion (PLAN-second-opinion-multi-model 이 옛 codex_second_opinion 을 대체) 로 제어된다 — targets 와 직교. 자세한 건 아래 Cross-model second opinion (multi-model).
  • Cross-model second opinion (multi-model) — full rules: docs/reference/second-opinion.md. Load-bearing rules:
    • harness.yaml.second_opinion.models (codex/antigravity, orthogonal to targets). Every CLI call goes through harness_maker.second_opinion_invoke; never inline a raw CLI in a recipe (four silent-skip bugs shipped that way).
    • k-of-N consensus with K=2 fixed; PIDA acceptance gate plus a vote freeze (one model call per review in /hm:execute); every failure mode is warn-and-proceed.
    • Never hand-compute ledger rates. Use hm verifier_discrimination report --ledger .claude/observability/second-opinion.jsonl. It applies .ledger-exclusions.json; a hand count was 30× off.
    • A green /hm:health smoke proves the base path only, not the worktree path.