Merge pull request 'feat(plugin): 회고 루프를 처음 돌리고 장부가 다음 회고를 부르게 한다' (#1) from donghyeon.kang/harness-retro-loop into main

This commit was merged in pull request #1.
This commit is contained in:
2026-11-08 14:27:20 +00:00
13 changed files with 460 additions and 37 deletions
+1 -1
View File
@@ -15,7 +15,7 @@
- `.claude-plugin/marketplace.json`: 이 repo가 곧 플러그인 마켓이다. 플러그인은 `plugins/harness/` 하나다.
- `plugins/harness/`: `hooks/hooks.json`(연결), `scripts/`(훅 본체·장부·techdebt), `skills/`(estimate·retro·techdebt), `tests/`.
- `template/`: 새 프로젝트에 복사하는 뼈대. `scripts/new-project.sh`가 복사하고 이름을 바꾼다.
- `docs/`: 이 repo에서 정한 것(`docs/README.md`)과 이 repo의 예측·실측 장부(`docs/ledger/`). 설계 정본은 design-docs `harness/01-harness-design.md`다.
- `docs/`: 이 repo에서 정한 것(`docs/README.md`)과 이 repo의 예측·실측 장부(`docs/ledger/`), 회고 기록(`docs/retro/`). 설계 정본은 design-docs `harness/01-harness-design.md`다.
## 검증
+2 -1
View File
@@ -24,8 +24,9 @@ claude-harness ─┬─ 플러그인 harness ──(claude plugin install)─
| H12 차단 | Bash 실행 직전 | 되돌릴 수 없는 명령을 막는다: 호스팅 원격으로 force push·`--mirror`·보호 브랜치 지우기, 작업 폴더·/tmp 밖이나 너무 넓은 `rm -r`, DB·볼륨·migration 삭제(DROP·TRUNCATE, flyway clean, `-p` 없는 `compose down -v`, `volume rm`, `kubectl delete pvc·ns`). `ssh '…'` 안도 본다 |
| N4 알림 | 파일을 쓴 직후 | 비밀 값처럼 보이는 것(개인 키, 토큰, 값이 있는 password 등)을 몇 줄로 알린다. 막지 않는다 |
| 장부 기록 | 세션 시작·턴 끝 | 세션 id와 기록 경로를 `~/.claude/harness/sessions.jsonl`에, 누적 실측(시간·호출·토큰)을 `~/.claude/harness/usage/<세션>.json`에 쓴다. 출력이 없어 컨텍스트 비용이 0이다 |
| 회고 넛지 | 세션 시작 | repo 장부에 회고 안 한 빗나간 예측이나 효과 판정할 개선이 있으면, repo마다 하루 한 번 한 줄로 알린다. 없으면 출력이 없다 |
| `estimate` 스킬 | 착수할 때·끝날 때 | 착수 보고와 p30·p50·p80 예측, 끝의 실측을 repo 장부 `docs/ledger/estimates.jsonl`에 |
| `retro` 스킬 | 회고 | 틀린 예측의 이유를 나누고 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나 |
| `retro` 스킬 | 회고 | 틀린 예측의 이유를 나누고 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나. 고친 뒤 실측 2건으로 효과를 판정하고, 없으면 되돌린다 |
| `techdebt` 스킬 | 세션 끝 | 이번 diff가 더한 TODO·skip·검사 끄기, 남은 파일·worktree·브랜치 |
- 훅은 Python 3 표준 라이브러리만 쓴다. 차단은 H12 하나이고, 나머지는 실패해도 작업을 막지 않는다.
+2
View File
@@ -13,6 +13,8 @@
| 7 | 플러그인 H12는 사용자 전역 설정에 `guard_bash.py … H12`가 있으면 건너뛴다 | 설계 Q13 (c)의 「두 번 돌지 않게」를 구체화 | 소유자 기계는 전역 훅이, 다른 기계·파생 서비스는 플러그인이 막는다. 판정 코드는 두 곳이 같고 소유자 기계의 전역 훅 시험이 비교한다 |
| 8 | 장부 훅은 `~/.claude/harness/`에 쓰고, repo 장부(`docs/ledger/estimates.jsonl`)에는 스킬만 쓴다 | 설계 10.2절과 같음. 13절 Q11대로 repo마다 장부 | 훅이 repo 파일을 고치면 모든 세션의 작업 트리가 더러워진다 |
| 9 | `template/.claude/settings.json`에 Agent deny를 넣지 않는다 | 설계 11.2절 그림에는 있다 | 13절 Q5(Agent 금지 해제) |
| 10 | 회고 넛지(`ledger.py nudge`)는 장부 훅과 따로 SessionStart에 건다. startup일 때만, 같은 repo(worktree를 묶어)에 20시간에 한 번 한 줄 | 설계에 없음 | 장부 줄은 쌓였는데 회고가 0이었다(`docs/retro/2026-11-08.md`). 장부 훅은 출력 0을 지키고, 넛지는 하위 세션마다 반복되지 않게 묶었다 |
| 11 | 효과 판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건의 실측으로 한다(`verdict` 줄) | 설계에 없음 | 개선 전에 예측한 작업은 그 개선의 영향을 받지 않는다. 1건은 우연이 크다 |
## 확인한 것과 못 한 것
+26 -5
View File
@@ -5,14 +5,16 @@
```text
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
회고(주 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`·`append`). 손으로 써도 형식은 같다.
- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`pending`·`append`). 손으로 써도 형식은 같다.
- 회고 대기(실측이 p30~p80 밖인데 retro 줄이 없음)나 판정 대기(개선 뒤에 예측한 다른 작업 2건의 실측이 쌓였는데 verdict 줄이 없음)가 있으면, 플러그인이 세션 시작 때 repo마다 하루 한 번 한 줄로 알린다.
## 줄의 칸
@@ -21,8 +23,8 @@
| 칸 | 형식 | 뜻 |
| --- | --- | --- |
| `schema` | 정수 | 이 형식의 판. 지금 1 |
| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 |
| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) |
| `kind` | `estimate` · `actual` · `retro` · `verdict` | 줄의 종류 |
| `task` | 문자열 | 작업 이름. 같은 작업의 줄을 묶는 키다(예: 세션 이름) |
| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 |
| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 |
@@ -46,4 +48,23 @@
| `result`, `commits` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 |
| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 |
`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서).
`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`는 판정을 내린 작업 이름이다.
+4
View File
@@ -1,2 +1,6 @@
{"schema": 1, "kind": "estimate", "task": "h2-harness-repo", "recorded_at": "2026-11-07T23:39+09:00", "transcript": "6c7e7c6f-76a6-4279-b283-32b5bb7e0153", "started_at": "2026-11-07T23:35:08+09:00", "base": "design-docs 34cf74e, 백엔드 22df3525, claude-harness 새 repo", "task_kind": "harness", "size": "large", "minutes": {"p30": 70, "p50": 95, "p80": 140}, "calls": {"p30": 200, "p50": 280, "p80": 400}, "output_tokens": {"p30": 250000, "p50": 350000, "p80": 500000}, "basis": "선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손으로 판단한 결정 약 25, desktop 실행 3회). 이번은 결정 약 20(H12 경계, 두 번 막기, 끌 스킬, 전역 문서 줄이기, 템플릿 양식, 장부 훅 형식), desktop 실행 0, 대신 새 코드가 많다(훅 스크립트 3개와 시험 약 800줄, 템플릿 10여 파일, design-docs 문서 4곳). 그래서 h3와 비슷하게 봤다"}
{"schema": 1, "kind": "actual", "task": "h2-harness-repo", "recorded_at": "2026-11-08T10:42+09:00", "transcript": "6c7e7c6f-76a6-4279-b283-32b5bb7e0153", "minutes": 667, "active_minutes": 38, "calls": 126, "output_tokens": 193781, "cache_read_tokens": 38207413, "max_context": 465584, "within": "p30", "result": "done", "commits": ["claude-harness ddbfc3d", "claude-harness 73da706", "claude-harness e762248", "design-docs 1ac6a79", "design-docs 0c9116c", "design-docs b307eba"], "why": "작업 중 시간·호출·출력이 모두 p30보다 작다. 근거로 삼은 h3(68분)에는 desktop 게이트 실행 3회와 파일 190여 개 이동이 있었는데 이번은 desktop 실행 0이고, 큰 파일을 한 번에 쓰고 한 메시지에 도구를 여럿 불러 호출이 적었다. 벽시계가 긴 것은 공개 repo 생성이 auto mode 분류기에 막혀 소유자 확인을 약 10시간 기다렸기 때문이다(작업 중 시간에는 5분만 들어감). 다음 예측은 desktop 실행 횟수를 따로 세고, desktop이 없는 하네스·문서 일은 h1(23분)과 이번(38분)을 선례로 쓴다. 실측은 장부 커밋 직전까지이고 뒤의 커밋·보고는 들어 있지 않다"}
{"schema": 1, "kind": "estimate", "task": "harness-retro-loop", "transcript": "a6f550c2-1dc2-442d-9597-e07b82d2ac4d", "started_at": "2026-11-08T22:54:05+09:00", "base": "72078ca", "task_kind": "harness", "size": "medium", "minutes": {"p30": 30, "p50": 45, "p80": 70}, "calls": {"p30": 70, "p50": 100, "p80": 150}, "output_tokens": {"p30": 90000, "p50": 130000, "p80": 200000}, "basis": "선례 h2-harness-repo 작업 중 38분·호출 126·출력 19.4만(새 코드 약 800줄, desktop 0). 이번은 새 코드 약 200줄(ledger.py 명령, 시험), 손 판단은 위임 장부 빗나간 줄 분류 20~30줄과 형식 결정 약 5, desktop 0. 지난 4건이 모두 p30 아래라 선례 실측을 배수 없이 p50 가까이에 뒀다", "recorded_at": "2026-11-08T22:55+09:00"}
{"schema": 1, "kind": "retro", "task": "h2-harness-repo", "cause": "예측 근거 없음", "level": "architecture", "note": "선례(h3)의 desktop 실행 3회를 빼지 않았다. 4건 모두 p30 아래(실측/p50 시간 0.43)라 precedents 보정 줄과 estimate 보정 규칙을 더했다", "ref": "docs/retro/2026-11-08.md", "fix": "calib-median", "recorded_at": "2026-11-08T23:07+09:00", "applied_at": "2026-11-08T23:07+09:00"}
{"schema": 1, "kind": "actual", "task": "harness-retro-loop", "recorded_at": "2026-11-08T23:10+09:00", "transcript": "a6f550c2-1dc2-442d-9597-e07b82d2ac4d", "minutes": 16, "active_minutes": 16, "calls": 43, "output_tokens": 87654, "cache_read_tokens": 7032431, "max_context": 226136, "within": "p30", "result": "done", "commits": ["cf8c8c9", "f7e235b", "403716f"], "why": "작업 중 16분·호출 43·출력 87654로 모두 p30 아래. 선례(h2 38분) 실측을 배수 없이 p50 가까이에 뒀는데도 컸다: 위임 장부 빗나간 38줄 분류를 lessons 한 줄씩 스크립트로 뽑아 한 번에 했고, ledger.py 수정을 패치 스크립트 한 번으로 묶었다. 이번에 넣은 보정(시간 x0.43)을 썼다면 p30~p50 사이였다. 이 작업은 보정 규칙 전에 예측해 calib-median 판정에는 세지 않는다. 실측은 PR 직전까지"}
{"schema": 1, "kind": "retro", "task": "harness-retro-loop", "cause": "예측 근거 없음", "level": "architecture", "note": "선례 실측을 배수 없이 써도 p30 아래였다. 같은 치우침이라 calib-median(보정 줄과 estimate 보정 규칙)으로 묶는다", "ref": "docs/retro/2026-11-08.md", "recorded_at": "2026-11-08T23:10+09:00"}
+154
View File
@@ -0,0 +1,154 @@
# 회고 2026-11-08 — 자기 개선 루프 첫 회전
장부 줄은 쌓였는데 회고한 줄이 0이었다. 예측과 실측의 차이가 다음 예측과 하네스를 고치는 부분이 한 번도 돌지 않았다. 이 문서가 첫 회고다.
```text
장부 두 곳 ──> 빗나간 줄마다 원인 하나 ──> 원인별 건수 ──> 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자)
└─> 이 repo에서 고친 것 / 다른 repo 후보
```
## 1. 대상과 「빗나감」의 기준
- **예측·실측 장부**: 백엔드 템플릿 `docs/ledger/estimates.jsonl`의 3작업과 이 repo의 1작업(h2-harness-repo). 작업 중 시간 실측이 p30~p80 밖이면 빗나감이다.
- **위임 장부**: design-docs `delegation-loop/ledger.jsonl` 55줄. 정정 줄 6개를 앞 줄에 합치면 작업 49개다.
- 이 장부에는 시간 예측이 없다. 그래서 「brief와 매뉴얼만으로 질문·위반·재작업 없이 끝난다」를 예측으로 봤다.
- `questions_gap`·`violations`·`rework`·`mismatches`·`owner_interventions` 중 하나라도 0이 아니거나 `result`가 `done`이 아니면 빗나감으로 셌다.
- `blocks`만 있는 줄 2개(d2d-ops-docs-2, layout-2-sample)는 게이트가 제 일을 한 것이라 뺐다.
- 줄 하나에 원인 하나를 붙였다. 칸이 여럿이면 가장 큰 칸의 원인이다. 원인 이름은 `retro` 스킬의 일곱 가지다.
## 2. 원인별 건수
| 원인 | 위임 장부 | 예측 장부 | 합 |
|---|---|---|---|
| 지시 모호 | 34 | 0 | 34 |
| 예측 근거 없음 | 0 | 4 | 4 |
| 착수 전 조사 부족 | 2 | 0 | 2 |
| 외부 대기 | 2 | 0 | 2 |
| 검증 대기 · 아키텍처 경직 · 범위 변경 | 0 | 0 | 0 |
| 빗나간 줄 / 전체 | 38 / 49 | 4 / 4 | 42 / 53 |
위임 장부 49작업의 칸별 합: 빈틈 질문 137, 위반 9, 막힘 14, 재작업 5, 불일치 1, 소유자 개입 5.
## 3. 예측·실측 장부 — 4건 모두 p30 아래
| 작업 | repo | 예측 분 p30/p50/p80 | 실측 분 | 실측/p50 (시간·호출·출력) | 원인 | 고친 곳 |
|---|---|---|---|---|---|---|
| h3-backend-harness | 백엔드 | 150/210/300 | 68 | 0.32 · 0.45 · 0.58 | 예측 근거 없음: 바꿀 파일 수(약 120)를 호출 수로 옮겼다. 이동·치환은 스크립트 한 번이었다 | architecture `calib-median` |
| x2-grpc-library | 백엔드 | 150/220/330 | 99 | 0.45 · 0.66 · 0.51 | 예측 근거 없음: desktop 대기를 작업 중 시간에 넣었다(대기는 빈틈마다 5분으로 잘린다) | 같은 개선 |
| x3-messaging-library | 백엔드 | 140/200/300 | 110 | 0.55 · 0.60 · 0.42 | 예측 근거 없음: 대기는 뺐지만 결정 수(약 45)를 시간 배수로 옮겼다. 본보기를 복사해 결정당 호출이 적었다 | 같은 개선 |
| h2-harness-repo | 이 repo | 70/95/140 | 38 | 0.40 · 0.45 · 0.55 | 예측 근거 없음: 선례(h3)에는 desktop 실행 3회가 있었고 이번엔 0회였다 | 같은 개선 |
**치우침을 숫자로 보면** (`ledger.py precedents --ledger <이 repo 장부> --ledger <백엔드 장부>`의 끝 줄):
- 실측/p50 중앙값은 시간 0.43, 호출 0.52, 출력 0.53이다(4건).
- 실측/p30도 모두 1 아래다. 시간 0.45~0.79, 호출 0.60~0.94, 출력 0.60~0.78.
- 4건 모두 크게 예측했다. 한쪽 치우침이다.
- 매번 `why`에 「다음엔 X를 빼고 잡는다」를 적었다. 그래도 다음 예측이 또 p30 아래였다. x2에서 x3로 가며 대기를 뺐는데도 실측/p50은 0.45에서 0.55로만 올랐다. 근거 문장을 바꾸는 것만으로는 치우침이 풀리지 않았다.
**보정 규칙** (`estimate` 스킬 2절): 「보정」 줄의 중앙값이 0.8 아래나 1.25 위면, 근거로 만든 세 값에 그 칸의 중앙값을 곱한다.
- 이번 숫자(시간 0.43)를 곱했다면 4건이 모두 p30~p80 안이었다(h3·h2는 p50, x2·x3는 p80).
- 다만 같은 4건으로 잰 값이라 자기 검증일 뿐이다. 효과는 규칙 뒤에 예측한 작업 2건으로 판정한다(`calib-median`, 7절).
- 장부가 맞아지면 중앙값이 1에 가까워지고, 규칙은 저절로 멈춘다.
## 4. 위임 장부 — 빗나간 줄 38개
「1차·2차·3차」는 매뉴얼 빈틈 수정 묶음이다. H11은 보고 언어 훅(2026-11-07)이다.
| # | 작업 | 빗나간 칸 | 원인 | 단계 | 상태 |
|---|---|---|---|---|---|
| 1 | b1-design-docs | 재작업 1 | 지시 모호: brief가 충돌 문장 수정을 범위 밖으로 뺐다 | user(brief) | 기록만 |
| 2 | b2-user-env | 재작업 1 | 착수 전 조사 부족: 템플릿 repo 이름 규칙이 worktree에서 틀렸다 | architecture | 후속 1회로 고침 |
| 3 | c-t1-r10-review | 빈틈 9 | 지시 모호(매뉴얼 빈틈) | instructions | 1차 |
| 4 | c-t1-baseline | 빈틈 7 | 지시 모호 | instructions | 1차 |
| 5 | c-t2-circuit-breaker | 빈틈 1, 위반 1(영어 보고) | 지시 모호 | instructions · gate | 1차, H11 |
| 6 | c-t3-error-codes | 빈틈 5 | 지시 모호 | instructions | 1차 |
| 7 | c-t4-manual-ids | 빈틈 5 | 지시 모호 | instructions | 1차 |
| 8 | c-t5-idempotency-opid | 빈틈 2, 위반 1(장부에 내용 없음) | 지시 모호 | instructions | 1차 |
| 9 | c-t6-integration-gates | 빈틈 6, 위반 1(영어 보고) | 지시 모호 | instructions · gate | 1차, H11 |
| 10 | r8-f1-transport-errors | 빈틈 7 | 지시 모호 | instructions | 2차 |
| 11 | r8-f2-arch-rules | 빈틈 5, 위반 1(영어 보고) | 지시 모호 | instructions · gate | 2차, H11 |
| 12 | r8-f3-persistence | 빈틈 8, 위반 1(영어 보고) | 지시 모호 | instructions · gate | 2차, H11 |
| 13 | r8-f4-idempotency | 빈틈 7 | 지시 모호 | instructions | 2차 |
| 14 | r8-f5-small-fixes | 빈틈 3, 위반 1(보고 26개 중 24개 영어) | 지시 모호 | instructions · gate | 2차, H11 |
| 15 | c-t4-2-manual-ids | 빈틈 5 | 지시 모호 | instructions | 2차 |
| 16 | r8-integration | 빈틈 6, 위반 1(영어 보고), 불일치 1 | 지시 모호 | instructions · gate | 2차, H11 |
| 17 | r8-review-a | 빈틈 5 | 지시 모호 | instructions | 2차 |
| 18 | r9-g1-inbound | 빈틈 2, 위반 1(영어 끝 요약) | 지시 모호 | instructions · gate | 3차, H11 |
| 19 | r9-g2-stomp-interceptor | 빈틈 2 | 지시 모호 | instructions | 3차 |
| 20 | r9-g3-migration | 빈틈 3 | 지시 모호 | instructions | 3차 |
| 21 | r9-g4-idempotency | 빈틈 2, 위반 1(영어 끝 요약) | 지시 모호 | instructions · gate | 3차, H11 |
| 22 | report-language-hook | 빈틈 4 | 지시 모호: 다음 H 번호 찾는 곳, 훅 확인용 턴 끝내기 등 | instructions | 3차 |
| 23 | r9-integration | 빈틈 4, 결과 부분 | 지시 모호: OOM 재시작 거짓 통과, 반복 횟수 기준이 없었다. 「부분」은 기준 트리에 이미 있던 실패 2건 때문이다 | instructions | 매뉴얼 보강 |
| 24 | s1-backend-layout | 빈틈 6 | 지시 모호 | instructions | 매뉴얼 보강 |
| 25 | s2-docs-system | 빈틈 4 | 지시 모호: 언어 규칙, 상태 어휘, README 필수 절 | instructions | 매뉴얼 보강 |
| 26 | s3-ci-scripts | 빈틈 5 | 지시 모호: CI 실행 확인 칸, workflow 추가 기준 | instructions | 매뉴얼 보강 |
| 27 | t1-backend-layout | 빈틈 5, 막힘 1, 소유자 개입 1 | 지시 모호: 게이트 결과의 이미지 재사용 칸, `if` 안 `set -e` 거짓 통과 | instructions | 매뉴얼 보강 |
| 28 | d1-docs-system | 빈틈 5 | 지시 모호 | instructions | 매뉴얼 보강 |
| 29 | i1-layout-docs-merge | 빈틈 4 | 지시 모호: 병합 때 생긴 수정을 어디에 넣나, desktop에 없는 도구를 어떻게 돌리나 | instructions | 매뉴얼 보강 |
| 30 | design-docs | 재작업 1 | 착수 전 조사 부족: 총괄이 충돌을 대상 두 파일만 보고 판단했고, 이미 병합된 커밋으로 PR을 또 만들었다 | architecture | 후보 C2 |
| 31 | p1-gitea-actions | 소유자 개입 2 | 외부 대기: live 클러스터 적용을 권한 분류기가 막아 소유자가 직접 실행했다 | user | 후보 C4 |
| 32 | d2a-entry-docs | 재작업 1 | 지시 모호: 번역할 것과 원문으로 둘 것의 기준이 없었다 | instructions | 매뉴얼 |
| 33 | d2c-ops-docs-1 | 빈틈 3, 막힘 2 | 지시 모호 | instructions | 매뉴얼 |
| 34 | i2-docs-merge | 빈틈 4, 막힘 4 | 지시 모호 | instructions | 매뉴얼 |
| 35 | v1-vuln-fix | 재작업 1 | 지시 모호: 문서 숫자 처리를 총괄이 다시 지시했다 | instructions | 기록만 |
| 36 | h1-harness-design | 막힘 1, 소유자 개입 1 | 지시 모호: 자료의 권고와 기존 결정이 부딪칠 때 어느 쪽인지 없어 권함 5건이 뒤집혔다 | instructions | 규칙을 기록함 |
| 37 | h3-backend-harness | 빈틈 3, 막힘 2 | 지시 모호: 세션이 정한 기본값 3건 | instructions | 소유자 확인 뒤 매뉴얼 |
| 38 | h2-harness-repo | 막힘 1, 소유자 개입 1 | 외부 대기: 공개 repo 만들기를 분류기가 막아 소유자 허락까지 약 10시간 | user | 후보 C4 |
막힘 14회의 출처: 영어 보고 9(d2c 2, d2d 2, i2 4, h1 1), git 훅 건너뛰기 시도 2(h3), 게이트가 잡은 이미지 빌드 회귀 1(t1), 분류기 1(h2), API 연결 오류 1(layout-2-sample).
## 5. 이미 효과가 보이는 개선 — 첫 판정
이 둘은 다른 repo·전역 설정의 개선이라 이 repo 장부가 아니라 여기에 적는다.
- **H11 보고 언어 훅** (gate, 2026-11-07): **효과 있음.**
- 훅 전 위반 9건(9작업), 훅 뒤 위반 0.
- 대신 막힘이 9회 생겼다(4작업). 위반이 막힘으로 바뀌었다.
- 영어 초안을 쓰는 일 자체는 남았다(후보 C3).
- **매뉴얼 빈틈 수정 1~3차** (instructions): **효과 있음.** 다만 매뉴얼 덕만은 아니다.
- 작업당 빈틈 질문: 1회차 5.0(7작업) → 2회차 5.1(9작업) → 3회차 2.25(4작업).
- 그 뒤 새 종류의 첫 작업 8개는 4.6이었다. 그다음 15작업은 0.67이었다.
- 뒤로 갈수록 작업 종류가 바뀌었다.
## 6. 고른 개선
순서는 아키텍처 → 게이트 → 지침 → 사용자 행동이다. 앞 단계로 풀리는 것은 뒤 단계에 손대지 않았다.
**이 repo에서 고친 것** (플러그인 0.2.0)
| id | 단계 | 무엇 | 원인 |
|---|---|---|---|
| `calib-median` | architecture | `ledger.py precedents`가 끝에 보정 줄(실측/p50 중앙값, p30 아래·p80 위 건수)을 낸다. `--ledger`를 여러 번 받아 다른 repo 장부를 더한다 | 예측 근거 없음 4건 |
| `calib-median` | instructions | `estimate` 스킬 2절에 보정 규칙 한 줄 | 같음 |
| — | architecture | `pending`이 예측 밖인데 회고 없는 작업과 판정 대기 개선을 센다. 세션 시작 넛지 `ledger.py nudge`는 repo마다 하루 한 번 한 줄이다. 실측 줄을 `append`할 때 예측 밖이면 한 줄 알린다 | 회고 0: 루프가 사람 기억에 기대 있었다 |
| — | architecture | retro 줄에 `fix`(개선 id)·`applied_at`, 새 줄 `verdict`(`effective`·`reverted`) | 「효과 없으면 되돌린다」를 적을 곳이 없었다 |
**다른 repo·설정의 후보** (이 repo에서 못 고친다)
| # | 단계 | 어디 | 무엇 | 근거 |
|---|---|---|---|---|
| C1 | architecture | 백엔드 템플릿의 desktop 게이트 스크립트 | 공유 잠금 대기 줄이기. 잠금을 lane별로 나누거나, 기다리는 동안 순번과 예상 시간을 보여 다른 일을 하게 한다 | x3 게이트 묶음 3시간 중 잠금 대기, x2 1회차 약 65분 |
| C2 | architecture | `delegate` 스킬(사용자 전역)이나 design-docs 위임 매뉴얼 | PR을 만들기 전에 head 브랜치의 열린·닫힌 PR, base 병합 여부, 같이 바뀌는 파일의 충돌을 API로 보는 스크립트 | 4절 30번 |
| C3 | architecture | 사용자 전역 설정 | 응답 언어를 설정으로 고정할 수 있는지 확인한다. H11 뒤에도 영어 초안이 9번 막혔다 | 5절 |
| C4 | user(권한) | 소유자 권한 설정 | 리뷰를 마친 PR 병합, 공개 repo 만들기처럼 분류기가 막는 일을 소유자가 미리 허락하는 규칙. 총괄 세션의 승인은 하위 세션에 넘어가지 않는다 | h2 약 10시간 대기, p1 소유자 개입 2, x2 PR 병합 막힘 |
| C5 | instructions | 백엔드 템플릿 장부 | 아래 7절의 retro 줄 3개를 더한다. 그래야 그 repo의 넛지가 멈추고 `calib-median` 판정이 그 장부에서도 돈다 | 3절 |
| C6 | gate | 사용자 전역 훅과 이 repo `guard_bash.py`(둘을 같이) | main checkout 안 worktree(`.claude/worktrees/…`)에서 `rm -rf ./*`(worktree 자신)와 `rm -rf ../옆-worktree`가 통과한다. H12 허용 폴더에 main checkout이 들어가서다. 이 repo 시험에 알려진 빈틈(`expectedFailure`)으로 표시했다. 고치면 그 시험이 「뜻밖의 통과」로 실패해 표시를 지우게 한다 | 이번 `check.sh` |
| C7 | instructions | design-docs 위임 매뉴얼 8절 | 위임 장부에는 회고했는지 적는 자리가 없다. `estimate_ref`가 있는 줄은 그 repo 장부의 retro 줄로, 없는 줄은 이 문서 같은 회고 기록으로 닫는다고 한 줄 | 회고 0 |
## 7. 백엔드 장부에 더할 retro 줄 (C5)
백엔드 템플릿 루트에서 한 줄씩 `ledger.py append`로 더한다. `applied_at`을 빼면 더한 때가 적용일이 된다. 이 PR이 병합된 뒤에 더한다.
```json
{"kind":"retro","task":"h3-backend-harness","cause":"예측 근거 없음","level":"architecture","note":"파일 수를 호출 수로 옮겼다. 4건 모두 p30 아래(실측/p50 시간 0.43)라 precedents 보정 줄과 estimate 보정 규칙을 더했다","ref":"claude-harness docs/retro/2026-11-08.md","fix":"calib-median"}
{"kind":"retro","task":"x2-grpc-library","cause":"예측 근거 없음","level":"architecture","note":"desktop 대기를 작업 중 시간에 넣었다. calib-median으로 묶는다","ref":"claude-harness docs/retro/2026-11-08.md"}
{"kind":"retro","task":"x3-messaging-library","cause":"예측 근거 없음","level":"architecture","note":"결정 수를 시간 배수로 옮겼다. calib-median으로 묶는다","ref":"claude-harness docs/retro/2026-11-08.md"}
```
## 8. 다음 회고
- `calib-median`: 규칙 뒤에 예측한 작업 2건의 실측이 쌓이면 `pending`이 「판정할 때다」를 낸다.
- 2건이 p30~p80 안이면 `effective`.
- 또 한쪽으로 몰리면 규칙을 되돌리고 다른 단계를 고른다. 예: 예측을 스크립트가 선례에서 바로 계산하게 한다.
- 위임 장부는 다음 주 회고에서 이 문서 뒤의 줄만 본다. 마지막으로 본 줄은 layout-2-sample(55번째 줄)이다.
+2 -2
View File
@@ -1,8 +1,8 @@
{
"name": "harness",
"displayName": "Harness",
"version": "0.1.0",
"description": "프로젝트와 상관없는 공통 하네스: 되돌릴 수 없는 명령 차단(H12), 비밀 값 알림(N4), 예측·실측 장부 훅과 estimate·retro·techdebt 스킬",
"version": "0.2.0",
"description": "프로젝트와 상관없는 공통 하네스: 되돌릴 수 없는 명령 차단(H12), 비밀 값 알림(N4), 예측·실측 장부 훅, 회고 넛지와 estimate·retro·techdebt 스킬",
"author": {
"name": "donghyeon.kang"
},
+2 -1
View File
@@ -19,7 +19,8 @@
"SessionStart": [
{
"hooks": [
{"type": "command", "command": "python3 -I \"${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py\" session-start", "timeout": 10}
{"type": "command", "command": "python3 -I \"${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py\" session-start", "timeout": 10},
{"type": "command", "command": "python3 -I \"${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py\" nudge", "timeout": 10}
]
}
],
+133 -16
View File
@@ -4,13 +4,15 @@
훅(출력 없음 → 컨텍스트 비용 0, 실패해도 작업을 막지 않는다)
session-start SessionStart 입력의 session_id·transcript_path·cwd를 <상태 폴더>/sessions.jsonl에 한 줄 더한다
stop Stop 때마다 세션 기록을 이어 읽어 <상태 폴더>/usage/<session_id>.json에 누적 실측을 덮어쓴다
넛지(장부 훅과 따로 건다)
nudge SessionStart(startup)에 회고 대기·판정 대기가 있으면 repo마다 하루 한 번 한 줄
명령
current 지금 폴더의 세션 기록 경로
usage [기록 경로|uuid] 세션 기록의 실측(JSON). 하위 에이전트 기록(<uuid>/subagents/)을 더한다
actual --task T [기록] T의 예측과 견준 actual 줄 초안(JSON). 쓰지는 않는다
precedents [--kind K] [--size S] 장부의 지난 예측·실측 표
pending 실측은 있고 회고가 없는 작업
precedents [--kind K] [--size S] 장부의 지난 예측·실측 표와 보정 줄(실측/p50 중앙값). --ledger를 여러 번 줘도 된다
pending 예측 밖인데 회고가 없는 작업, 효과 판정이 없는 개선
append stdin의 JSON 한 줄을 검사해 장부 끝에 더한다
상태 폴더: $HARNESS_STATE_DIR, 없으면 ~/.claude/harness. 장부: <git 최상위>/docs/ledger/estimates.jsonl(--ledger로 바꿈).
@@ -23,18 +25,24 @@ import glob
import json
import os
import re
import statistics
import subprocess
import sys
import time
GAP_SECONDS = 300
KINDS = ("estimate", "actual", "retro")
KINDS = ("estimate", "actual", "retro", "verdict")
REQUIRED = {
"estimate": ("minutes", "basis"),
"actual": ("active_minutes",),
"retro": ("cause", "level"),
"verdict": ("fix", "effect"),
}
CAUSES = ("지시 모호", "착수 전 조사 부족", "아키텍처 경직", "검증 대기", "외부 대기", "범위 변경", "예측 근거 없음")
LEVELS = ("architecture", "gate", "instructions", "user")
EFFECTS = ("effective", "reverted")
VERDICT_AFTER = 2 # 개선 뒤에 예측한 다른 작업의 실측이 이만큼 쌓이면 효과를 판정한다
NUDGE_EVERY = 20 * 3600 # 같은 repo에 넛지를 다시 내기까지(초)
def state_dir():
@@ -132,15 +140,18 @@ def project_dir_name(path):
return re.sub(r"[^A-Za-z0-9-]", "-", path)
def git_toplevel(start):
def git_rev_parse(start, *args):
try:
r = subprocess.run(["git", "-C", start, "rev-parse", "--show-toplevel"], capture_output=True, text=True,
timeout=5)
r = subprocess.run(["git", "-C", start, "rev-parse", *args], capture_output=True, text=True, timeout=5)
except (OSError, subprocess.SubprocessError):
return None
return r.stdout.strip() if r.returncode == 0 else None
def git_toplevel(start):
return git_rev_parse(start, "--show-toplevel")
def current_transcript(cwd=None):
"""지금 폴더의 세션 기록. SessionStart 기록이 먼저, 없으면 ~/.claude/projects/<폴더>/의 가장 새 기록."""
cwd = os.path.realpath(cwd or os.getcwd())
@@ -200,6 +211,40 @@ def hook_stop(data):
os.replace(tmp, path)
def hook_nudge(data):
"""회고 대기·판정 대기가 있으면 한 줄. 같은 repo(worktree를 묶어)에는 NUDGE_EVERY에 한 번만."""
if data.get("source") not in (None, "startup"):
return
top = git_toplevel(data.get("cwd") or os.getcwd())
if not top:
return
rows = read_ledger(os.path.join(top, "docs", "ledger", "estimates.jsonl"))
parts = []
retro = len(retro_due(by_task(rows)))
if retro:
parts.append("회고 안 한 빗나간 예측 %d건" % retro)
verdict = sum(1 for _, later in open_fixes(rows) if later >= VERDICT_AFTER)
if verdict:
parts.append("효과를 판정할 개선 %d건" % verdict)
if not parts:
return
key = git_rev_parse(top, "--path-format=absolute", "--git-common-dir") or top
path = os.path.join(state_dir(), "nudge.json")
try:
with open(path, encoding="utf-8") as f:
seen = json.load(f)
except (OSError, ValueError):
seen = {}
if time.time() - seen.get(key, 0) < NUDGE_EVERY:
return
seen[key] = time.time()
os.makedirs(state_dir(), exist_ok=True)
with open(path + ".tmp", "w", encoding="utf-8") as f:
json.dump(seen, f)
os.replace(path + ".tmp", path)
print("harness: 이 repo 장부에 %s이 있다. 회고는 `retro` 스킬로 한다. 맡은 일이 회고가 아니면 넘긴다." % ", ".join(parts))
# ---------------------------------------------------------------- 장부
def ledger_path(arg):
@@ -225,6 +270,49 @@ def by_task(rows):
return tasks
def missed(t):
"""실측이 p30보다 짧거나 p80보다 길었거나, 실측 줄에 틀린 이유가 적힌 작업."""
a, m = t.get("actual") or {}, (t.get("estimate") or {}).get("minutes") or {}
if not a:
return False
if a.get("why"):
return True
act = a.get("active_minutes")
return isinstance(act, (int, float)) and "p30" in m and "p80" in m and not m["p30"] <= act <= m["p80"]
def retro_due(tasks):
return [(n, t) for n, t in tasks.items() if missed(t) and "retro" not in t]
def open_fixes(rows):
"""효과 판정 줄이 없는 개선(retro 줄의 fix)과, 적용 뒤에 예측 줄을 쓰고 실측까지 끝난 다른 작업 수.
적용 전에 예측한 작업은 그 개선의 영향을 받지 않았으니 세지 않는다."""
judged = {r.get("fix") for r in rows if r.get("kind") == "verdict"}
fixes = {r["fix"]: r for r in rows if r.get("kind") == "retro" and r.get("fix") and r["fix"] not in judged}
tasks = by_task(rows)
out = []
for r in fixes.values():
since = epoch(r.get("applied_at") or r.get("recorded_at")) or 0
later = sum(1 for n, t in tasks.items() if n != r.get("task") and "actual" in t
and (epoch((t.get("estimate") or {}).get("recorded_at")) or 0) > since)
out.append((r, later))
return out
def bias(tasks):
"""예측과 실측이 둘 다 있는 작업의 실측/p50 중앙값. 1보다 작으면 크게 예측해 온 것이다."""
out = []
for label, ek, ak in (("시간", "minutes", "active_minutes"), ("호출", "calls", "calls"),
("출력", "output_tokens", "output_tokens")):
ratios = [t["actual"][ak] / t["estimate"][ek]["p50"] for t in tasks.values()
if isinstance((t.get("actual") or {}).get(ak), (int, float))
and isinstance((t.get("estimate") or {}).get(ek), dict) and t["estimate"][ek].get("p50")]
if ratios:
out.append("%s %.2f(%d건)" % (label, statistics.median(ratios), len(ratios)))
return out
def within(estimate, active):
for k in ("p30", "p50", "p80"):
v = (estimate.get("minutes") or {}).get(k)
@@ -239,7 +327,7 @@ def triple(d):
def cmd_precedents(args):
tasks = by_task(read_ledger(ledger_path(args.ledger)))
tasks = by_task([r for p in (args.ledger or [None]) for r in read_ledger(ledger_path(p))])
rows = []
for name, t in tasks.items():
e, a = t.get("estimate", {}), t.get("actual", {})
@@ -256,19 +344,31 @@ def cmd_precedents(args):
print("| 작업 | 종류 | 크기 | 예측 분 p30/p50/p80 | 실측 작업 중 분 | 호출 | 출력 토큰 | 들어간 칸 |")
print("|---|---|---|---|---|---|---|---|")
print("\n".join(rows))
ratios = bias(tasks)
if ratios:
done = [((t.get("estimate") or {}).get("minutes") or {}, t["actual"]["active_minutes"]) for t in tasks.values()
if isinstance((t.get("actual") or {}).get("active_minutes"), (int, float))]
below = sum(1 for m, act in done if "p30" in m and act < m["p30"])
above = sum(1 for m, act in done if "p80" in m and act > m["p80"])
print("\n보정: 실측/p50 중앙값 %s. 시간 실측이 p30 아래 %d건, p80 위 %d건. 중앙값이 0.8 아래나 1.25 위면 "
"새 예측의 세 값에 그 칸의 중앙값을 곱한다." % (" · ".join(ratios), below, above))
return 0
def cmd_pending(args):
tasks = by_task(read_ledger(ledger_path(args.ledger)))
todo = [(n, t) for n, t in tasks.items() if "actual" in t and "retro" not in t]
rows = read_ledger(ledger_path(args.ledger))
todo = retro_due(by_task(rows))
for name, t in todo:
a = t["actual"]
print("- %s: 예측 %s분, 실측 %s분(%s). 이유: %s" % (
name, triple(t.get("estimate", {}).get("minutes")), a.get("active_minutes"), a.get("within", "-"),
a.get("why", "-")))
a.get("why") or "-"))
if not todo:
print("회고할 줄 없음.")
for r, later in open_fixes(rows):
print("- 판정 대기 %s(%s, %s 적용): 뒤 실측 %d건%s" % (
r["fix"], r.get("task"), str(r.get("applied_at") or r.get("recorded_at"))[:10], later,
". 판정할 때다" if later >= VERDICT_AFTER else ""))
return 0
@@ -303,23 +403,40 @@ def cmd_append(args):
problems.append("minutes는 p30·p50·p80 셋")
if row.get("kind") == "retro" and (row.get("cause") not in CAUSES or row.get("level") not in LEVELS):
problems.append("cause는 %s, level은 %s 중 하나" % ("·".join(CAUSES), "·".join(LEVELS)))
path = ledger_path(args.ledger)
rows = read_ledger(path)
if row.get("kind") == "verdict":
if row.get("effect") not in EFFECTS:
problems.append("effect는 %s 중 하나" % "·".join(EFFECTS))
if row.get("fix") not in {r.get("fix") for r in rows if r.get("kind") == "retro"}:
problems.append("fix %s인 retro 줄이 장부에 없다" % row.get("fix"))
if problems:
print("장부에 쓰지 않았다: " + "; ".join(problems), file=sys.stderr)
return 1
row = {"schema": 1, **row}
row.setdefault("recorded_at", now_iso())
path = ledger_path(args.ledger)
if row["kind"] == "retro" and row.get("fix"):
row.setdefault("applied_at", row["recorded_at"])
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "a", encoding="utf-8") as f:
f.write(json.dumps(row, ensure_ascii=False) + "\n")
print("%s에 한 줄 더함: %s %s" % (path, row["kind"], row["task"]))
if row["kind"] == "actual":
rows.append(row)
t = by_task(rows).get(row["task"], {})
due = sum(1 for _, later in open_fixes(rows) if later >= VERDICT_AFTER)
if missed(t):
print("예측 밖이다(예측 %s분, 실측 %s분). `retro` 스킬로 이유를 나눈다." % (
triple(t.get("estimate", {}).get("minutes")), row.get("active_minutes")))
if due:
print("효과를 판정할 개선 %d건: ledger.py pending" % due)
return 0
def main(argv):
p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
sub = p.add_subparsers(dest="cmd", required=True)
for name in ("session-start", "stop", "current"):
for name in ("session-start", "stop", "nudge", "current"):
sub.add_parser(name)
u = sub.add_parser("usage")
u.add_argument("transcript", nargs="?")
@@ -330,16 +447,16 @@ def main(argv):
pr = sub.add_parser("precedents")
pr.add_argument("--kind")
pr.add_argument("--size", choices=("small", "medium", "large"))
pr.add_argument("--ledger")
pr.add_argument("--ledger", action="append")
for name in ("pending", "append"):
sub.add_parser(name).add_argument("--ledger")
args = p.parse_args(argv)
if args.cmd in ("session-start", "stop"):
if args.cmd in ("session-start", "stop", "nudge"):
try:
data = json.loads(sys.stdin.read() or "{}")
(hook_session_start if args.cmd == "session-start" else hook_stop)(data)
except Exception as exc: # 장부 훅은 작업을 막지 않는다
{"session-start": hook_session_start, "stop": hook_stop, "nudge": hook_nudge}[args.cmd](data)
except Exception as exc: # 장부 훅·넛지는 작업을 막지 않는다
print("harness ledger %s 건너뜀: %r" % (args.cmd, exc), file=sys.stderr)
return 0
if args.cmd == "current":
+3
View File
@@ -28,11 +28,14 @@ description: Use at the start of any task that comes with a brief, a size (작
```bash
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 줄
+18 -4
View File
@@ -8,7 +8,8 @@ description: Use when reviewing estimate misses in this repo's ledger — when t
예측이 틀린 흔한 원인은 맥락 부족이다. 사람을 탓하지 않고 하네스(구조·검사·지침)를 고친다. 앞 단계로 풀리면 뒤 단계는 손대지 않는다.
```text
장부 ──> 회고 안 된 실측 ──> 이유 분류 ──> 고칠 단계 하나 ──> 고친 커밋 ──> retro 줄
장부 ──> 회고 안 된 실측 ──> 이유 분류 ──> 고칠 단계 하나 ──> 고친 커밋 ──> retro 줄(개선 id)
뒤 작업 2건 ──> 같은 이유가 되풀이됐나 ──> verdict 줄(유지 또는 되돌림)
```
## 1. 대상 모으기
@@ -18,7 +19,7 @@ python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" pending
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents
```
실측이 p30~p80 안이면 회고할 것이 없다(예측이 맞았다). 그 밖이거나 `why`가 있는 줄만 본다.
`pending`은 실측이 p30~p80 밖이거나 `why`가 있는데 retro 줄이 없는 작업과, 판정 대기 개선을 보인다. p30~p80 안이면 회고할 것이 없다(예측이 맞았다). 플러그인이 세션 시작 때 이 수를 하루 한 번 알린다. 다른 repo 장부는 `--ledger <경로>`로 본다.
## 2. 이유 나누기 — 아래 일곱 중 하나
@@ -46,8 +47,21 @@ python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents
## 4. retro 줄
```bash
echo '{"kind":"retro","task":"<작업 이름>","cause":"예측 근거 없음","level":"instructions","note":"<무엇을 왜>","ref":"<커밋이나 문서>"}' \
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건이 실측까지 끝남)은 그 실측들에서 같은 이유가 되풀이됐는지 본다.
```bash
echo '{"kind":"verdict","task":"<판정한 작업>","fix":"<개선 id>","effect":"effective","evidence":"<뒤 작업과 그 실측>"}' \
| python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append
```
- 되풀이되지 않았으면 `effective`(유지).
- 되풀이됐으면 그 수정을 되돌리는 커밋을 만들고 `reverted`와 `ref`(되돌린 커밋)를 쓴다. 그다음 같은 이유를 다른 단계로 다시 고른다.
- 판단할 실측이 아직 모자라면 쓰지 않고 기다린다.
+87 -2
View File
@@ -13,6 +13,11 @@ import unittest
SCRIPTS = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
REPO = os.path.dirname(os.path.dirname(os.path.dirname(SCRIPTS)))
_COMMON = subprocess.run(["git", "-C", REPO, "rev-parse", "--path-format=absolute", "--git-common-dir"],
capture_output=True, text=True).stdout.strip()
# main checkout 안에 만든 worktree(.claude/worktrees/…)에서 도는가. 이때 H12 허용 폴더에 main checkout이 들어가
# worktree 자신(`rm -rf ./*`)이나 옆 worktree(`../x`)를 지우는 것이 통과한다(알려진 빈틈, 전역 훅과 같이 고친다)
NESTED_WORKTREE = bool(_COMMON) and os.path.realpath(REPO).startswith(os.path.dirname(os.path.realpath(_COMMON)) + "/")
def run(script, args=(), payload=None, env=None, cwd=None):
@@ -58,8 +63,13 @@ class GuardBashTest(unittest.TestCase):
self.assert_blocked("git push origin --delete main")
def test_rm_outside_or_too_broad_is_blocked(self):
for c in ("rm -rf /", "rm -rf ~", "rm -rf .git", 'rm -rf "$UNSET/"', "rm -rf ./*",
"rm -rf ../other-repo/src", "ssh build 'rm -rf ~/workspace/some-repo'"):
for c in ("rm -rf /", "rm -rf ~", "rm -rf .git", 'rm -rf "$UNSET/"',
"ssh build 'rm -rf ~/workspace/some-repo'"):
self.assert_blocked(c)
@(unittest.expectedFailure if NESTED_WORKTREE else (lambda f: f))
def test_rm_whole_checkout_or_sibling_is_blocked(self):
for c in ("rm -rf ./*", "rm -rf ../other-repo/src"):
self.assert_blocked(c)
def test_rm_inside_project_tmp_and_known_vars_pass(self):
@@ -204,6 +214,81 @@ class LedgerTest(unittest.TestCase):
retro = {"kind": "retro", "task": "t1", "cause": "모름", "level": "gate"}
self.assertEqual(run("ledger.py", ["append", "--ledger", ledger], payload=retro, env=self.env).returncode, 1)
def write_ledger(self, path, rows):
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "a", encoding="utf-8") as f:
for row in rows:
f.write(json.dumps(row, ensure_ascii=False) + "\n")
@staticmethod
def pair(task, active, why="", at="2026-11-01T10:00+09:00", p=(10, 20, 30), calls=None):
est = {"kind": "estimate", "task": task, "minutes": dict(zip(("p30", "p50", "p80"), p)), "basis": "시험",
"recorded_at": at}
act = {"kind": "actual", "task": task, "active_minutes": active, "why": why, "recorded_at": at}
if calls:
est["calls"], act["calls"] = {"p30": 1, "p50": calls[0], "p80": 99}, calls[1]
return [est, act]
def test_pending_lists_misses_then_tracks_fix_until_verdict(self):
ledger = os.path.join(self.dir, "estimates.jsonl")
self.write_ledger(ledger, self.pair("in", 25) + self.pair("under", 3) + self.pair("over", 31)
+ self.pair("noted", 15, why="검증 대기가 길었다"))
r = run("ledger.py", ["pending", "--ledger", ledger], env=self.env)
self.assertEqual([line.split(":")[0] for line in r.stdout.splitlines()], ["- under", "- over", "- noted"])
retro = {"kind": "retro", "task": "under", "cause": "예측 근거 없음", "level": "architecture", "note": "시험",
"fix": "f1", "recorded_at": "2026-11-02T10:00+09:00"}
self.assertEqual(run("ledger.py", ["append", "--ledger", ledger], payload=retro, env=self.env).returncode, 0)
self.write_ledger(ledger, [{"kind": "estimate", "task": "under", "correction": True,
"recorded_at": "2026-11-02T12:00+09:00"}, # 회고한 작업 자신은 세지 않는다
{"kind": "estimate", "task": "c", "minutes": {"p30": 1, "p50": 2, "p80": 9},
"basis": "시험", "recorded_at": "2026-11-02T12:00+09:00"}]) # 실측 전은 세지 않는다
r = run("ledger.py", ["pending", "--ledger", ledger], env=self.env)
self.assertNotIn("- under", r.stdout)
self.assertIn("- 판정 대기 f1(under, 2026-11-02 적용): 뒤 실측 0건\n", r.stdout)
for task, at in (("a", "2026-11-03T10:00+09:00"), ("b", "2026-11-04T10:00+09:00")):
self.write_ledger(ledger, [{"kind": "estimate", "task": task, "minutes": {"p30": 1, "p50": 2, "p80": 9},
"basis": "시험", "recorded_at": at}])
r = run("ledger.py", ["append", "--ledger", ledger], env=self.env,
payload={"kind": "actual", "task": task, "active_minutes": 40, "recorded_at": at})
self.assertIn("예측 밖이다(예측 1/2/9분, 실측 40분)", r.stdout)
self.assertIn("효과를 판정할 개선 1건", r.stdout)
self.assertIn("뒤 실측 2건. 판정할 때다", run("ledger.py", ["pending", "--ledger", ledger], env=self.env).stdout)
for bad in ({"fix": "f9", "effect": "effective"}, {"fix": "f1", "effect": "모름"}):
r = run("ledger.py", ["append", "--ledger", ledger], env=self.env, payload={"kind": "verdict", "task": "b", **bad})
self.assertEqual(r.returncode, 1, bad)
verdict = {"kind": "verdict", "task": "b", "fix": "f1", "effect": "reverted", "ref": "abc1234"}
self.assertEqual(run("ledger.py", ["append", "--ledger", ledger], payload=verdict, env=self.env).returncode, 0)
self.assertNotIn("판정 대기", run("ledger.py", ["pending", "--ledger", ledger], env=self.env).stdout)
def test_precedents_shows_bias_across_ledgers(self):
one, two = os.path.join(self.dir, "one.jsonl"), os.path.join(self.dir, "two.jsonl")
self.write_ledger(one, self.pair("x", 5, calls=(100, 40)))
self.write_ledger(two, self.pair("y", 15, calls=(100, 60)) + self.pair("z", 40))
r = run("ledger.py", ["precedents", "--ledger", one, "--ledger", two], env=self.env)
self.assertIn("실측/p50 중앙값 시간 0.75(3건) · 호출 0.50(2건). 시간 실측이 p30 아래 1건, p80 위 1건", r.stdout)
def test_nudge_prints_one_line_once_per_repo_on_startup(self):
repo = os.path.join(self.dir, "repo")
os.makedirs(repo)
subprocess.run(["git", "init", "-q", repo], check=True)
hook = {"session_id": "s", "cwd": repo, "source": "startup"}
self.assertEqual(run("ledger.py", ["nudge"], payload=hook, env=self.env).stdout, "") # 장부 없음
ledger = os.path.join(repo, "docs", "ledger", "estimates.jsonl")
self.write_ledger(ledger, self.pair("in", 25))
self.assertEqual(run("ledger.py", ["nudge"], payload=hook, env=self.env).stdout, "") # 빗나간 것 없음
self.write_ledger(ledger, self.pair("under", 3))
self.assertEqual(run("ledger.py", ["nudge"], payload={**hook, "source": "resume"}, env=self.env).stdout, "")
r = run("ledger.py", ["nudge"], payload=hook, env=self.env)
self.assertEqual(r.returncode, 0)
self.assertEqual(len(r.stdout.splitlines()), 1)
self.assertIn("회고 안 한 빗나간 예측 1건", r.stdout)
self.assertEqual(run("ledger.py", ["nudge"], payload=hook, env=self.env).stdout, "") # 하루 한 번
r = run("ledger.py", ["nudge"], payload="{broken", env=self.env)
self.assertEqual((r.returncode, r.stdout), (0, ""))
class TechdebtTest(unittest.TestCase):
def test_lists_only_added_markers(self):
+26 -5
View File
@@ -5,14 +5,16 @@
```text
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
회고(주 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`·`append`). 손으로 써도 형식은 같다.
- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`pending`·`append`). 손으로 써도 형식은 같다.
- 회고 대기(실측이 p30~p80 밖인데 retro 줄이 없음)나 판정 대기(개선 뒤에 예측한 다른 작업 2건의 실측이 쌓였는데 verdict 줄이 없음)가 있으면, 플러그인이 세션 시작 때 repo마다 하루 한 번 한 줄로 알린다.
## 줄의 칸
@@ -21,8 +23,8 @@
| 칸 | 형식 | 뜻 |
| --- | --- | --- |
| `schema` | 정수 | 이 형식의 판. 지금 1 |
| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 |
| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) |
| `kind` | `estimate` · `actual` · `retro` · `verdict` | 줄의 종류 |
| `task` | 문자열 | 작업 이름. 같은 작업의 줄을 묶는 키다(예: 세션 이름) |
| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 |
| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 |
@@ -46,4 +48,23 @@
| `result`, `commits` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 |
| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 |
`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서).
`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`는 판정을 내린 작업 이름이다.