Files
claude-harness/template/docs/ledger
DongHyeonka f7e235bad7 feat(plugin): 장부가 회고 대기와 효과 판정을 세고 세션 시작에 알린다
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이다. 회고는 사람이
「주 1회」를 기억해야 돌고, 고친 뒤 효과가 없으면 되돌린다는 규칙을
적을 칸도 없다. 지난 4작업은 모두 실측이 p30 아래였는데(실측/p50
시간 중앙값 0.43), 매번 이유 한 줄만 바꿔서 치우침이 그대로 남았다.

고른 방법:
- precedents 끝에 보정 줄을 낸다: 실측/p50 중앙값(시간·호출·출력)과
  p30 아래·p80 위 건수. --ledger를 여러 번 받아 다른 repo 장부를 더한다.
  estimate 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄.
- pending은 예측 밖(p30~p80 밖이거나 why가 있음)인데 retro 줄이 없는
  작업만 보이고, 효과 판정이 없는 개선도 보인다.
- retro 줄에 fix(개선 id)·applied_at, 새 줄 verdict(effective·reverted).
  판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건의 실측이 끝나면 한다.
  개선 전에 예측한 작업은 그 개선의 영향을 받지 않아 세지 않는다.
- SessionStart에 ledger.py nudge를 따로 건다. startup일 때만, 같은
  repo(worktree를 git common dir로 묶어)에 20시간에 한 번 한 줄.
  append가 actual 줄을 쓸 때 예측 밖이면 그 자리에서 한 줄 알린다.
버린 대안: session-start 장부 훅에서 출력(장부 훅 출력 0 규칙을 깬다),
매 세션 넛지(하위 세션마다 같은 줄이 컨텍스트에 쌓인다), 별도
retro 스크립트(이미 있는 ledger.py 명령으로 충분하다).

위험: 넛지는 그 repo의 첫 세션이 하위 세션이어도 나온다. 문구에
「맡은 일이 회고가 아니면 넘긴다」를 넣었다. 다른 repo 장부에 retro
줄이 더해질 때까지 그 repo에서는 하루 한 번 넛지가 나온다.
보정 규칙은 같은 4건으로 잰 값이라 아직 효과를 모른다.

검증: scripts/check.sh rc=0(플러그인 시험 21개 OK, expected failure 1,
템플릿 시험 10개 OK, plugin validate --strict 통과). 새 조건 15개를
하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다. 백엔드 템플릿
장부에 nudge를 돌리면 「회고 안 한 빗나간 예측 3건」 한 줄이 나왔다
(상태 폴더는 scratchpad).
2026-11-08 23:09:32 +09:00
..

예측·실측 장부

작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다.

착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계, 개선 id
판정(뒤 작업 2건) ──> verdict 줄: 그 개선이 효과가 있었나, 없으면 되돌림
  • 파일은 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·pending·append). 손으로 써도 형식은 같다.
  • 회고 대기(실측이 p30~p80 밖인데 retro 줄이 없음)나 판정 대기(개선 뒤에 예측한 다른 작업 2건의 실측이 쌓였는데 verdict 줄이 없음)가 있으면, 플러그인이 세션 시작 때 repo마다 하루 한 번 한 줄로 알린다.

줄의 칸

모든 줄:

칸 형식 뜻
schema 정수 이 형식의 판. 지금 1
kind estimate · actual · retro · verdict 줄의 종류
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 문자열 무엇을 왜, 고친 커밋이나 문서
fix 문자열 개선 id(예: calib-p50). 효과를 판정할 개선이면 붙인다. 같은 id를 다른 retro 줄에 다시 쓰지 않는다
applied_at ISO 8601 개선을 적용한 때. 빼면 이 줄을 쓴 때다. 이 뒤에 예측 줄을 쓴 다른 작업의 실측으로 효과를 본다

verdict(개선 하나의 효과 판정):

칸 형식 뜻
fix 문자열 판정한 개선 id. 장부에 그 id의 retro 줄이 있어야 한다
effect effective · reverted 효과 있음(유지), 효과 없음(되돌림)
evidence 문자열 근거: 개선 뒤 작업들과 같은 원인이 되풀이됐나
ref 문자열 reverted면 되돌린 커밋

task는 판정을 내린 작업 이름이다.