feat(plugin): 회고 루프를 처음 돌리고 장부가 다음 회고를 부르게 한다 #1

Merged
donghyeon.kang merged 4 commits from donghyeon.kang/harness-retro-loop AGit into main 2026-11-08 14:27:20 +00:00
Owner

무엇을, 왜

예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이었다. 예측과 실측의 차이가 다음 예측과 하네스를 고치는 부분이 한 번도 돌지 않았다. 이 PR은 그 루프를 처음 돌리고(회고 기록), 다음부터 저절로 돌게 한다(플러그인 0.2.0).

  • 첫 회고: docs/retro/2026-11-08.md. design-docs 위임 장부 55줄(작업 49)과 백엔드 템플릿 예측 장부 3작업, 이 repo 1작업. 빗나간 42줄 중 지시 모호 34, 예측 근거 없음 4, 착수 전 조사 부족 2, 외부 대기 2.
  • 치우침: 예측 장부 4건이 모두 p30 아래. 실측/p50 중앙값 시간 0.43 · 호출 0.52 · 출력 0.53.
  • 보정: ledger.py precedents 끝에 보정 줄, estimate 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄.
  • 루프 자동화: pending이 회고 대기와 판정 대기를 센다. SessionStart 넛지 ledger.py nudge(repo마다 하루 한 번 한 줄)를 건다. append가 예측 밖 실측을 쓸 때 한 줄 알린다.
  • 되돌림 기록: retro 줄에 fix·applied_at, 새 줄 verdict(effective·reverted).

고른 방법과 버린 대안

  • 넛지는 장부 훅(session-start)과 따로 건다. 장부 훅의 「출력 0」 규칙을 지키기 위해서다. 매 세션 넛지는 버렸다. 하위 세션마다 같은 줄이 컨텍스트에 쌓인다. 그래서 startup일 때만, worktree를 git common dir로 묶어 20시간에 한 번만 낸다.
  • 효과 판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건으로 한다. 개선 전에 예측한 작업은 영향을 받지 않았다. 1건은 우연이 크다.
  • 위임 장부에는 시간 예측이 없다. 그래서 「질문·위반·재작업·불일치·소유자 개입 없이 끝난다」를 예측으로 봤다. 막힘만 있는 줄은 게이트가 제 일을 한 것이라 뺐다.
  • H12 rm 빈틈(아래)은 판정 코드를 고치지 않고 시험에 expectedFailure로 표시했다. H12 절은 전역 훅과 같이 바꿔야 한다(AGENTS.md 3번). skip은 버렸다. 고쳐져도 알리지 않기 때문이다.

위험과 영향

  • 넛지는 그 repo의 그날 첫 세션이 하위 세션이어도 나온다. 문구에 「맡은 일이 회고가 아니면 넘긴다」를 넣었다.
  • 백엔드 템플릿 장부에는 retro 줄이 아직 없다. 그래서 그 repo에서는 하루 한 번 넛지가 나온다. 더할 3줄은 회고 문서 7절에 있다(범위 밖이라 쓰지 않았다).
  • 보정 규칙은 같은 4건으로 잰 값이라 효과를 아직 모른다. calib-median으로 다음 2건 뒤 판정한다.
  • 이 repo를 .claude/worktrees/… worktree에서 시험하면 H12가 rm -rf ./*(worktree 자신)와 rm -rf ../옆-worktree를 통과시킨다. 이 PR 전부터 있던 빈틈이다. main checkout에서는 이전처럼 막힌다.
  • 위임 장부의 원인은 lessons 한 줄을 읽고 붙였다. 세션 기록까지 다시 보지는 않았다.

검증

  • scripts/check.sh rc=0: 플러그인 시험 21개 OK(expected failure 1), 템플릿 시험 10개 OK, claude plugin validate --strict 둘 통과.
  • 새 조건 15개(startup 필터, 20시간 제한, p30·p80 판정, why, 판정된 개선 빼기, 2건 기준, 자기 작업 빼기, 회고된 작업 빼기, verdict의 fix·effect 검사, 적용 시각 비교, 중앙값, append 알림, 여러 장부, p30 아래 건수)를 하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다.
  • 백엔드 템플릿 장부에 nudge를 돌리면 한 줄이 나온다: 「회고 안 한 빗나간 예측 3건」. 상태 폴더는 임시 폴더로 돌렸다.
  • 플러그인을 설치해 새 세션에서 넛지가 뜨는지는 보지 않았다. 병합 뒤 claude plugin marketplace update claude-harness와 새 세션이 필요하다.

리뷰어가 볼 곳

  • plugins/harness/scripts/ledger.py: missed·retro_due·open_fixes·bias·hook_nudge, cmd_append의 verdict 검사와 알림.
  • plugins/harness/hooks/hooks.json: SessionStart 두 번째 훅.
  • docs/retro/2026-11-08.md 6절: 다른 repo·설정 후보 C1~C7.

관련

  • 하네스 설계 design-docs harness/01-harness-design.md, 장부 칸 conventions/delegation-loop.md 8절.
  • 이 repo의 결정 docs/README.md 10·11번.
## 무엇을, 왜 예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이었다. 예측과 실측의 차이가 다음 예측과 하네스를 고치는 부분이 한 번도 돌지 않았다. 이 PR은 그 루프를 처음 돌리고(회고 기록), 다음부터 저절로 돌게 한다(플러그인 0.2.0). - 첫 회고: `docs/retro/2026-11-08.md`. design-docs 위임 장부 55줄(작업 49)과 백엔드 템플릿 예측 장부 3작업, 이 repo 1작업. 빗나간 42줄 중 지시 모호 34, 예측 근거 없음 4, 착수 전 조사 부족 2, 외부 대기 2. - 치우침: 예측 장부 4건이 모두 p30 아래. 실측/p50 중앙값 시간 0.43 · 호출 0.52 · 출력 0.53. - 보정: `ledger.py precedents` 끝에 보정 줄, `estimate` 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄. - 루프 자동화: `pending`이 회고 대기와 판정 대기를 센다. SessionStart 넛지 `ledger.py nudge`(repo마다 하루 한 번 한 줄)를 건다. `append`가 예측 밖 실측을 쓸 때 한 줄 알린다. - 되돌림 기록: retro 줄에 `fix`·`applied_at`, 새 줄 `verdict`(`effective`·`reverted`). ## 고른 방법과 버린 대안 - 넛지는 장부 훅(session-start)과 따로 건다. 장부 훅의 「출력 0」 규칙을 지키기 위해서다. 매 세션 넛지는 버렸다. 하위 세션마다 같은 줄이 컨텍스트에 쌓인다. 그래서 startup일 때만, worktree를 git common dir로 묶어 20시간에 한 번만 낸다. - 효과 판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건으로 한다. 개선 전에 예측한 작업은 영향을 받지 않았다. 1건은 우연이 크다. - 위임 장부에는 시간 예측이 없다. 그래서 「질문·위반·재작업·불일치·소유자 개입 없이 끝난다」를 예측으로 봤다. 막힘만 있는 줄은 게이트가 제 일을 한 것이라 뺐다. - H12 rm 빈틈(아래)은 판정 코드를 고치지 않고 시험에 `expectedFailure`로 표시했다. H12 절은 전역 훅과 같이 바꿔야 한다(AGENTS.md 3번). skip은 버렸다. 고쳐져도 알리지 않기 때문이다. ## 위험과 영향 - 넛지는 그 repo의 그날 첫 세션이 하위 세션이어도 나온다. 문구에 「맡은 일이 회고가 아니면 넘긴다」를 넣었다. - 백엔드 템플릿 장부에는 retro 줄이 아직 없다. 그래서 그 repo에서는 하루 한 번 넛지가 나온다. 더할 3줄은 회고 문서 7절에 있다(범위 밖이라 쓰지 않았다). - 보정 규칙은 같은 4건으로 잰 값이라 효과를 아직 모른다. `calib-median`으로 다음 2건 뒤 판정한다. - 이 repo를 `.claude/worktrees/…` worktree에서 시험하면 H12가 `rm -rf ./*`(worktree 자신)와 `rm -rf ../옆-worktree`를 통과시킨다. 이 PR 전부터 있던 빈틈이다. main checkout에서는 이전처럼 막힌다. - 위임 장부의 원인은 lessons 한 줄을 읽고 붙였다. 세션 기록까지 다시 보지는 않았다. ## 검증 - `scripts/check.sh` rc=0: 플러그인 시험 21개 OK(expected failure 1), 템플릿 시험 10개 OK, `claude plugin validate --strict` 둘 통과. - 새 조건 15개(startup 필터, 20시간 제한, p30·p80 판정, why, 판정된 개선 빼기, 2건 기준, 자기 작업 빼기, 회고된 작업 빼기, verdict의 fix·effect 검사, 적용 시각 비교, 중앙값, append 알림, 여러 장부, p30 아래 건수)를 하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다. - 백엔드 템플릿 장부에 `nudge`를 돌리면 한 줄이 나온다: 「회고 안 한 빗나간 예측 3건」. 상태 폴더는 임시 폴더로 돌렸다. - 플러그인을 설치해 새 세션에서 넛지가 뜨는지는 보지 않았다. 병합 뒤 `claude plugin marketplace update claude-harness`와 새 세션이 필요하다. ## 리뷰어가 볼 곳 - `plugins/harness/scripts/ledger.py`: `missed`·`retro_due`·`open_fixes`·`bias`·`hook_nudge`, `cmd_append`의 verdict 검사와 알림. - `plugins/harness/hooks/hooks.json`: SessionStart 두 번째 훅. - `docs/retro/2026-11-08.md` 6절: 다른 repo·설정 후보 C1~C7. ## 관련 - 하네스 설계 design-docs `harness/01-harness-design.md`, 장부 칸 `conventions/delegation-loop.md` 8절. - 이 repo의 결정 `docs/README.md` 10·11번.
donghyeon.kang added 4 commits 2026-11-08 14:10:57 +00:00
문제: 이 repo를 `.claude/worktrees/<이름>` worktree에서 시험하면
GuardBashTest.test_rm_outside_or_too_broad_is_blocked가 실패한다.
H12 허용 폴더에 main checkout(git common dir의 부모)이 들어가서,
worktree 자신을 지우는 `rm -rf ./*`와 옆 worktree를 지우는
`rm -rf ../x`가 「작업 폴더 안」으로 통과한다. main checkout에서
돌리면 통과하는 시험이라 지금까지 보이지 않았다.

고른 방법: 두 사례를 따로 떼어, main checkout 안 worktree에서 돌 때만
expectedFailure로 둔다. 판정 코드는 고치지 않았다. H12 절은 소유자
기계의 전역 훅과 같이 바꿔야 하고(AGENTS.md 3번), 전역 훅은 이 작업
범위 밖이다. 버린 대안: 시험의 cwd를 main checkout으로 옮기기(빈틈을
가린다), skip(고쳐져도 알리지 않는다). expectedFailure는 고쳐지면
「뜻밖의 통과」로 시험이 실패해 표시를 지우게 만든다.

위험: worktree 세션에서 위 두 명령은 여전히 막히지 않는다.
전역 훅과 플러그인을 같이 고치는 작업이 따로 필요하다.

검증: worktree에서 python3 -m unittest discover -s plugins/harness/tests
→ OK (expected failures=1). main checkout에서는 예전처럼 통과로 돈다
(NESTED_WORKTREE가 거짓이면 데코레이터가 없다).
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 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).
문제: design-docs 위임 장부 55줄과 백엔드 템플릿 예측 장부 6줄이
쌓였는데 원인을 나눈 회고가 한 번도 없었다.

고른 방법: retro 스킬의 일곱 원인으로 빗나간 줄마다 원인 하나를
붙였다. 위임 장부에는 시간 예측이 없어서 「질문·위반·재작업·불일치·
소유자 개입 없이 끝난다」를 예측으로 보고, 막힘만 있는 줄은 게이트가
제 일을 한 것이라 뺐다. 결과: 빗나간 42줄 중 지시 모호 34, 예측 근거
없음 4, 착수 전 조사 부족 2, 외부 대기 2. 예측 장부 4건은 모두 p30
아래였고 실측/p50 중앙값은 시간 0.43·호출 0.52·출력 0.53이다.
H11 보고 언어 훅과 매뉴얼 빈틈 수정 1~3차는 장부 숫자로 효과를
판정했다. 다른 repo·설정에서 고칠 후보 일곱 개(C1~C7)를 적었다.
이 repo 장부에는 이 작업의 예측 줄과 h2-harness-repo의 retro 줄
(fix calib-median)을 더했다.

위험: 위임 장부의 원인은 lessons 한 줄을 읽고 붙인 것이라 세션
기록까지 다시 보지 않았다. 백엔드 장부의 retro 줄은 그 repo에 쓰지
않고 문서 7절에 더할 줄로만 두었다(범위 밖).

검증: scripts/check.sh rc=0. ledger.py pending → 회고할 줄 없음,
판정 대기 calib-median 뒤 실측 0건.
donghyeon.kang merged commit ce240d66f1 into main 2026-11-08 14:27:20 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/claude-harness#1