Chachamaru127/claude-code-harness

계획(Plan). 실행(Work). 검토(Review). 배포(Ship).

Codex 및 OpenCode를 위한 제한된 경로를 포함한, Claude Code를 위한 규율 있는 전달 루프(delivery loop).

English | 日本語

Claude Code는 강력하지만, 가공되지 않은 에이전트 작업은 표류하기 쉽습니다. 계획은 채팅 속에 머물고, 테스트는 선택 사항이 되며, 검토는 너무 늦게 이루어지고, 출시 증거는 기억에 의존해 다시 구축되어야 합니다. Harness는 이를 하나의 반복 가능한 운영 경로(operating path)로 전환합니다.

설치 후, 기본 방식은 "에이전트에게 코딩을 요청하는 것"에서 다음과 같이 변경됩니다:

• 사양(spec)과 계획(plan) 작성,
• 승인된 슬라이스(slice)만 구현,
• 결과 검증,
• 독립적인 검토,
• PR(Pull Request) 또는 출시를 위한 증거 패키징.

신규 사용자는 이미 사용 중인 도구부터 시작해야 합니다. 기존 사용자는 정리 또는 재설치 전에 마이그레이션 보고서(migration report)를 실행해야 합니다.

경로	시작
신규 사용자	도구 우선 온보딩 (Tool-first onboarding)
...

claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
...

다음 명령: /harness-plan 실행

작은 요청과 함께.

/harness-plan Improve the README onboarding flow (README 온보딩 흐름 개선)

• 사용 중인 도구 경로를 통해 설치합니다.
• /harness-setup 또는 그에 상응하는 설정 스크립트를 실행합니다.
• 작은 요청과 함께 /harness-plan을 실행합니다. Harness가 사용자가 확인할 수 있도록 spec.md와 Plans.md 초안을 작성해 줍니다. 작은 오타, 문서, 상태 업데이트는 가볍게 유지됩니다.
• 생성된 계약(contract)을 승인하거나 원하는 수정 사항을 답장합니다.
• 승인된 가장 작은 작업을 실행합니다. 예: /harness-work 1.1.1.
• /harness-review를 실행하고 검증 출력 결과(verification output)를 보관합니다.

당신의 역할은 계획을 직접 작성하는 것이 아닙니다. 실행이 계속되기 전에 생성된 계약을 승인하거나 수정하는 것입니다.

Harness는 에이전트 작업 주변에 신뢰할 수 있는 단일 출처(source-of-truth) 루프를 추가합니다. 5가지 동사 기술(verb skills)이 그 범위를 작게 유지합니다: 계획(plan), 실행(work), 검토(review), 동기화(sync), 출시(release).

• 당신은 일반적인 언어로 결과를 설명합니다.
• /harness-plan은 범위(scope), 수락 기준(acceptance criteria), 미지의 요소(unknowns), 중단 조건(stop conditions)을 포함하여 spec.md와 Plans.md를 초안 작성하거나 업데이트합니다.
• 중요도가 높은 계획 기록은 team_validation_mode를 사용합니다.

그리고 spec/Plans 정렬, 메모리 재사용 (memory reuse), 제품 적합성 (product fit), 보안 적합성 (security fit), 그리고 실제 작동 여부 (works-in-practice)를 위해 팀/하위 에이전트 (team/sub-agent) 또는 수동 통과 (manual-pass) 관점을 통해 계획을 검증합니다. - Harness는 해당 파일들을 신뢰할 수 있는 단일 원천 (source of truth)으로 취급합니다. 에이전트가 확인하지 않은 데이터는 조용히 지어내는 대신 unknown 상태로 유지됩니다.

/harness-work는 TDD 및 검증을 통해 승인된 슬라이스 (slice)를 구현합니다.
/harness-review는 구현과 리뷰를 분리합니다.
/harness-release는 검증된 증거만을 패키징합니다.

명령 (Command)	내부 동작
/harness-setup	워크플로우가 하나의 알려진 베이스라인 (baseline)에서 시작할 수 있도록 프로젝트 가이드, 명령 인터페이스 (command surfaces), 훅 (hooks) 및 체크 사항을 설치합니다.
/harness-plan	의도를 범위 (scope), 수락 기준 (acceptance criteria), 의존성 (dependencies), 미지의 사항 (unknowns), 중단 조건 (stop conditions) 및 중요도가 높은 계획 검증을 포함하는 spec.md 및 Plans.md로 변환합니다.
/harness-work	승인된 하나의 작업 또는 범위를 실행하고, 필요 시 테스트를 추가하며, 검증을 실행하고, 작업이 계획 내에서 유지되도록 합니다.
/harness-work all	승인된 계획을 구현 및 리뷰 경로를 통해 실행합니다; 계획이 명확해지고 리포지토리 (repo) 베이스라인이 알려진 후에 사용하십시오.
/harness-review	구현과 별도로 결과를 리뷰하며, 주요 발견 사항을 차단 요소 (blockers)로 취급합니다.
/harness-release	구현 및 리뷰가 완료된 후, 출시 준비 상태, CHANGELOG/태그 (tag) 경계 및 증거 패키징을 확인합니다.
bin/harness doctor --migration-report	데이터를 삭제하지 않고 오래된 플러그인 캐시 (plugin caches), Codex 기술 (skills), OpenCode 파일, 심볼릭 링크 (symlinks) 및 메모리 상태를 조사합니다.

단계 (Stage)	출력물 (Output)	게이트 (Gate)
조사 (Investigate)	증거 및 미확인 사항 (Evidence and unknowns)	관찰되지 않은 데이터를 주장으로 승격하지 말 것.
계획 (Plan)	spec.md + Plans.md	사용자가 생성된 계약(contract)을 승인하거나 수정함.
작업 (Work)	코드 및 테스트	작업 지침에 명시된 경우 TDD (테스트 주도 개발) 필수.
검토 (Review)	독립적 판결 (Independent verdict)	주요 발견 사항은 완료를 차단함.
PR	증거 팩 (Evidence pack)	PR 준비가 곧 릴리스 준비를 의미하지는 않음.
릴리스 (Release)	태그/릴리스 아티팩트 (Tag/release artifacts)	릴리스 프리플라이트 (Release preflight)가 릴리스 경로에서 통과해야 함.

도구 (Tool)	티어 (Tier)	경로 (Route)
Claude Code	supported	Claude 플러그인 마켓플레이스, 그 다음 /harness-setup .
Codex CLI	internal-compatible	scripts/setup-codex.sh --user ; 직접적인 플러그인 스모크 테스트는 별도로 추적됨.
Codex app	candidate	후보(Candidate) 스모크 테스트만 수행; Codex CLI 증거를 재사용하지 말 것.
OpenCode	internal-compatible	scripts/setup-opencode.sh ; 런타임 패리티 (runtime parity)는 보장되지 않음.
Cursor	candidate	PM 인계 또는 어댑터 연구 전용.
GitHub Copilot CLI	candidate	수동 프로필 연구 전용.
Antigravity CLI	future/unsupported	이 단계에서는 최종 사용자 설치 경로가 없음.

기존 설정을 변경하기 전에 bin/harness doctor --migration-report 를 실행하십시오.
이 보고서는 아무것도 삭제하지 않고 오래된 Claude 플러그인 캐시, 중복된 Codex 기술 (skills), 오래된 심볼릭 링크 (symlinks), OpenCode 백업 경로 및 harness-mem 상태를 목록화합니다.

Harness는 후보 경로를 설명할 수 있지만, Superpowers, Hermes Agent 또는 기타 프로젝트로부터 지원 주장 (support claims)을 상속받지는 않습니다. 호스트는 Harness가 자체적인 부트스트랩 (bootstrap), 트리거 (trigger), 런타임 (runtime) 및 릴리스 증거를 가질 때에만 상향 이동합니다.

not_observed != absent

: 로컬 증거가 누락되었다는 것은 "여기서 증명되지 않음"을 의미하며, "불가능함"이나 "지원됨"을 의미하지 않습니다.

• 지원되는 Claude 경로를 위한 Claude Code v2.1+.
• 로컬 설정을 위한 쓰기 권한이 있는 프로젝트 리포지토리.
• Go 네이티브 가드레일 엔진 (Go-native guardrail engine)을 위해 Node.js는 필요하지 않음.
• 구성되어 있고 상태가 양호할 경우 세션 간 메모리를 위한 선택적 harness-mem.

기본 트리거 경로(basic trigger path)가 확인된 후에 다음 기능들을 사용하십시오.

기능 (Capability)	추가되는 사항	경계 (Boundary)
Breezing	더 큰 작업 목록을 위한 Planner/Critic/Worker 스타일의 팀 실행.	여전히 계획의 품질과 검토(review)에 의해 제한됨.
Codex companion review	scripts/codex-companion.sh를 통한 스키마 기반(Schema-backed) Codex의 제2 의견 제공.	가공되지 않은(Raw) codex exec는 Harness companion 경로가 아님.
OpenCode bootstrap	Harness의 가이드를 OpenCode 호환 인터페이스로 미러링.	실제 런타임(runtime)의 동일성(parity)을 보장하지는 않음.
harness-mem	세션 간 프로젝트 범위의 메모리 및 회상(recall).	선택적 동반 기능; 삭제(purge)는 여전히 명시적으로 이루어짐.

리소스 (Resource)	설명
Tool-first onboarding	호스트 도구별 시작 방법.
...

이슈(Issues)와 PR(Pull Requests)을 환영합니다. CONTRIBUTING.md를 참조하세요.

MIT License. LICENSE.md를 참조하세요.