harness-maker CLAUDE.md

CLAUDE.md — harness-maker

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

제1목표

harness-maker 의 제1목표는 기본 품질을 지키면서 빠르고 효율적인 워크플로를 만드는 것이며, 복잡한 설계를 지양하고 단순하고 효율적인 쪽을 택한다.

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

LLM 활용 원칙 (최우선)

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

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

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

프로젝트 정체성

• 이름: harness-maker (Claude Code + Cursor 플러그인)
• 단일 메타 명령: /harness-maker:make (audit/add/remove/promote 플래그)
• 사용자 명령은 /hm: prefix — 양쪽 IDE 모두 /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 / dev_mode 와 직교.

• 값: claude-code | cursor | codex (multi-select)
• 인터뷰 정책: 명시 multi-select 강제. auto-detect 금지 (.cursor/ 디렉토리 존재 여부 등으로 추론하지 않음). 사용자 의도 확인 필수.
• Default fallback: 옛 harness.yaml 에 targets 키 없을 때만 [claude-code] silent fallback + 경고 로그. 신규 인터뷰는 항상 명시 선택.
• Single source 원칙: agents / skills / hooks / MCP 자산은 .claude/ 한 곳에서 양쪽 IDE 가 공유 (Cursor 가 .claude/agents/ 를 native 로 읽음, hooks schema 호환 — IDE 모드 인식은 Phase 1 manual 검증 결과 따름).
• Cursor 추가 자산: targets 에 cursor 포함 시에만 .cursor/rules/*.mdc, .cursor/commands/hm-*.md, .cursor/mcp.json 추가 렌더.
• Cursor 사용자 모델 권장: harness.yaml.recommended_model: claude-opus-4-7 + agent frontmatter model 명시. user override 자유. prompt 자체는 model-agnostic 재작성 안 함 (<thinking> blocks 등 Claude-specific 표현 유지).
• 최소 지원 Cursor 버전: 2.4 (subagents + skills + Claude Code hooks 호환 최초 도입). Cursor 3.0 이상 권장.
• 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) (PLAN-second-opinion-multi-model, supersedes PLAN-codex-second-llm-integration + PLAN-crossmodel-codex-gaps): harness.yaml.second_opinion.models: list[Literal["codex","antigravity"]] — 활성 모델 집합 (빈 리스트=off). Codex CLI (codex exec) 와 Antigravity CLI (agy --sandbox --print, project-less) 를 각각 독립 second-opinion voter 로 붙일 수 있고 둘 다 동시 가능. 두 CLI 호출은 harness_maker.second_opinion_invoke 가 단독 소유한다 (PLAN-second-opinion-invocation-and-slug-cap ADR-001) — 렌더된 레시피는 uv run … -m harness_maker.second_opinion_invoke --model <m> --prompt-file <f> 한 줄로 축소됐고, /hm:health smoke 도 같은 entrypoint 를 호출한다 (ADR-005). 레시피에 raw CLI 를 다시 인라인하지 말 것: prose 레시피는 실행 표면이 없어 render 테스트가 텍스트 grep 밖에 못 하고, 그 형태로 silent-skip 버그가 4번 출하됐다. 옛 codex_second_opinion.enabled=true harness 는 answers_from_harness_yaml 의 1회성 silent migration (ADR-001, schema_version 2→3) 으로 second_opinion.models=["codex"] 로 자동 변환 (both-keys-present 면 new-key-wins + advisory 1회). 축은 targets 와 직교 — targets 에 codex/agy 없어도 활성 가능 (사용자 측 CLI + login 만 있으면 됨).
    • k-of-N consensus, K=2 고정 (ADR-006): /hm:review Step 3.5 가 각 활성 모델을 정식 투표권으로 합류 (voter pool N = enabled reviewers + len(models)). codex_adapter 가 severity critical→P0… 매핑 + null-location symbol/message-similarity relaxation → Step 4 filter. threshold 는 모델을 더 켜도 K=2 고정 (conditional_router.scope_aware_consensus 의 len(reviewers)>=2 — Python 변경 0, prose 만 일반화). recall-favoring: 모델 추가는 consensus 를 쉽게 만든다.
    • per-model config sub-block (ADR-002): second_opinion.{failure_policy, agents} 는 공유 (agents = global allowlist, 모든 모델에 동일 적용); second_opinion.codex.{hermetic, output_schema_path} 와 second_opinion.antigravity.{model} 는 모델별. antigravity model 은 free-text 표시 이름 (agy models 가 안정적 machine ID 없음), 인터뷰 시점에만 live shell-out, render 는 절대 shell-out 안 함 (ADR-007 결정성).
    • mandatory 매트릭스 (ADR-003): Production = 모든 활성 모델을 review+plan 마다 강제 / Side = high-diff 시에만. 활성 모델 균등 적용 (2x 비용 감수).
    • graceful degrade (ADR-011; 분기 정의는 PLAN-second-opinion-invocation-and-slug-cap ADR-008 이 supersede): CLI 미설치 / login 만료 / rate-limit·구독 초과 / timeout / 파싱 불가 — 전부 warn-and-proceed. exit 127 은 더 이상 CLI 미설치의 신호가 아니다 — invoker 는 shell=False 로 돌기 때문에 127 을 만들어주던 쉘이 없고, 미설치는 FileNotFoundError, timeout 은 TimeoutExpired, 실행권한 없음은 PermissionError 로 예외로 온다. 7분기 매트릭스(예외 3 + non-zero exit + payload 획득 실패 + validate 실패 + 성공)가 이걸 전부 흡수하며, resolve_base_root/load_config 의 shell-out 도 같은 보호를 받는다 (git 부재 시 cwd fallback 후 진행 — skip 아님). agy 는 hang 가능 → agy native --print-timeout 240s 를 계속 쓰고, process-level AGY_TIMEOUT_S=300 은 그보다 위에 있는 바깥 backstop 이다 (native 가 먼저 발화해 agy 자신의 진단이 남도록). 옛 "external timeout 래퍼 금지" 규칙의 근거는 allow-rule prefix 매칭이었고 ADR-001 이후 그 근거는 사라졌다 — subprocess.run(timeout=) 은 금지 대상이 아니다. Codex 는 --output-schema 로 JSON 강제; antigravity 도 CLI-레벨 강제가 있다 — 플래그 이름이 다를 뿐이다 (--output-format json --json-schema <path>, 2026-08-08 probe. 옛 "CLI-레벨 강제 없음" 서술은 --output-schema 라는 철자만 찾아본 결과였고, 그 오기가 여섯 곳에 복제돼 파싱 실패 9건의 원인이 됐다 — PLAN-antigravity-second-opinion-timeout ADR-002/006). 단 강제는 best-effort 다: status: SUCCESS 응답에서도 structured_output 키가 없는 경우가 관측됐으므로 codex_adapter.extract_antigravity_payload fail-closed 경로는 폐기가 아니라 필수 fallback 으로 남는다 (4-case 표: 파싱불가→failed / status≠SUCCESS→skipped / structured_output dict→그대로 쓰되 validate 실패는 fail-closed / 부재→response 를 tolerant 추출). plan-validator 는 PIDA (KEEP/REFUTE → oracle 없으면 unresolved surface, never-block).
    • output contract (ADR-008): plan stage 는 second_opinion_results: [{model, status: invoked|skipped|failed, reconciliation: [...]}] 배열 (모델당 정확히 1 entry). 옛 scalar codex_status/codex_reconciliation 대체. review stage 는 persistent status field 없음 (findings 를 source: "<model>" 태그로 Step 4 에 fold).
    • PIDA 수용 게이트 + vote freeze (PLAN-second-opinion-acceptance-gate): review 경로에도 반박 게이트가 생겼다. /hm:review Step 3.4 가 모든 finding (Claude 것 포함) 에 codex_adapter.finding_id 로 불변 id 를 찍고 (리뷰어는 id 를 내보내지 않는다 — LLM 이 만들면 매 실행 달라져 안정성이 깨짐), Step 3.6 이 분쟁 finding 이 지목한 경로에 targeted pytest/ruff/mypy 를 돌려 예산 4000자 / 명령당 1500자 + 가시 절단마커 + id 연결 + 자격증명 라인 필터 를 걸어 주입하고, Step 3.7 이 code-verifier mode B 로 ledger enum (accepted/rejected/duplicate/unresolved) 을 직접 판정한다 (KEEP/REFUTE 중간 어휘 없음 — 번역 단계가 있으면 그 매핑 실패로 행이 조용히 사라진다). accepted 만 Step 4 투표권을 얻고, unresolved 는 manual-only + unverified_severe 스캔의 유일한 provenance 예외 (ADR-004 — 가시성 회귀를 수용한 의도된 선택). Phase 0 mechanical checks 를 oracle 로 재사용하지 말 것 — reviewers.mechanical_checks 로 가드되어 이 repo 에선 렌더 자체가 안 되고, 렌더돼도 Round 1 위에서 1회만 돌며 stop-on-first-failure 라 살아남은 라운드에선 항상 all-green 이다. 모델은 /hm:review 당 정확히 1회 호출되고 rounds 2..N 은 REVIEW 의 ## 🧊 Cross-model findings (frozen @ round 1) 섹션을 다시 읽는다. Auto-Fix Loop 은 단조 격자(pending→resolved/stale 만 progress; → pending 은 절대 아님)와 1회 무진전 라운드 종료(단 round ≥ 2 에서만 평가 — round 1 은 fix 단계가 없어 progress 전이가 원리적으로 0이라 무조건 규칙이면 auto-fix 가 아예 안 돈다)를 갖고, 라운드별 voter state 는 id 기준 merge 다 (wholesale replacement 금지 — 리뷰어 비결정성만으로 corroborating voice 가 사라져 코드 변경 없이 등급이 움직인다). resolved 는 verification 성공 후에만 — revert/skip 된 fix 는 pending 유지.
    • ledger .claude/observability/second-opinion.jsonl 는 두 종류의 행이 공존한다: finding_ref == "n/a" = 호출당 1행 (skip-rate 분모), finding_ref != "n/a" = finding 당 disposition 1행 (accept-rate, oracle_result 에 capped PIDA 근거). 둘 다 status: "invoked" 이므로 finding_ref 가 유일한 판별자 — 필터 없이 집계하면 finding 마다 호출 1건으로 세어 skip-rate 가 조용히 오염된다. disposition 행은 hm second_opinion_invoke --record-disposition --disposition-file <path> 로만 쓴다 (argv JSON 금지 — quoting + ARG_MAX; codex_ledger emit 은 Path.cwd() 에 써서 worktree row-loss 재발). 실패는 exit 0 + [second-opinion] disposition rows NOT recorded: stderr 1행 (조용한 no-op 금지). oracle_result 는 max_length=200 이고 invoker 의 row emission 이 예외를 삼키므로 codex_ledger.cap_oracle_result 로 검증 전에 자른다 — 안 자르면 행 전체가 소실된다. invoker 가 base repo root 기준으로 쓴다 — 옛 codex_ledger.main() 의 project_root=Path.cwd() 는 worktree 안 gitignored 경로에 기록해 task-land 시 소실됐다. 행이 skip 전용에서 호출 전체로 바뀌었으므로 분모가 바뀌었다. 이 수치는 손으로 계산하지 말 것 — 출하된 리더를 쓴다: