어떤 프로젝트든 명령 하나로 AI 코딩 하네스를 스캐폴딩하고, plan → construct → test
워크플로와 검증 게이트를 강제하는 CLI.
모델은 무엇을 만들지 정한다. 하네스는 언제·어디서·어떻게를 제어한다. 하네스는 모델을 똑똑하게 만드는 게 아니라 출력을 안정적으로 만든다.
크로스플랫폼(Windows / macOS / Linux), 외부 의존성 없음(표준 라이브러리만). 현재 버전: v0.6.0.
단계별 상세 설정·사용법은 docs/GUIDE.md 참고.
pipx install https://github.com/uhihi09/harness-cli/releases/download/v0.6.0/harness_cli-0.6.0-py3-none-any.whl치면 설치.- harness init하면 프로젝트에 바로 적용 가능.
- AI가 Claude.md보고 코드 짜라 하면 알아서 harness 명령어 치면서 하네스 적용 끝
1) 릴리스 휠로 설치 (권장)
pipx install https://github.com/uhihi09/harness-cli/releases/download/v0.6.0/harness_cli-0.6.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 를 import) — 루트 고정
.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 import 한 줄만(마커로 중복 방지) 추가한다.
이미 @AGENTS.md 를 import 하고 있으면 건드리지 않는다. Claude Code 는 AGENTS.md 를 직접 읽지 않으므로
(공식 문서: "Claude Code reads CLAUDE.md, not AGENTS.md") 이 import 가 있어야 워크플로 규칙이 세션에 실린다.
백틱 안의 AGENTS.md 언급은 import 가 아니다.
| 감지 파일 | 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) 실패 로그를 다음 지시로 돌려줘 스스로 고치게 한다. 훅은 입력 JSON 의cwd에서 돈다 — worktree 세션(--worktree, 데스크톱 앱 병렬 세션)이면 그 worktree 를 검증한다. 같은 차단 사슬에서 3회 연속 실패하면 막기를 멈추고 사람에게 넘긴다 (Claude Code 자체 상한CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, 기본 8회가 뒤에 한 겹 더 있다). - SessionStart 훅 — 세션 시작/재개/컴팩트 시
harness status를 컨텍스트로 주입. 워크플로 규칙은 CLAUDE.md 의@AGENTS.mdimport 가 담당한다.
기존 .claude/settings.json 이 있으면 hooks 키만 안전하게 병합하고 나머지 설정은 보존한다.
같은 스크립트를 가리키는 항목이 이미 있으면 중복 추가하지 않고, 0.5.0 이하가 만든 exec 폼(args: [])
항목은 셸 폼으로 교체한다.
설치 후 Claude Code 를 재시작하고 /hooks 로 확인한다(실행 권한은 harness 가 준다).
훅은 harness 가 PATH에 있어야 하고, JSON 파싱에 python3(또는 python)을 쓴다.
셸 폼으로 등록하므로 Windows 에서는 Git Bash 가 실행한다 — Git for Windows 가 필요하다.
이렇게 하면 사용자가 harness verify 를 직접 칠 필요 없이 Claude Code가 자동으로 게이트를 통과시킨다.
harness init --orchestration 은 멀티에이전트 코딩 워크플로를 깐다 (훅 설치를 포함한다):
.harness/config.json의orchestration블록 — 역할→모델 매핑 +max_parallel+isolation. 기본값은 별칭lead=fable,coder=fable,reviewer=sonnet— Claude Code 가 최신 세대(Fable 5.1 / Sonnet 5)로 풀어준다. 전체 ID(claude-opus-5등)도 된다..claude/agents/에 에이전트 정의 3개. 코더는isolation: worktree로 격리되고 frontmatter Stop 훅 (서브에이전트에서는 SubagentStop)으로harness verify게이트를 강제받는다. 리뷰어는disallowedTools로 편집이 막힌다..claude/settings.json에env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(=max_parallel) 와worktree.baseRef: "head"를 (없을 때만) 넣는다..harness/ORCHESTRATION.md— 리드가 따르는 프로토콜 (레인 분할 → 코더 병렬 → 리뷰 → 순차git merge).
리드가 기능을 파일 소유권이 겹치지 않는 레인으로 나눠 코더 여러 개를 병렬로 굴리고, 다른 모델이
각 레인 diff 를 독립 리뷰한다. 객관 게이트(harness verify)가 먼저이고 리뷰는 그 위에 얹힌다 —
"리뷰 OK"가 테스트 통과를 대체하지 않는다. harness 는 모델을 호출하지 않고 판만 깐다(구동은 Claude Code).
에이전트 정의는 config 에서 매번 재생성되므로 config 를 고쳐라(파일 직접 편집은 덮어써진다).
refusal 폴백은 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