claude-code-harness, Claude Code 작업을 5단계 운영 루프로 묶는 오픈소스 공개

Chachamaru127가 깃허브에 공개한 claude-code-harness는 Claude Code 에이전트 작업이 채팅 속에 흩어지는 문제를 spec과 plan을 저장소의 진실 원천으로 삼아 통제하는 운영 루프다. 설치 이후 기본 동작이 "에이전트에게 코드를 부탁하기"에서 spec과 plan 작성, 승인된 슬라이스만 구현, 결과 검증, 독립 리뷰, PR/릴리스 증거 패키징의 순서로 바뀐다.

harness는 다섯 동사 스킬 plan, work, review, sync, release를 중심에 두고 슬래시 명령으로 흐름을 분리한다. /harness-setup이 프로젝트 가이드와 명령 표면, 훅, 점검을 한 번에 깔아 베이스라인을 만든다. /harness-plan은 요청을 spec.md와 Plans.md로 옮기며 범위, 수용 기준, 의존성, 미지, 중단 조건을 명문화한다. /harness-work는 승인된 한 슬라이스만 TDD와 검증으로 실행하고, /harness-work all 모드는 계획이 분명할 때 구현과 리뷰 경로를 한 번에 돈다.

리뷰와 릴리스 단계는 구현과 명시적으로 분리된다. /harness-review는 구현자와 별개로 결과를 평가하며, 주요 발견은 완료를 막는 차단 사항으로 처리된다. /harness-release는 릴리스 준비 상태와 CHANGELOG·태그 경계, 증거 패키징을 점검해 검증된 결과만 모아 묶는다. README는 "PR ready is not release ready"라며 PR 통과와 릴리스 가능성을 같은 기준으로 보지 말라고 강조한다.

저장소가 진실의 원천으로 작동하기 위한 두 가지 안전장치도 명문화됐다. 에이전트가 직접 보지 못한 데이터는 가짜로 채우지 않고 "unknown" 상태로 남는다. 또 "not_observed != absent" 원칙을 두어, 로컬 검증이 없는 항목은 "불가능"이 아니라 "이곳에서 입증되지 않음"으로만 표기한다.

호스트 도구별 지원 등급은 표로 못 박았다. Claude Code는 supported 등급으로 Claude 플러그인 마켓플레이스에서 설치한 뒤 /harness-setup만 실행하면 된다. Codex CLI와 OpenCode는 internal-compatible 등급으로 각각 scripts/setup-codex.sh와 scripts/setup-opencode.sh로 설치되지만 런타임 동등성은 보장하지 않는다고 밝혔다. Codex 앱, Cursor, GitHub Copilot CLI는 candidate 단계로 후보 검증과 PM 핸드오프 수준에 머물고, Antigravity CLI는 이번 단계에서 최종 사용자 설치 경로가 없다고 못 박았다.

요구사항은 가볍게 잡혔다. 지원 경로는 Claude Code v2.1 이상이며, 쓰기 권한이 있는 프로젝트 저장소만 있으면 된다. 가드레일 엔진은 Go로 작성돼 Node.js가 필요 없다. 옵션 컴패니언인 harness-mem을 연결하면 세션 간 프로젝트 메모리와 리콜을 쓸 수 있고, 정리는 명시적인 purge로만 가능하다.

큰 작업을 겨냥한 고급 기능은 별도 카탈로그로 분리됐다. Breezing은 Planner, Critic, Worker 역할로 팀 실행을 흉내내 더 긴 작업 목록을 처리하지만 여전히 plan 품질과 리뷰가 게이트가 된다. Codex companion review는 scripts/codex-companion.sh로 Codex의 스키마 기반 2차 의견을 받는 경로이며, raw codex exec은 companion 경로가 아니라고 못 박았다. OpenCode bootstrap은 harness 가이드를 OpenCode-호환 표면에 미러링하지만 런타임 동등성은 주장하지 않는다.

기존 사용자에게는 이주 진단이 먼저 권고된다. bin/harness doctor --migration-report는 오래된 Claude 플러그인 캐시, 중복 Codex 스킬, 옛 심볼릭 링크, OpenCode 백업 경로, harness-mem 상태를 데이터 삭제 없이 점검해 보고한다. 정리나 재설치 전에 반드시 먼저 돌리라고 README가 안내한다. harness는 Superpowers나 Hermes Agent 같은 외부 프로젝트의 지원 주장을 자동 승계하지 않고, 자체 부트스트랩과 트리거, 런타임, 릴리스 증거가 갖춰질 때만 해당 호스트의 등급이 올라간다.

라이선스는 MIT이며 README는 영어와 일본어로 함께 제공된다. 이슈와 PR을 받는다고 명시했고, 기여 가이드는 CONTRIBUTING.md에 정리돼 있다.