어떤 프로젝트든 명령 하나로 AI 코딩 하네스를 스캐폴딩하고, plan → construct → test
워크플로와 검증 게이트를 강제하는 CLI.
모델은 무엇을 만들지 정한다. 하네스는 언제·어디서·어떻게를 제어한다. 하네스는 모델을 똑똑하게 만드는 게 아니라 출력을 안정적으로 만든다.
크로스플랫폼(Windows / macOS / Linux), 외부 의존성 없음(표준 라이브러리만). 현재 버전: v0.5.0.
단계별 상세 설정·사용법은 docs/GUIDE.md 참고.
pipx install https://github.com/uhihi09/harness-cli/releases/download/v0.5.0/harness_cli-0.5.0-py3-none-any.whl치면 설치.- harness init하면 프로젝트에 바로 적용 가능.
- AI가 Claude.md보고 코드 짜라 하면 알아서 harness 명령어 치면서 하네스 적용 끝
1) 릴리스 휠로 설치 (권장)
pipx install https://github.com/uhihi09/harness-cli/releases/download/v0.5.0/harness_cli-0.5.0-py3-none-any.whl
2) 소스에서 설치 (개발)
git clone https://github.com/uhihi09/harness-cli && cd harness-cli
pip install -e ".[dev]"설치 후 확인:
harness --version
harness --helpcd my-project
harness init --hooks # 하네스 + Claude Code 자동 verify 훅까지
harness plan "STT 재시도 로직" # plan: .harness/plans/0001-... 작성
harness add F02 "실패 시 3회 재시도" "pytest tests/test_retry.py -q"
harness start F02 # active 로 (WIP=1 강제)
# ... Claude Code / Codex 로 F02 구현 (construct) ...
harness verify F02 # test 게이트 통과 시 자동으로 passing
harness check # 세션 종료 클린 상태 점검
harness record "재시도 e2e 통과" # 세션 기록| 명령 | 단계 | 하는 일 |
|---|---|---|
harness init [--force] [--hooks] [--local] [--orchestration] |
— | 하네스 파일 일체 생성, 스택 감지, .gitignore·기존 CLAUDE.md 처리. --hooks 면 Claude Code 훅까지, --local 이면 하네스 파일을 git에서 제외(개인용), --orchestration 이면 멀티에이전트 오케스트레이션 레이어 설치 |
harness hooks [--force] |
— | 기존 하네스 프로젝트에 Claude Code 훅 추가 (settings.json 안전 병합) |
harness plan "<제목>" |
plan | .harness/plans/000N-<slug>.md 계획 생성 |
harness add <id> "<동작>" "<검증명령>" |
— | 기능을 (동작·검증·상태) 삼중구조로 등록 |
harness start <id> |
— | 기능을 active 로 (WIP=1 초과 시 거부) |
harness block <id> ["<사유>"] |
— | 기능을 blocked 로 (WIP 슬롯 반환, 사유는 증거로 기록) |
harness unblock <id> |
— | blocked 기능을 not_started 로 되돌림 |
harness verify [<id>] |
test | 검증 게이트 실행. <id> 지정 시 통과하면 passing 자동 갱신 |
harness status |
— | 진행 상황 / 기능 상태 / WIP 경고 |
harness check |
— | 세션 종료 클린 상태 5차원 점검 (빌드·테스트·디버그마커·tmp) |
harness record "<메모>" |
— | .harness/records/<날짜>.md 에 타임스탬프 기록 |
AGENTS.md 에이전트 운영 매뉴얼(라우터) — 루트 고정 (도구 규약)
CLAUDE.md Claude Code 진입점 (AGENTS.md 를 가리킴) — 루트 고정
.harness/
config.json 감지된 스택 + 검증 명령 (단일 진실 원천)
feature_list.json 범위: WIP=1, (동작·검증·상태) 삼중구조
PROGRESS.md 진행 상황 (세션 연속성)
DECISIONS.md 설계 결정 로그
SESSION_CHECKLIST.md 클린 상태 5차원
init.sh 세션 시작 루틴 (설치→검증→상태)
verify.sh 검증 게이트 편의 스크립트 (정식 경로는 harness verify)
plans/ 버전+제목 계획 파일
records/ 세션/결정 기록
tmp/ 스크래치 (.gitignore 처리)
AGENTS.md·CLAUDE.md 만 루트에 둔다(도구가 루트에서 읽는 규약). 나머지 상태 파일·스크립트는 모두
.harness/안에 모아 루트를 깔끔하게 유지한다.
덮어쓰지 않는다. 내용을 보존하고 맨 아래에 AGENTS.md 를 따르라는 포인터 한 줄만
(마커로 중복 방지) 추가한다. 이미 AGENTS.md 를 참조하고 있으면 건드리지 않는다.
| 감지 파일 | stack | test 기본값 |
|---|---|---|
pyproject.toml+uv.lock |
python-uv | uv run pytest -q |
pyproject.toml / requirements.txt |
python | pytest -q |
pom.xml |
java-maven | mvn -q test |
build.gradle |
java-gradle | ./gradlew test |
package.json |
node | npm test |
| (그 외) | generic | TODO 자리표시자 |
검증 명령 중 # 로 시작하거나 빈 항목은 "미설정"으로 간주되어 게이트에서 건너뛴다.
.harness/config.json 의 verify 를 직접 편집해 프로젝트에 맞게 채우면 된다.
config.json 의 verify 명령을 lint → typecheck → test → e2e 순서로 실행한다.
앞 단계가 실패하면 즉시 멈춘다. bash 에 의존하지 않고 각 명령을 직접 실행하므로
Windows 에서도 동일하게 동작한다. 전부 통과해야만(그리고 <id> 를 줬다면) 기능이
passing 으로 바뀐다 — "코드가 멀쩡해 보임"이 아니라 실행 가능한 증거가 완료의 기준.
harness init --hooks (또는 기존 프로젝트에 harness hooks)는 .claude/ 에 훅을 깐다:
- Stop 훅 — Claude가 작업을 끝내려 할 때마다
harness verify를 자동 실행. 실패하면 멈추지 못하게 막고(exit 2) 실패 로그를 Claude에게 피드백해 스스로 고치게 한다. 무한 루프는stop_hook_active확인 + 카운터 상한(3회)으로 2중 방어. - SessionStart 훅 — 세션 시작 시 plan→construct→test 워크플로와
harness status를 컨텍스트로 주입.
기존 .claude/settings.json 이 있으면 hooks 키만 안전하게 병합하고 나머지 설정은 보존한다.
같은 command 가 이미 있으면 중복 추가하지 않는다.
설치 후: chmod +x .claude/hooks/*.sh → Claude Code 재시작 → /hooks 로 확인.
훅은 harness 가 PATH에 있어야 동작하며, Windows에서는 Git Bash를 사용한다.
이렇게 하면 사용자가 harness verify 를 직접 칠 필요 없이 Claude Code가 자동으로 게이트를 통과시킨다.
harness init --orchestration 은 멀티에이전트 코딩 워크플로를 깐다:
.harness/config.json의orchestration블록 — 역할→모델 매핑 (lead/coder/reviewer/fallback/max_parallel, 전부 교체 가능)..claude/agents/에 에이전트 정의 3개 (lead·coder·reviewer)..harness/ORCHESTRATION.md— 리드가 따르는 프로토콜.
리드(기본 Fable 5)가 기능을 파일 소유권이 겹치지 않는 레인으로 나눠 코더 여러 개를
병렬로 굴리고, 다른 모델(기본 Sonnet)이 각 레인 diff 를 독립 리뷰한다. 객관 게이트
(harness verify)가 먼저이고 리뷰는 그 위에 얹힌다 — "리뷰 OK"가 테스트 통과를 대체하지 않는다.
harness 는 모델을 호출하지 않고 판만 깐다(구동은 Claude Code).
기본적으로 하네스 파일(AGENTS.md, feature_list.json, PROGRESS.md 등)은 커밋되어야 한다 — 저장소가 단일 진실 원천이고, 그래야 다른 PC·세션·팀원이 컨텍스트를 이어받는다.
혼자 쓰는 토이 프로젝트라 git에 올리고 싶지 않다면:
harness init --local # 하네스 파일을 .gitignore 에 추가 (이 PC에서만)harness 가 이번 실행에서 새로 만든 파일만 무시 목록에 넣는다. 직접 작성해 두었던
AGENTS.md/CLAUDE.md 나 기존 .claude/ 설정은 건드리지 않는다(.claude/ 가 이미 있으면
harness 가 추가한 훅 스크립트만 무시). --local 로 깐 하네스는 그 PC·그 클론에만 존재하므로,
다른 환경에서는 다시 harness init 해야 한다.
pip install -e ".[dev]"
pytest -qMIT