Chachamaru127/claude-code-harness

Claude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle

Claude Code Harness – 체계적인 AI 기반 개발 루프

무엇인가요 – Claude Code(또는 호환되는 에이전트인 Codex, Cursor, Grok 등)가 계획, 구현, 검토, 동기화, 배포에 이르기까지 소프트웨어 개발 전 주기를 담당할 수 있는 Go 네이티브 플러그인입니다. 고수준의 의도(예: "README 온보딩 흐름 개선")를 제시하면, 해서스는 구체적인 사양(spec.md, Plans.md)으로 변환하고, 선택된 AI 모델로 코드를 생성하며, 출력을 검증한 후 최종적으로 깨끗한 릴리스를 패키징합니다. 모든 단계는 명시적인 인간 승인을 통해 제어되므로, 완전 자율적인 개발자가 아니라 안전을 우선시하는 오케스트레이션 계층입니다.

핵심 개념 및 워크플로우

단계	명령어	기능	인간 승인
계획	`/harness‑plan <의도>`	범위, 수용 기준, 종속성, 불확실 요소, 중단 조건을 설명하는 사양(`spec.md`)과 작업 목록(`Plans.md`)을 생성합니다.	코드 생성 전에 생성된 계약을 승인하거나 수정해야 합니다.
작업	`/harness‑work [작업	all]`	승인된 작업을 적절한 모델(Claude Sonnet 5로 일반 작업, GPT-5.6 Luna로 고처리량 "Breezing" 등)을 사용해 실행합니다. 개별 또는 팀 작업을 처리하고, 필요한 테스트를 실행하며, 설정 가능한 수정 한도까지 반복합니다.
검토	`/harness‑review`	별도의 리뷰 모델(Claude Sonnet 5, xhigh 노력 수준)을 실행하여 변경 사항을 검사하고 추가 검증을 수행하며 주요 발견 사항을 보고합니다.	완료를 방해하는 발견 사항은 다음 단계로 진행하기 전에 해결해야 합니다.
동기화	`/harness‑sync`	현재 리포지토리 상태와 원래 계획을 비교하여 편차를 표시하고 계획 상태를 업데이트합니다.	필요 시 재계획을 확인해야 합니다.
릴리스	`/harness‑release`	검증된 변경 사항을 변경 로그에 패키징하고, git 태그를 생성하며, 릴리스를 게시합니다.	프리플라이트 체크리스트가 통과하지 않으면 릴리스가 중단됩니다.

루프는 /harness‑loop로 자동 반복되며, work-review-sync를 반복하여 정지 조건(예: 최대 사이클 수, 실행 가능한 작업 없음)에 도달할 때까지 진행됩니다.

안전성 및 가드레일

이중 보호 – 가벼운 Go 엔진이 런타임 바닥선(5개 항목: 요금, 네트워크 출력, 시크릿 읽기, 프로덕션 배포, 파괴적 작업)을 강제하고, 더 풍부한 가드레일(R01-R16)이 위험한 작업에 대해 거부, 경고, 또는 확인을 요구합니다.
명시적 승인 – main에 푸시하거나 보호된 경로에 쓰기와 같은 사전 승인이 필요한 작업은 계획 시점에 만료 기한, 범위, 사용 제한과 함께 기록됩니다.
미지 데이터 처리 – 모델이 본 적 없는 데이터는 unknown으로 표시되며, 침묵하는 환각을 방지합니다.
세션 로스터 – 여러 에이전트가 동일한 리포지토리에서 작업할 경우, 로컬 로스터가 활성 세션을 표시하고 검증된 메시지 전달을 가능하게 하며, 선택적으로 콘텐츠 검증을 제공합니다.
비엔지니어 뷰 – 3개의 단일 페이지 HTML 대시보드(계획 요약, 진행 상황, 수용)를 통해 스테이크홀더가 코드를 읽지 않고도 작업을 검토할 수 있습니다.

설치 (30초)

# Claude Code(또는 지원되는 호스트 내부에서)
claude /plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup

다른 호스트(Codex CLI, Cursor, Grok)의 경우 README의 "도구별 설치" 표를 참조하세요. 각 도구는 플러그인을 추가하고 /harness‑setup를 실행하는 작은 쉘 스크립트를 제공합니다.

일반적인 사용 사례

의도 정의 – /harness‑plan "중복 주문 수정; 동일한 주문은 한 번만 저장되어야 합니다."
사양 승인 – spec.md/Plans.md를 검토하고 수용 기준을 확인합니다.
구현 실행 – /harness‑work all (또는 /harness‑work 3로 단일 작업을 지정).
자동 테스트 및 수정 – 모델이 테스트를 실행하고 실패를 보고하며, 설정된 수정 한도까지 반복합니다.
독립적 검토 – /harness‑review는 별도의 감사 보고서를 생성하며, 주요 발견 사항은 릴리스를 차단합니다.
동기화 및 릴리스 – /harness‑sync로 계획이 현실과 일치하는지 확인한 후, /harness‑release로 태그된 릴리스와 생성된 변경 로그를 만듭니다.

모델 라우팅 및 노력 수준

역할	기본 모델	노력
어려운 결정 / 조언	Claude Fable 5.1	high
일반 구현	Claude Sonnet 5	medium
전용 리뷰어	Claude Sonnet 5	xhigh
Codex 작업 및 리뷰	GPT-6 astra / GPT-5.6 luna	xhigh / max

모든 역할이나 노력 수준은 수동으로 재정의할 수 있으며, 도구는 명시적 선택을 존중합니다.

프로젝트 상태 및 커뮤니티

라이선스 – MIT
지원되는 호스트 – Claude Code (v2.1+), Codex CLI, Cursor, Grok (모두 지원됨). 기타 도구는 후보 또는 미래로 표시됨.
문서 – 온보딩, 설치 경로, 안전성 동등성, 모델 정책, 고급 기능(Breezing, harness-loop, harness-mem 등)을 포함한 광범위한 문서.
기여 – 이슈 및 PR을 환영합니다. CONTRIBUTING.md를 참조하세요.

TL;DR

Claude Code Harness는 인간 검토로 각 주요 단계를 제어하는 안전 우선의 오케스트레이션 플러그인입니다. Claude 기반 에이전트(또는 호환 가능한 LLM)를 사용해 리포지토리의 변경 사항을 계획, 코드 작성, 검증, 배포할 수 있으며, 명확하고 반복 가능한 루프, 강력한 가드레일, 다중 도구 지원을 제공하여 AI 보조 개발을 강력하고 통제 가능한 것으로 만듭니다.