# 예측·실측 장부 작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다. ```text 착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계, 개선 id 판정(뒤 작업 2건) ──> verdict 줄: 그 개선이 효과가 있었나, 없으면 되돌림 평가(하네스 판 비교) ──> eval 줄: 같은 과제를 판마다 돌린 실행 하나씩 ``` - 파일은 `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` · `eval` | 줄의 종류 | | `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`는 판정을 내린 작업 이름이다. `eval`(하네스 판 비교의 실행 하나, `harness-eval` 스킬): | 칸 | 형식 | 뜻 | | --- | --- | --- | | `task` | 문자열 | 평가 이름(예: `harness-v2-eval`). 같은 평가의 실행을 묶는다 | | `arm`, `case` | 문자열 | 판(예: `v1`·`v2`), 과제(예: `review-seeded-be`) | | `active_minutes`, `calls`, `output_tokens`, `input_tokens_total` | 정수 | `actual`과 같은 규칙. 서브에이전트 기록을 더한다 | | `start_context`, `max_context` | 정수 | 첫 호출의 입력 토큰(시작 비용), 가장 큰 호출의 입력 토큰 | | `subagents`, `subagent_calls`, `agent_calls`, `agent_return_chars` | 정수 | 서브에이전트 기록 수와 그 호출 수, 메인이 띄운 Agent 호출 수, 서브에이전트가 메인에 돌려준 글자 수(컨텍스트 비용) | | `findings`, `false_findings` | 정수 | 정답을 아는 과제에서 찾은 것, 틀린 발견 | | `note` | 문자열 | 실행 방식(새 세션인가, 서브에이전트로 흉내 냈나), 모델 | `ledger.py compare --task <평가 이름>`이 과제·판마다 중앙값과 마지막 판/첫 판 비율을 보인다. `precedents`·회고 대기는 `eval` 줄을 세지 않는다.