Claude Code Harness v2
junhyeong9812/claude_skill_study
Orquestração Claude com estados, dimensões de risco e validação proporcional
Ver no GitHubSistema de orquestração para projetos Claude Code que estrutura o desenvolvimento em estados de tarefa (Exploração ↔ Definição) com verificação proporcional ao risco. Substitui procedimentos rígidos por um documento core (~200 linhas) que define critérios claros (6 dimensões de clareza, 14 eixos de análise) e gatilhos condicionais, reduzindo leitura contextual de ~50k tokens/sessão para ~5k tokens.
Instalação
npx convez-ai junhyeong9812/claude_skill_study1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Projetos Claude Code com múltiplas fases e stakes variáveis (implementação, review, validação)
- Equipes que precisam rastreabilidade de decisões e aprendizados sem overhead processual
- Automação de verificação (git hooks, detecção de contexto, segregação testador/revisor)
Veredito

Arquitetura sólida focada em reduzir sobrecarga cognitiva através de documentação condicional e triage dimensional. Adequada para times experientes em processamento dirigido por risco; requer ingestão inicial de ~15 documentos core, mas economiza iterações posteriores. Implementação em shell/git-hooks é robusta; aprendizado recomendado via `learned.md` (template incluído).
README
A tradução para o português deste README ainda está na fila.
Claude Code 작업 하네스 (v2)
Claude Code가 즉흥적으로 산출물을 만지지 않고, 정의 → 계획 → 개발 → 검증 → 기록을 거치도록 하는 설정 패키지. v2(2026-06-10, Fable 5)는 v1의 "절차를 촘촘히 강제하는 외골격"을 **"판단 기준을 제공하는 단일 핵심 문서 + 강제가 필요한 곳만 훅/네이티브 도구"**로 전면 개편한 버전이다.
핵심 철학
- 상시 선독은 core 하나. 세션마다 읽는 규칙은
CLAUDE.md(11줄, 부트스트랩) +core.md(~200줄)뿐. 나머지는 트리거 시에만 읽는 조건부 문서다. (v1: 매 구현 세션 ~50k 토큰 선독) - 모드가 아니라 테스크 상태. 토론/구현 라우팅을 없애고, 작업은 [탐색 중] ↔ [정의됨] 두 상태만 가진다. 경계는 발화 동사가 아니라 명확도 6칸(목표·대상 / 경계·불변식 / 기준소스 / 금지영역 / 검증 방법 / stakes)의 충족 여부다.
- 검증은 stakes 비례. stakes(틀렸을 때 손실·낯섦·모호성·불가역 — "변경 크기" 아님)가 외부 검색·codex 교차 검증·워커 분리·산출물 강도를 정한다. 균일 의무는 없되, 머지 전 최소 안전선은 stakes 무관 항상.
- 정책은 남기고 보상은 버린다. 사용자 권한·책임 경계(승인 게이트·기준소스 확정·금지영역)는 모델 무관 유지. 구모델 약점 보상 규칙(전부 읽기 강제·단계 상태머신·페르소나 라이브러리)은 제거. 규칙 증감은 측정(
measurement-log) 근거로만. - 절단은 구조로. 생성≠검증(테스트 설계는 구현 diff 미열람, 리뷰는 구현자와 분리)을 산문 규칙이 아니라 네이티브 서브에이전트의 컨텍스트 격리로 집행한다. 대규모 fan-out은 Workflow 도구(opt-in).
- learned.md·changelog.md는 제품이다. 사용자의 학습 산출물 — 프로세스 기록이 아니므로 간소화 대상이 아니다. learned = 전이 가능한 새 지식(트리거: 학습 가치) / changelog = 이번 diff의 의사결정 로그(트리거: 코드 구현 — 대안 비교·근거·리뷰 연습 포인트로 사용자의 코드 리뷰 능력을 훈련).
- 질문이 본체다 — "무엇을 보나"의 기준화. 시니어가 변경을 볼 때 도는 점검 차원(입력 검증·권한·정합성·동시성·예외·성능·장애·운영·보안·계약·도메인 규칙·모델링·비용·가시성 14개 + 표면별 팩)을
dimensions.md로 명시하고, 모든 정의됨 작업에서 전수 트리아지(해당/비해당 + 증거 인용)한다. stakes도 감이 아니라 활성 차원에서 도출된다. 프로세스는 이 질문들이 빠짐없이 던져지게 하는 장치다. (근거: docs/16, 인간용 질문 원문: docs/17·18)
구성 요소
claude-code-harness/
├── CLAUDE.md # 부트스트랩 (상시 ①)
├── core.md # 규칙 본체 (상시 ②) — 기준·테스크 상태·파이프라인·stakes·매핑·불변 정책
├── dimensions.md # 개발 차원 지도 (정의 게이트마다) — 14차원 트리아지 표 + 단계 질문(P/I/V) + stakes 도출 + 질문 보정 루프
├── dimensions-{batch,frontend,infra}.md # 확장팩 — surface detector가 조건부 로드 (각 ≤60줄)
├── playbooks/ # 조건부 (트리거 시만 읽음, 각 ≤80줄)
│ ├── orchestration.md # 메인=관리감독, 워커 위임·브리핑·절단 계약·렌즈·Workflow
│ ├── implementation.md # 설계 §0(렌즈 선적용·자문 4질문·높음은 설계 codex 검증)·읽기·범위 통제·예외처리 일관성·페이즈/커밋 규율
│ ├── review.md # 높음 stakes 병렬 듀얼 리뷰 루프 — Opus∥codex → 메인 종합 → codex 감사 → 수정·테스트 → 재리뷰(≤3) + 렌즈 4레벨·자원속도 체크 8문항
│ └── verification.md # stakes 비례 회귀·예외 경로 테스트·플로우 디버깅(API/서비스 간/비동기)·데이터 특칙
├── templates/
│ ├── task.md # 기본 산출물 1파일 (정의+계획+검증+기록)
│ ├── changelog.md # 코드 구현 작업마다 — 의사결정 로그 (J/M/G 전수 분류·대안 비교·근거 출처·라인별 해설·리뷰 연습 포인트)
│ ├── definition.md # 높은 stakes 정의 (경계×불변식×실패 의미론, 애매성 0)
│ ├── master-plan.md # 높은 stakes 다단계·대규모 (task.md 대체)
│ ├── phase.md # 페이즈 3파일 양식 (spec/changes/gate)
│ ├── learned.md (+example) # 학습 기록 풀 10항목 — 사용자 공부용 제품 산출물
│ └── measurement-log.md # 작업당 측정 1행 (규칙 증감의 근거 데이터)
├── hooks/ # git-guard(push·docs커밋 가드) + scope-guard(docs/code 혼합 경고)
├── settings.json # 훅 2종 배선
├── archive/2026-06-10-opus-harness/ # v1 전체 보존 (4문서·템플릿 16종·훅 5종·build/install)
└── docs/ # 설계 이력 (08~16 + HISTORY + plans) + 학습 제품 (17·18 개발 핵심질문)
작업 흐름
사용자 입력
│
├─ 산출물 변경 없음(토론·학습·설계) → 자유 진행 [탐색 중]
│ └─ 결론이 구현 입력이 되는 순간 실코드 재확인 / 고위험 결론은 확정 전 교차 검증
│
└─ 산출물 변경 → 정의 게이트(명확도 6칸 + 14차원 트리아지 + 사용자 합의) [정의됨]
→ 계획(사용자 승인) → 개발(설계: 렌즈 선적용 → 절단: 구현 ∥ 테스트설계 → 리뷰) → 검증(stakes 비례 + 활성 차원 렌즈) → 기록(측정 1행 + learned·changelog 판정)
| stakes | 외부 검색 | codex | 테스트설계/리뷰 | 산출물 |
|---|---|---|---|---|
| 낮음 | — | — | 셀프체크 | task.md (전 차원 비활성 자명 작업은 트리아지 1행 축약) |
| 중간 | 낯선 영역 | 반드시 1회 | 분리 패스 | task.md (+페이즈 절) |
| 높음 | 의무 | 계획+설계+최종 (페이즈 diff는 리뷰 루프가 겸함) | 테스트설계 별도 워커(diff 미열람) · 리뷰 = 병렬 듀얼 리뷰 루프(playbooks/review.md) | definition + task.md (다단계면 master-plan+phases) |
코드 구현이 있는 작업은 stakes 무관
changelog.md(리뷰 훈련용 의사결정 로그) 추가 작성.
설치 / 배포
배포 = repo 파일을 ~/.claude/로 복사 (v1의 build.sh/dist 이중 구조 폐지):
cp CLAUDE.md core.md dimensions*.md ~/.claude/
cp -r playbooks templates ~/.claude/
cp hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh
# settings.json은 기존 model 등 키를 보존하며 hooks 절만 반영
구 버전이 설치돼 있으면 먼저 ~/.claude/.backup-*/로 이동한다 (2026-06-10 배포 시 수행됨).
개발 히스토리
| Phase | 내용 |
|---|---|
| 1~7 | 기본 구조 → 스킬 75종 → 훅 → 모드 분리 4문서 체계 (2026-04) |
| 8 | 스킬 시스템 폐기 (~94k줄) — LLM이 아는 일반론의 외부 문서화는 비용>가치 |
| 9 | 30일 사용 분석 → git-guard·session-loader·외부 큐레이션 의무화 (2026-05-08) |
| 10 | codex(GPT-5.5) 교차 검증 전면 통합 — 전 단계 의무 (2026-05-14) |
| 11 | usage report 반영 — 페이즈 게이트·위험 승격·규모별 문서강도·데이터 특칙 (2026-06-05) |
| 12 | 멀티워커 — 리뷰 게이트(X4.5)·테스트설계 분리(X4-T)·페르소나 라이브러리 56인 (2026-06-08) |
| 13 | 실용성 재평가 — stakes·승격·최소안전선·측정 레이어, "성장할수록 줄어드는 비계" 원칙 (2026-06-09) |
| 14 | v2 전면 개편 (2026-06-10, Fable 5 전환) — 4문서+16템플릿+5훅 → core 1문서+조건부 playbook 3종+템플릿 7종+훅 2종. 모드 라우팅→테스크 상태 모델, codex 균일 의무→stakes 트리거, 산출물 7종→task.md 기본 1파일, 페르소나 라이브러리→렌즈 체크리스트 인라인(Workflow/Agent 네이티브 이관). learned.md는 제품 산출물로 보존. v1은 archive/로. 검증 4회: codex 초안 12지적 + playbook 7지적 + 최종 8지적, Fable 에이전트 시나리오 검증 16지적 — 전부 반영(오탐 1건 기각). 글로벌 ~/.claude/ 배포 완료 |
| 15 | 개발 차원 지도 (2026-06-10) — 사용자의 "개발 순환 프로세스 18항목" 정리를 하네스에 기준화. 성격 4분류(게이트 재료/조건부 차원/상시 렌즈/판정 입력 — docs/16) → dimensions.md 14차원 트리아지 표(전 stakes 전수·비활성에도 증거·불확실하면 light) + 단계 질문(P/I/V) + 확장팩 3종(배치/프론트/인프라). 칸2 5축 → 14차원, 칸6 stakes는 활성 차원에서 도출(하한→영향면 보정→누적 승격→낯섦·모호성 max). 경량 경로 폐지 (전 차원 비활성 자명 작업의 1행 축약만). 질문 보정 루프: 부적합은 task.md 기록 → 월 1회 측정 리뷰 승격분만 정본 반영. 검증 4중: codex 계획 검토 6절 + 최종(조건부 2건), Fable 시나리오 검증(집행 공백 8건)·구조 감사(12건) — 전부 머지 전 반영. 인간용 질문 원문 docs/17·18 |
| 16 | 병렬 듀얼 리뷰 루프 + 학습 산출물 changelog (2026-06-12) — ① 높음 stakes 리뷰를 루프로 교체: review packet(누적 diff, 동일 입력·보안 스캔) → Opus 워커 ∥ codex 동시 리뷰 → 메인 종합(근거는 packet 내로 제한) → codex 종합 감사 → 수정·테스트 → 재리뷰. 종료 = open 0 AND 신규 0, ≤3루프(초과 시 unresolved). 판단 렌즈 4레벨(API 예외 전파 / 메서드 내부 알고리즘·자원·속도 / 네이밍 도메인 직관성 / ORM 쿼리·실행계획) + 자원속도 체크 8문항·finding 자격 조건·상태 ledger. 같은 렌즈를 설계 단계에 선적용(implementation §0: 함수명·테스트 용이성·도메인 경계·대안 자문 + 높음은 설계 codex 검증 후 구현 진입). ② changelog.md 신설: 코드 구현 작업마다 의사결정 로그 — J/M/G 전수 분류, 대안 비교 표(실검토만), 근거 출처(없으면 "사후 추정"), 원본 스니펫+라인별 해설 표, 리뷰 연습 포인트. 목적 = 사용자의 코드 리뷰 능력 훈련, learned(전이 지식)와 스니펫 소유권 경계 고정. codex 검증 4회(루프: 계획 12+최종 5 / changelog: 계획 8+최종 3) 전부 머지 전 반영 |
상세: docs/HISTORY.md, v1 규칙 전문: archive/2026-06-10-opus-harness/, v2 설계 근거: docs/11~16 + core.md 변경 이력.