문제: 새 프로젝트마다 루트 지침, Claude Code 설정, 검증 진입점, 비전·
문제 정의 양식, 장부를 손으로 다시 만든다. 플러그인으로는 루트 문서와
권한 deny를 나눠 줄 수 없다(플러그인 CLAUDE.md·권한은 읽히지 않는다).
고른 방법: 공통 동작은 플러그인, 프로젝트 파일은 template/ 복사로
나눈다(결정 Q15). scripts/new-project.sh가 template/을 빈 폴더에 복사하고
이름·설명·마켓 주소를 바꾼 뒤 git init까지 한다. 커밋은 하지 않는다.
- AGENTS.md 양식(40줄 이하, 결정 Q2)과 CLAUDE.md(@AGENTS.md)
- .claude/settings.json: .env deny, 마켓과 harness 플러그인 켜기.
Agent deny는 넣지 않는다(결정 Q5)
- scripts/verify.sh: 단계(docs·unit·pr·app) 뼈대와 --on <호스트> 운반부.
작업 트리를 패치로 옮겨 기준 커밋의 새 worktree에 적용하고 트리 해시를
맞춘 뒤 잠금 아래에서 돌린다. push하지 않는다(설계 6.1절)
- 빈 양식: docs/vision.md, docs/problem-statement.md, docs/adr/0000-template.md
- docs/ledger/: 빈 장부와 형식 설명, .gitattributes merge=union(결정 Q11)
repo 자신의 AGENTS.md·README·docs/README.md(설계와 다르게 정한 것)와
scripts/check.sh도 같이 둔다.
버린 대안: 템플릿만(공통 훅 수정이 모든 repo 손작업), 플러그인만(루트
문서·deny를 못 준다).
위험: verify.sh의 원격 운반부는 가짜 ssh(같은 기계)로만 시험했다. 실제
desktop에서는 아직 돌리지 않았다. unit·pr·app 단계 본문은 비어 있다
(종료 코드 3).
검증: scripts/check.sh 통과(플러그인 17, 템플릿 10, validate --strict).
템플릿 시험은 이름 바꾸기, 남은 {{…}} 없음, AGENTS.md 40줄 이하,
settings의 플러그인·deny, 빈 폴더가 아니면 멈춤, verify docs, 가짜 ssh로
패치 적용·트리 해시·worktree 정리와 원격 실패(종료 코드 4)를 본다.
scratchpad에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
예측·실측 장부
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다.
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
- 파일은
docs/ledger/estimates.jsonl하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은task로"correction": true줄을 더한다. - 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게
.gitattributes가 이 파일에merge=union을 준다. - p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다.
- Claude Code에서는 하네스 플러그인의
estimate·retro스킬이 이 파일을 읽고 쓴다(ledger.py precedents·actual·append). 손으로 써도 형식은 같다.
줄의 칸
모든 줄:
| 칸 | 형식 | 뜻 |
|---|---|---|
schema |
정수 | 이 형식의 판. 지금 1 |
kind |
estimate · actual · retro |
줄의 종류 |
task |
문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) |
recorded_at |
ISO 8601 | 이 줄을 쓴 시각 |
transcript |
문자열 | Claude Code 세션 기록 파일 이름(~/.claude/projects/<폴더>/<이 값>.jsonl). 실측을 다시 셀 때 쓴다 |
estimate:
| 칸 | 형식 | 뜻 |
|---|---|---|
started_at |
ISO 8601 | 세션 첫 기록 시각 |
base |
문자열 | 기준 커밋 |
task_kind, size |
문자열 | 일의 종류, 작음·중간·큼(small·medium·large) |
minutes, calls, output_tokens |
{"p30","p50","p80"} 정수 |
작업 중 시간(분), 모델 호출 수, 출력 토큰 |
basis |
문자열 | 근거: 비교한 선례와 그 실측, 결정 수, 검증 대기 |
actual:
| 칸 | 형식 | 뜻 |
|---|---|---|
minutes, active_minutes |
정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간) |
calls, output_tokens, cache_read_tokens, max_context |
정수 | 세션 기록 assistant 줄의 message.usage. 같은 message.id는 한 번만 센다 |
within |
문자열 | p30·p50·p80·over: 시간 실측이 들어간 가장 작은 예측 |
result, commits |
문자열, 배열 | done·partial·failed, 만든 커밋 |
why |
문자열 | 예측이 틀렸으면 이유 한 줄 |
retro: cause(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), level(architecture · gate · instructions · user), note, ref(고친 커밋이나 문서).