Files
claude-harness/docs/retro/2026-11-08.md
T
DongHyeonka 403716f0f4 docs(retro): 두 장부의 첫 회고 표와 보정 숫자를 남긴다
문제: 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건.
2026-11-08 23:09:32 +09:00

14 KiB

회고 2026-11-08 — 자기 개선 루프 첫 회전

장부 줄은 쌓였는데 회고한 줄이 0이었다. 예측과 실측의 차이가 다음 예측과 하네스를 고치는 부분이 한 번도 돌지 않았다. 이 문서가 첫 회고다.

장부 두 곳 ──> 빗나간 줄마다 원인 하나 ──> 원인별 건수 ──> 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자)
                                                         └─> 이 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.450.79, 호출 0.600.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이 병합된 뒤에 더한다.

{"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번째 줄)이다.