feat(plugin): 장부가 회고 대기와 효과 판정을 세고 세션 시작에 알린다
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 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).
This commit is contained in:
@@ -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":
|
||||
|
||||
Reference in New Issue
Block a user