문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 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).
4.5 KiB
4.5 KiB
name, description
| name | description |
|---|---|
| estimate | Use at the start of any task that comes with a brief, a size (작음·중간·큼 / small·medium·large), or more than a few files of work — before building anything — to write a start report with p30/p50/p80 estimates of active minutes, model calls, and output tokens grounded in this repo's ledger; also use when the user asks how long or how many tokens something will take ("얼마나 걸려?", "예측해 봐", "견적"), and again at the end of the task to record the actual numbers and why the estimate missed. 착수할 때 이해한 것·가정·p30/p50/p80 예측을 쓰고 장부(docs/ledger/estimates.jsonl)에 남기며, 끝날 때 실측과 틀린 이유를 남긴다. |
estimate — 착수 보고와 예측·실측 장부
일정은 확률이다. 착수 전에 세 값을 예측하고, 끝나면 실측과 견주고, 틀린 이유로 하네스를 고친다. 질타가 아니라 측정이다.
착수(첫 5분) ──> 착수 보고 + estimate 줄 ──> 기다리지 않고 진행
끝 보고 직전 ──> actual 줄(세션 기록에서 뽑음) ──> 틀렸으면 이유 한 줄
장부는 docs/ledger/estimates.jsonl이고 형식은 docs/ledger/README.md다. 장부가 없는 repo면 터미널 착수 보고만 쓰고 장부 줄은 건너뛴다(만들지 않는다).
1. 착수 보고
공유 노트 폴더가 있으면 거기 <세션 이름>.md 맨 위에, 없으면 터미널에 한 단락으로 쓴다.
- 이해한 것 5줄 이하: 목표, 완료 기준, 범위 밖.
- 모호한 점과 고른 가정: 묻고 기다리지 않는다. 가정을 적고 진행한다. 틀린 가정은 대조에서 잡힌다.
- 예측: 작업 중 시간(분)·호출 수·출력 토큰을 p30(도전)·p50·p80(안전) 세 값으로.
- 근거: 아래 2절. 근거 없는 배수는 쓰지 않는다.
2. 근거 만들기
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents # 이 repo 장부의 지난 예측·실측
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents --size large
# 이 repo 선례가 3건 미만이면 같은 기계의 다른 repo 장부를 더한다(--ledger는 여러 번)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents --ledger docs/ledger/estimates.jsonl --ledger <다른 repo>/docs/ledger/estimates.jsonl
- 시간의 기준은 작업 중 시간이다(기록 사이 빈틈을 5분까지만 더한 값). 벽시계 시간에는 끝 보고 뒤 다음 지시를 기다린 시간이 섞인다.
- 같은 종류·크기 선례의 실측을 출발점으로 삼고, 이번 일과 다른 점을 숫자로 적는다: 손으로 판단할 결정 수, 검증 실행 횟수와 대기, 새로 쓸 코드 양. 파일 수는 약한 근거다(이동·치환은 스크립트 한 번으로 묶인다).
- 선례가 없으면 그렇다고 쓰고, 위 세 숫자로만 예측한다.
- 보정:
precedents끝 「보정」 줄의 실측/p50 중앙값이 0.8 아래나 1.25 위면, 근거로 만든 세 값에 그 칸의 중앙값을 곱하고 basis에 적는다(2026-11-08 회고: 4건 모두 p30 아래, 시간 0.43·호출 0.52·출력 0.53).
3. estimate 줄
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" current # 이 세션의 기록 경로(uuid가 transcript 칸)
echo '{"kind":"estimate","task":"<작업 이름>","transcript":"<uuid>","started_at":"<세션 시작>","base":"<기준 커밋>","task_kind":"<종류>","size":"large","minutes":{"p30":0,"p50":0,"p80":0},"calls":{"p30":0,"p50":0,"p80":0},"output_tokens":{"p30":0,"p50":0,"p80":0},"basis":"<근거 한 줄>"}' \
| python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append
append가 칸을 검사하고 schema·recorded_at을 채운다. 장부는 더하기만 한다. 고칠 일이 있으면 같은 task로 "correction": true 줄을 더한다.
4. 끝날 때 actual 줄
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" actual --task <작업 이름> # 실측과 within을 채운 초안
초안의 result(done·partial·failed), commits, why를 채워 append로 더한다. 실측이 p80을 넘었거나 p30보다 짧으면 why에 틀린 이유를 한 줄로 쓰고, 끝 보고의 「예측과 실측」에도 적는다. 커밋한 뒤에 쓰는 장부 줄은 다음 커밋에 들어가도 된다.
하지 않는 것
- 예측을 맞추려고 일을 늘리거나 줄이지 않는다.
- 회고(왜 틀렸나를 모아 하네스를 고치는 일)는
retro가 한다. 여기서는 이유 한 줄만.