문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 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.0 KiB
4.0 KiB
name, description
| name | description |
|---|---|
| retro | Use when reviewing estimate misses in this repo's ledger — when the user asks for a retrospective ("회고해", "retro", "예측이 왜 틀렸나", "장부 정리"), at a weekly review, or when a task just closed with its actual time over p80 or under p30 — to classify why each estimate missed and pick exactly one harness fix in the order architecture → gate → instructions → user behavior. 장부에서 회고가 없는 실측 줄을 모아 틀린 이유를 나누고, 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나를 고른다. |
retro — 예측이 틀린 이유로 하네스 고치기
예측이 틀린 흔한 원인은 맥락 부족이다. 사람을 탓하지 않고 하네스(구조·검사·지침)를 고친다. 앞 단계로 풀리면 뒤 단계는 손대지 않는다.
장부 ──> 회고 안 된 실측 ──> 이유 분류 ──> 고칠 단계 하나 ──> 고친 커밋 ──> retro 줄(개선 id)
뒤 작업 2건 ──> 같은 이유가 되풀이됐나 ──> verdict 줄(유지 또는 되돌림)
1. 대상 모으기
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" pending
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents
pending은 실측이 p30p80 밖이거나 p80 안이면 회고할 것이 없다(예측이 맞았다). 플러그인이 세션 시작 때 이 수를 하루 한 번 알린다. 다른 repo 장부는 why가 있는데 retro 줄이 없는 작업과, 판정 대기 개선을 보인다. p30--ledger <경로>로 본다.
2. 이유 나누기 — 아래 일곱 중 하나
| cause | 보이는 모양 |
|---|---|
| 지시 모호 | 완료 기준·범위가 brief에 없어 중간에 바뀜 |
| 착수 전 조사 부족 | 착수 뒤에야 안 사실(기존 장치, 제약)이 시간을 바꿈 |
| 아키텍처 경직 | 작은 변경이 여러 경계를 건드림 |
| 검증 대기 | 게이트·빌드·원격 실행 대기가 시간 대부분 |
| 외부 대기 | 사람 승인, 권한, 다른 세션 |
| 범위 변경 | 일 도중 요청이 늘거나 줄어듦 |
| 예측 근거 없음 | 선례를 잘못 읽었거나 배수에 근거가 없었음 |
세션 기록이 필요하면 ledger.py usage <uuid>로 다시 센다.
3. 고칠 곳 하나 — 이 순서로
- architecture: 구조나 도구를 바꿔 같은 일이 다시 안 생기게(스크립트, 경계 정리, 장부 칸).
- gate: 검사·훅이 잡게.
- instructions:
AGENTS.md·스킬·playbook에 한 줄. - user: 사용자에게 바꿔 달라고 할 행동(brief 양식 등).
앞 단계로 풀 수 있는데 뒤 단계(지침 한 줄 더하기)를 고르지 않는다. 고친 것은 커밋으로 남긴다.
4. retro 줄
echo '{"kind":"retro","task":"<작업 이름>","cause":"예측 근거 없음","level":"instructions","note":"<무엇을 왜>","ref":"<커밋이나 문서>","fix":"<개선 id>"}' \
| python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append
하네스를 고쳤으면 fix에 짧은 개선 id를 붙인다(적용 때 applied_at은 빼면 지금). 고치지 않고 기록만 하는 줄은 fix를 뺀다. 여러 작업이 같은 개선으로 묶이면 첫 retro 줄에만 fix를 붙인다.
5. 효과 판정 — 고친 뒤 실측으로
pending에 「판정할 때다」가 나온 개선(적용 뒤에 예측한 다른 작업 2건이 실측까지 끝남)은 그 실측들에서 같은 이유가 되풀이됐는지 본다.
echo '{"kind":"verdict","task":"<판정한 작업>","fix":"<개선 id>","effect":"effective","evidence":"<뒤 작업과 그 실측>"}' \
| python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append
- 되풀이되지 않았으면
effective(유지). - 되풀이됐으면 그 수정을 되돌리는 커밋을 만들고
reverted와ref(되돌린 커밋)를 쓴다. 그다음 같은 이유를 다른 단계로 다시 고른다. - 판단할 실측이 아직 모자라면 쓰지 않고 기다린다.