문제: 하네스 v2(분야 전문가 협업)를 v1과 견주려면 같은 과제를 판마다 돌린 실행을 한 줄씩 남기고 비교해야 하는데, 장부에는 예측·실측만 있다. 실측도 시간·호출·토큰뿐이라 모든 세션의 시작 비용(첫 호출 입력 토큰)과 서브에이전트가 메인에 돌려준 양(컨텍스트 비용)을 볼 수 없다. 고른 방법: - usage에 start_context(본 기록 첫 호출), subagents·subagent_output_tokens, agent_calls(Agent·Task 호출), agent_return_chars를 더한다. 반환 글자는 Agent 도구 결과와, 백그라운드 결과가 들어오는 대기열 알림 (queued_command의 <agent-message·<task-notification 머리)을 센다. 2026-11-11 세션 기록에서 백그라운드 결과가 tool_result가 아니라 알림으로 오는 것을 확인했다. - 새 줄 종류 eval(arm·case 필수)과 명령 eval(초안)·compare(과제·판별 중앙값, 마지막 판/첫 판 비율). precedents는 eval만 있는 작업을 세지 않는다. - Stop 훅이 0.2.0이 저장한 상태 파일을 이어 읽어도 깨지지 않게 새 칸은 setdefault로 채운다. - 버린 대안: eval을 actual 줄에 arm 칸으로 붙이기. 같은 작업의 판 여럿이 by_task에서 덮이고 회고 대기 계산에 섞인다. 위험: 대기열 알림 모양은 앱 내부 형식이다. 바뀌면 agent_return_chars가 조용히 줄어든다(시험이 지금 모양을 고정한다). 검증: python3 -m unittest discover -s plugins/harness/tests → 24건 통과 (알려진 실패 1). 조건을 하나씩 끈 변이 9개가 모두 시험에 걸렸다.
claude-harness
새 프로젝트에 바로 쓰는 Claude Code 작업 환경(하네스)이다. 프로젝트와 상관없는 공통 동작은 플러그인으로 받아 버전으로 갱신하고, 프로젝트마다 다른 파일은 뼈대 복사로 시작한다. 이 repo가 곧 플러그인 마켓이다.
claude-harness ─┬─ 플러그인 harness ──(claude plugin install)──> 모든 세션의 훅·스킬
└─ template/ ──(scripts/new-project.sh)──> 새 repo의 AGENTS.md·설정·verify.sh·빈 양식
무엇이 들었나
| 폴더 | 하는 일 | 먼저 읽을 곳 |
|---|---|---|
plugins/harness/ |
공통 플러그인: 훅 넷과 스킬 셋 | 아래 「플러그인」 |
template/ |
새 프로젝트에 복사하는 뼈대 | 아래 「새 프로젝트」 |
scripts/ |
new-project.sh(뼈대 복사), check.sh(이 repo 검증) |
각 파일 머리 주석 |
docs/ |
이 repo에서 정한 것, 이 repo의 예측·실측 장부 | docs/README.md |
tests/ |
템플릿·new-project·verify 운반부·매니페스트 시험 |
플러그인 harness
| 장치 | 때 | 하는 일 |
|---|---|---|
| H12 차단 | Bash 실행 직전 | 되돌릴 수 없는 명령을 막는다: 호스팅 원격으로 force push·--mirror·보호 브랜치 지우기, 작업 폴더·/tmp 밖이나 너무 넓은 rm -r, DB·볼륨·migration 삭제(DROP·TRUNCATE, flyway clean, -p 없는 compose down -v, volume rm, kubectl delete pvc·ns). ssh '…' 안도 본다 |
| N4 알림 | 파일을 쓴 직후 | 비밀 값처럼 보이는 것(개인 키, 토큰, 값이 있는 password 등)을 몇 줄로 알린다. 막지 않는다 |
| 장부 기록 | 세션 시작·턴 끝 | 세션 id와 기록 경로를 ~/.claude/harness/sessions.jsonl에, 누적 실측(시간·호출·토큰)을 ~/.claude/harness/usage/<세션>.json에 쓴다. 출력이 없어 컨텍스트 비용이 0이다 |
| 회고 넛지 | 세션 시작 | repo 장부에 회고 안 한 빗나간 예측이나 효과 판정할 개선이 있으면, repo마다 하루 한 번 한 줄로 알린다. 없으면 출력이 없다 |
estimate 스킬 |
착수할 때·끝날 때 | 착수 보고와 p30·p50·p80 예측, 끝의 실측을 repo 장부 docs/ledger/estimates.jsonl에 |
retro 스킬 |
회고 | 틀린 예측의 이유를 나누고 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나. 고친 뒤 실측 2건으로 효과를 판정하고, 없으면 되돌린다 |
techdebt 스킬 |
세션 끝 | 이번 diff가 더한 TODO·skip·검사 끄기, 남은 파일·worktree·브랜치 |
- 훅은 Python 3 표준 라이브러리만 쓴다. 차단은 H12 하나이고, 나머지는 실패해도 작업을 막지 않는다.
- H12의 판정은 소유자 기계의 전역 훅과 같다. 사용자 전역
~/.claude/settings.json에guard_bash.py … H12가 이미 등록돼 있으면 플러그인 H12는 아무것도 하지 않는다(두 번 막지 않는다). - 권한 deny(예:
.env읽기 금지)는 플러그인으로 나눠 줄 수 없다. 그래서template/.claude/settings.json에 둔다.
받기
claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git
claude plugin install harness@claude-harness
새 세션부터 훅과 스킬이 돈다. 공개 repo라 인증 없이 받는다. 갱신은 plugin.json의 version이 오른 뒤 claude plugin marketplace update claude-harness와 claude plugin update harness@claude-harness다.
템플릿으로 만든 프로젝트는 .claude/settings.json이 마켓과 플러그인을 이미 적어 둔다. 대화형 Claude Code는 그 폴더를 처음 믿을 때 설치를 묻는다(공식 문서의 설명이고, 이 repo에서 직접 보지는 않았다). 비대화형(claude -p)은 묻지도 설치하지도 않는다(2026-11-08 확인). 그때는 그 폴더에서 위 두 명령에 --scope project를 붙여 한 번 돌린다. 설정 파일 내용은 바뀌지 않는다.
새 프로젝트
scripts/new-project.sh ~/workspace/order-service --description "주문을 받는 서비스다."
복사되는 것: AGENTS.md(루트 지침 양식, 40줄 이하), CLAUDE.md(@AGENTS.md와 Claude 전용 줄), .claude/settings.json(.env deny, 하네스 플러그인 켜기), scripts/verify.sh(검증 진입점 뼈대와 원격 운반부), docs/vision.md·docs/problem-statement.md·docs/adr/0000-template.md(빈 양식), docs/ledger/(빈 장부와 형식 설명), .gitattributes·.gitignore. 이름을 바꾸고 git init까지 하며 커밋은 하지 않는다.
있는 프로젝트에 붙이기
- 플러그인만 켜려면
template/.claude/settings.json의extraKnownMarketplaces·enabledPlugins를 그 repo의.claude/settings.json에 합친다. - 장부를 쓰려면
template/docs/ledger/와.gitattributes한 줄을 복사한다. - 루트 지침은
template/AGENTS.md의 절 순서를 참고해 그 repo의 것을 줄인다(덮어쓰지 않는다).
검증
scripts/check.sh
플러그인 시험(H12·N4·장부·techdebt), 템플릿 시험(new-project 결과, verify.sh docs, 가짜 ssh로 원격 운반부), claude plugin validate --strict를 돈다.
규칙과 기여
규칙은 AGENTS.md다. 플러그인 동작을 바꾸면 version을 올린다. 설계 근거는 design-docs harness/01-harness-design.md(11·13절)이고, 이 repo에서 따로 정한 것은 docs/README.md다.