convez.ai
SkillDevOps & InfraestruturaAvançado
junhyeong9812

Claude Code Harness v2

junhyeong9812/claude_skill_study

Orquestração Claude com estados, dimensões de risco e validação proporcional

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema 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_study

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 dias
Versão
—
Issues abertas
0
Contribuidores
1

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의 "절차를 촘촘히 강제하는 외골격"을 **"판단 기준을 제공하는 단일 핵심 문서 + 강제가 필요한 곳만 훅/네이티브 도구"**로 전면 개편한 버전이다.


핵심 철학

  1. 상시 선독은 core 하나. 세션마다 읽는 규칙은 CLAUDE.md(11줄, 부트스트랩) + core.md(~200줄)뿐. 나머지는 트리거 시에만 읽는 조건부 문서다. (v1: 매 구현 세션 ~50k 토큰 선독)
  2. 모드가 아니라 테스크 상태. 토론/구현 라우팅을 없애고, 작업은 [탐색 중] ↔ [정의됨] 두 상태만 가진다. 경계는 발화 동사가 아니라 명확도 6칸(목표·대상 / 경계·불변식 / 기준소스 / 금지영역 / 검증 방법 / stakes)의 충족 여부다.
  3. 검증은 stakes 비례. stakes(틀렸을 때 손실·낯섦·모호성·불가역 — "변경 크기" 아님)가 외부 검색·codex 교차 검증·워커 분리·산출물 강도를 정한다. 균일 의무는 없되, 머지 전 최소 안전선은 stakes 무관 항상.
  4. 정책은 남기고 보상은 버린다. 사용자 권한·책임 경계(승인 게이트·기준소스 확정·금지영역)는 모델 무관 유지. 구모델 약점 보상 규칙(전부 읽기 강제·단계 상태머신·페르소나 라이브러리)은 제거. 규칙 증감은 측정(measurement-log) 근거로만.
  5. 절단은 구조로. 생성≠검증(테스트 설계는 구현 diff 미열람, 리뷰는 구현자와 분리)을 산문 규칙이 아니라 네이티브 서브에이전트의 컨텍스트 격리로 집행한다. 대규모 fan-out은 Workflow 도구(opt-in).
  6. learned.md·changelog.md는 제품이다. 사용자의 학습 산출물 — 프로세스 기록이 아니므로 간소화 대상이 아니다. learned = 전이 가능한 새 지식(트리거: 학습 가치) / changelog = 이번 diff의 의사결정 로그(트리거: 코드 구현 — 대안 비교·근거·리뷰 연습 포인트로 사용자의 코드 리뷰 능력을 훈련).
  7. 질문이 본체다 — "무엇을 보나"의 기준화. 시니어가 변경을 볼 때 도는 점검 차원(입력 검증·권한·정합성·동시성·예외·성능·장애·운영·보안·계약·도메인 규칙·모델링·비용·가시성 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이 아는 일반론의 외부 문서화는 비용>가치
930일 사용 분석 → git-guard·session-loader·외부 큐레이션 의무화 (2026-05-08)
10codex(GPT-5.5) 교차 검증 전면 통합 — 전 단계 의무 (2026-05-14)
11usage report 반영 — 페이즈 게이트·위험 승격·규모별 문서강도·데이터 특칙 (2026-06-05)
12멀티워커 — 리뷰 게이트(X4.5)·테스트설계 분리(X4-T)·페르소나 라이브러리 56인 (2026-06-08)
13실용성 재평가 — stakes·승격·최소안전선·측정 레이어, "성장할수록 줄어드는 비계" 원칙 (2026-06-09)
14v2 전면 개편 (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 변경 이력.

Ver o original no GitHub

Bom para

Relacionados