diff --git a/README.md b/README.md index 484ec78..e6f99fa 100644 --- a/README.md +++ b/README.md @@ -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 하나이고, 나머지는 실패해도 작업을 막지 않는다. diff --git a/docs/README.md b/docs/README.md index 5d7eec2..0b3bdf1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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건은 우연이 크다 | ## 확인한 것과 못 한 것 diff --git a/docs/ledger/README.md b/docs/ledger/README.md index 9890e66..17114d5 100644 --- a/docs/ledger/README.md +++ b/docs/ledger/README.md @@ -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`는 판정을 내린 작업 이름이다. diff --git a/plugins/harness/.claude-plugin/plugin.json b/plugins/harness/.claude-plugin/plugin.json index a0847b0..7d3f014 100644 --- a/plugins/harness/.claude-plugin/plugin.json +++ b/plugins/harness/.claude-plugin/plugin.json @@ -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" }, diff --git a/plugins/harness/hooks/hooks.json b/plugins/harness/hooks/hooks.json index 221dcf6..c8df61a 100644 --- a/plugins/harness/hooks/hooks.json +++ b/plugins/harness/hooks/hooks.json @@ -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} ] } ], diff --git a/plugins/harness/scripts/ledger.py b/plugins/harness/scripts/ledger.py index 5f1ae8a..44177f8 100755 --- a/plugins/harness/scripts/ledger.py +++ b/plugins/harness/scripts/ledger.py @@ -4,13 +4,15 @@ 훅(출력 없음 → 컨텍스트 비용 0, 실패해도 작업을 막지 않는다) session-start SessionStart 입력의 session_id·transcript_path·cwd를 <상태 폴더>/sessions.jsonl에 한 줄 더한다 stop Stop 때마다 세션 기록을 이어 읽어 <상태 폴더>/usage/.json에 누적 실측을 덮어쓴다 +넛지(장부 훅과 따로 건다) + nudge SessionStart(startup)에 회고 대기·판정 대기가 있으면 repo마다 하루 한 번 한 줄 명령 current 지금 폴더의 세션 기록 경로 usage [기록 경로|uuid] 세션 기록의 실측(JSON). 하위 에이전트 기록(/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. 장부: /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": diff --git a/plugins/harness/skills/estimate/SKILL.md b/plugins/harness/skills/estimate/SKILL.md index ba003f8..2075270 100644 --- a/plugins/harness/skills/estimate/SKILL.md +++ b/plugins/harness/skills/estimate/SKILL.md @@ -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 줄 diff --git a/plugins/harness/skills/retro/SKILL.md b/plugins/harness/skills/retro/SKILL.md index 75c98a6..f7ec098 100644 --- a/plugins/harness/skills/retro/SKILL.md +++ b/plugins/harness/skills/retro/SKILL.md @@ -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`(되돌린 커밋)를 쓴다. 그다음 같은 이유를 다른 단계로 다시 고른다. +- 판단할 실측이 아직 모자라면 쓰지 않고 기다린다. diff --git a/plugins/harness/tests/test_hooks.py b/plugins/harness/tests/test_hooks.py index c0cff9c..4ad4504 100644 --- a/plugins/harness/tests/test_hooks.py +++ b/plugins/harness/tests/test_hooks.py @@ -214,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): diff --git a/template/docs/ledger/README.md b/template/docs/ledger/README.md index 9890e66..17114d5 100644 --- a/template/docs/ledger/README.md +++ b/template/docs/ledger/README.md @@ -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`는 판정을 내린 작업 이름이다.