Files
clean-architecture-backend-…/docs/work/evidence.md
T
DongHyeonka 73d39212f5 docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
  delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다

고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
  답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
  decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
  않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
  (operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
  desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
  reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
  (고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.

위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
  소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
  README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다

검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
  improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
  432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
  트리 3d0e5900을 만들고 flock 아래
  :app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
  건너뜀 0, 13초, 직전 1분 부하 3.13
  (desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
2026-11-06 23:18:47 +09:00

30 KiB

근거와 이력

docs/work/ 본문은 지난 리뷰를 모르는 사람도 읽을 수 있게 썼다. 그래서 규칙이 나온 사건과 지난 리뷰 ID는 본문에 넣지 않고 여기에 모았다. 본문을 따르는 데 이 문서는 필요 없다. 규칙의 이유를 확인하거나 규칙을 바꾸려 할 때 읽는다.

표기: 1101/05-01은 docs/reviews/2026-11-01-maturity-review/의 발견 05-01이다. 1103/RR6-01-05는 docs/reviews/2026-11-03-rereview/의 발견이다. 접두어와 문서: RR-는 1차 재리뷰(폴더 바로 아래 0107 영역 문서)와 round2의 0103 영역 문서(1차 번호를 이어 썼다), RR2-는 round2의 04 영역 문서, RR3-RR7-는 round3round7이다. 1101 README, 1103 README는 각 폴더의 README.md다. 「결정 N」은 docs/reviews/2026-09-25-review-followup-status.md 「소유자 결정」의 N번이다.

1. 이 매뉴얼이 나온 곳

  • 조사와 설계: design-docs delegation-loop/01-research.md(15단계), delegation-loop/02-design.md(6단계, 4·5·6·7·10절). 2026-11-06 소유자가 결정 D1D14를 모두 권하는 안대로 승인했다.
  • 공통 정본: design-docs conventions/work-thinking-order.md(작업 사고 순서), conventions/delegation-loop.md(위임 루프 운영).
  • 재료: 옛 개선 매뉴얼 브랜치 claude/improvement-manual-6ae516(커밋 3b66358e, 319cff91, 06477350, 2026-11-05). 병합하지 않고 설계 10절 표대로 옮겼다(결정 D12).
  • 옛 매뉴얼을 버린 이유(2026-11-06 소유자 판정): 조사 없이 만들었다, 범위가 리뷰·수정뿐이다, 본문 159줄에 지난 리뷰 ID가 있다, 진입 분량이 717줄이다, 시험한 적이 없다.

옛 매뉴얼에서 옮긴 곳:

옛 위치 새 위치
README 「정본 표」, 적용 범위 docs/work/README.md 1·7절, 각 playbook
결정 M-5(저장소 밖 문서는 코드 표기), M-6(소유자 환경 규칙은 한 절에만) docs-writing.md 4절, operate.md 4.1절
결정 M-3(심각도 두 체계) reference/review-criteria.md 3절
결정 M-4(결정 표는 색인) reference/decisions.md 머리말
결정 M-7(커밋 정책은 두고 예외만) docs/work/README.md 4절, AGENTS.md 커밋 문장
결정 M-8(개선 제안도 닫는다) reference/review-criteria.md 1절
결정 M-9(분업과 "Minor도 고친다"의 저장소 안 정본) improve.md 4.5절, delegate.md
결정 M-1(위치 docs/improvement/), M-2(프론트와 장 번호 맞추기) 버림. 위치는 docs/work/, 두 repo는 장 번호 대신 같은 playbook 파일 이름을 쓴다
01장 판정표, 0절 공통 단계, 1~6절 docs/work/README.md 3절, improve.md
02장 reference/review-criteria.md(지난 예는 이 문서 5절)
03장 reference/review-criteria.md 9절
04장 P1~P11 reference/defect-patterns.md 「막는 기준」
05장 reference/review-criteria.md 7절, improve.md 4.2·4.3절
06장 reference/review-criteria.md 8절, reference/gates.md 5절, 기준선은 이 문서 6절
07장 reference/gates.md, operate.md
08장 reference/decisions.md
09장 delegate.md, improve.md 4.4·4.5절, design-docs conventions/delegation-loop.md
부록 결함 패턴 reference/defect-patterns.md + 이 문서 4절

2. 규칙과 사건

규칙(본문 위치) 사건 근거
무거운 실행은 desktop에서, 공유 잠금으로 (operate.md 4.1) 2026-11-05 하위 세션 넷이 노트북에서 Gradle을 돌려 노트북 부하가 22까지 올랐다 1103 README 17.1절, design-docs delegation-loop/01-research.md 4.2절
진입 분량 상한, 본문 이력 ID 금지 (docs/work/README.md 8절) 옛 개선 매뉴얼은 진입 717줄, 이력 ID가 든 본문 159줄 01-research.md 4.1절
색인은 기계로 대조한다 (improve.md 4.1) 원래 리뷰 색인이 119건이었다. 06 영역 문서의 NN-10~NN-14 5건이 색인과 모든 수정 묶음에서 빠졌다. 실제는 124건 1101 README 12절 정정, 1103 README 1절, 1103/RR-05-10
「새로 가정하는 것」 칸, 수정 묶음 크기 상한 (improve.md 4.4, 8절) round6 발견 25건 중 17건(68%)을 직전 수정 커밋이 만들었다. 짝 프론트 1106 리뷰도 25건 중 16건(64%) 01-research.md 4.3절, design-docs delegation-loop/02-design.md 4.3절
보고한 태스크가 로그에 있는지 확인 (improve.md 9절, gates.md 4절) 묶음 보고가 없는 태스크 :adapter:outbound:persistence-jpa:documentContractTest를 적었다 1103 README 17.2절
성능 lane은 상한을 매번 단언하고, 끄는 값은 테스트 전에 실패한다 (gates.md 5절) r10 desktop 게이트의 performanceCheck가 -Pperformance.assertions.enabled=true 없이 돌아, httpclient 시간 단언 없이 통과했다. 그 전에는 JPA pool lane이 같은 속성 뒤에 숨어 상한을 비교하지 않았다(PoolLaneClaimTest). 2026-11-06 빌드가 강제하게 바꿨다 desktop ~/r10-logs/gates.sh, docs/testing/TESTING_STRATEGY.md PERFORMANCE 문단, 커밋 e6b6e18e
캐시에서 가져온 결과는 지금 통과한다는 증거가 아니다. 기준 상태와 시간·환경에 민감한 테스트는 --rerun으로 (operate.md 9절, gates.md 6절) 2026-11-06 B3 desktop ci rc=0은 캐시 결과였다(태스크 701개 중 403개를 캐시에서). 그 사이 httpclient CircuitBreakerStatusAccountingTest 2건은 기준 커밋 3d73b6f1에서도 10번 중 10번 실패하고 있었다 desktop ~/b3-logs/ci.log, 2026-11-06 총괄 전달
묶음을 너무 크게 만들지 않는다 (delegate.md 4.2) 알림·파일 서버를 한 묶음(r2-05a)으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다. 다음 라운드(r3-a)에 다시 올려 합쳤다 1101 README 14.3절, 16절
두 묶음이 같은 파일을 건드리지 않게 (delegate.md 4.2) 2라운드 묶음 r2-06이 10개 파일 충돌로 처음부터 다시 작업했다 1101 README 14.1절
전 leaf import를 바꾸는 묶음은 마지막에 혼자 (improve.md 6절, delegate.md 4.2) r3-G 1101 README 15.1절
묶음마다 그 시점 최신 기준에서 시작 (delegate.md 4.2) 3라운드가 2라운드보다 충돌이 적었다 1101 README 16.1절
합친 트리는 따로 검증 (improve.md 4.4, gates.md 3절) 두 묶음의 수정이 한 트리에서 처음 만나 BC_IMPOSSIBLE_INSTANCEOF가 생겼다. 최종 게이트에서 드러난 2건 1101 README 16.1절, 1103 README 6.1절
캐시로 통과한 것은 그렇게 적는다 (gates.md 4절) ci가 434초에서 51초로 준 것은 캐시 재사용이었다 1101 README 16.2절
같은 결함은 한 묶음에만 (delegate.md 4.2) 같은 runbook 문장을 두 리뷰가 적어 한 번 고쳤다(1103/RR6-01-07, 1103/RR6-02-03) 1103 README 17절
RED가 머신에 따라 통과하지 않게 (improve.md 7절) watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서 옛 코드도 통과시켰다 1103/RR4-03-01, 1103 README 16절 r9-b
실 vendor 결함은 실 vendor에서 RED (improve.md 4.2) 새 실 PostgreSQL 테스트 3개의 수정 전 실패를 실 PostgreSQL로 확인하지 않았다 1101 README 14절 r2-04
Agent 도구를 쓰지 않는다 (delegate.md 4.3) 하위 세션 시작이 막히자 Agent 하위 에이전트로 우회했다. 지난 라운드는 사용량 한도 때문에도 하위 에이전트 없이 진행했다 01-research.md 4.2절, 1101 README 16절, 1103 README 6절
예전 멈춤 기준을 거둠 (improve.md 4.5) 2026-11-05 소유자 지시 "보고할 때 남은 문제가 없어야 한다". "새 Important 0이면 멈춤"(9.1절), "Minor는 기록만"(11.1절)을 거뒀다 1103 README 16절
종료 조건은 repo마다 (improve.md 4.5) 2026-11-05 소유자 원문 "각자 유지" 2026-11-05 총괄 세션 전달

3. 수정 묶음 크기 (improve.md 4.4)

추가 줄은 git show --shortstat의 insertions다(테스트·문서 포함).

수정 커밋 고친 것 추가 줄 다음 확인 리뷰 그 리뷰의 발견
01a8a2a70..5786126c(커밋 3개) 원래 리뷰 발견 +60,167 1차 재리뷰 Important 27, Minor 41
bbe944bd 1차 재리뷰 발견 + 색인에서 빠졌던 5건 +13,479 round2 Important 7, Minor 22
1885bf8d 2차 재리뷰 결함 29건 +5,495 round3 Important 0, Minor 19
f40c03c6 Minor 19건(영역 묶음 4개) +1,877 round4 Important 0, Minor 7
70fb80bf 소유자가 다시 정한 기본값 3가지 +906 round5 Important 0, Minor 9
45d2a478 기록만 했던 결함 전부(영역 묶음 4개) +5,420 round6 Important 2, Minor 23(17건은 이 커밋이 만듦)
6e992970 round6 결함 25건(영역 묶음 4개) +5,143 아직 없음 —

읽는 법: 추가 2,000줄 아래 두 번은 다음 발견이 7·9건, 5,000줄 위 네 번은 19·25·29·68건이었다. 상한(묶음 8건, 확인 리뷰당 1,500줄)은 이 표에서 정한 판단 값이다. 위임 루프 지표(라운드당 새 결함, 수정이 만든 결함 비율)로 다시 맞춘다.

4. 결함 패턴의 근거 (reference/defect-patterns.md)

패턴 근거
A1 갈라진 복사본 1101/01-03, 1101/01-07, 1101/04-06, 1101/05-09, 1101/07-06, 1101/01-11, 1103/RR-01-14, 1101 README 16.3절(템플릿 패키지 목록 두 곳), 1103 README 16절 r9-c(버전 정규식 사본)
A2 문서와 코드 불일치 1101/02-01, 1101/07-11, 1101/03-04, 1101/06-11, 1103/RR-01-03, 1103/RR-01-11, 1103/RR5-01-01, 1103/RR6-02-05, 1103/RR6-03-05, 1103/RR6-04-05
A3 선언과 실행이 떨어져 있다 1101/05-15, 1101/03-11, 1101/02-03, 1101/07-06, 1103/RR-06-01, 1103/RR2-04-03, 1103 README 6.1절(redis.capability.* 6개)
A4 결과 불명을 확실함으로 1101/05-01, 1101/04-01, 1101/06-01, 1101/05-17, 1101/05-11, 1103/RR-02-03, 1103/RR-01-11, 1101 README 4절 원인 1
A5 중복·경쟁을 코드 순서로 1101/09-02, 1101/04-08, 1101/04-02, 1101/03-10, 1101/04-13, 1103/RR-03-01, 1103/RR-02-04
A6 주장하는 것을 보지 않는 테스트 1101/05-08, 1101/02-02, 1101/01-05, 1103 README 14절(CountDownLatch 7건), 1103/RR4-03-01, 1103/RR6-01-08, 1103/RR6-02-02
A7 거짓 통과 게이트 1101/08-01, 1101/04-04, 1101/03-12, 1103/RR-06-02, 1103/RR-06-03, 1103/RR-04-05, 1103 README 14절(테스트 SpotBugs 53개), 1103/RR3-04-02, 1103/RR6-04-01, r10 desktop performanceCheck(2절)
A8 로그로 새는 입력값·원인 1103/RR6-01-05, 1103/RR6-01-06, 1103 README 16절 r9-a, 1101/02-11, 1101/01-04
A9 이름만 보는 허용·거부 1103/RR-07-02, 1103/RR2-04-02, 1103/RR2-04-01, 1101/07-14
A10 글로만 있는 규칙 1103/RR-01-02, 1101/04-03, 1101/05-16
A11 샘플·fixture가 운영과 다르게 조립 1101/07-03, 1101/09-03, 1101/09-08, 1101/07-04, 1101/01-02, 1101/07-09
A12 수정이 새 결함을 만든다 1103 README 1절(Important 27), 9절, 1103/RR6-01-01(회귀), 1101 README 16.1절, 1103 README 6.1절, round6 68%(2절)
A13 합치는 과정의 누락 1101 README 12절 정정, 1101 README 14.1절(충돌 처리 목록)
A14 타이밍에 기댄 약속 1103 README 16.1절(ClientRuntimeRegistry.close), 1103/RR3-03-01, 1101/05-06
A15 사라지는 외부 공급원 1101/05-09, 1101/08-04
A16 상한 없는 자원 1101/03-06, 1101/03-09, 1101/04-10, 1101/02-09, 1101/04-12

5. 리뷰 기준의 예 (reference/review-criteria.md)

결함의 모양(1절): 이름과 다른 동작 1101/05-03(ONLY_IF_SOURCE_REVISION_NEWER가 조건 없이 덮어씀), HARD-STOP 위반 1101/07-08(기본 조립 루트가 선택 capability를 앎), 갈라진 복사본 1101/01-03(TenantId 3벌)·1101/04-06(SQLState 표 2벌), 막지 못하는 게이트 1101/05-08(소유자 검사를 지워도 442개 통과)·1101/08-01(어떤 workflow도 돌리지 않는 strict lane 14개), 틀린 조치를 시키는 문서 1103/RR-05-01(DEAD 재발행 SQL을 따르면 다시 DEAD), 기본값 뒤에 숨은 위험 1101/02-03(JWT audience가 비면 검증을 건너뜀).

성격(2절): 구조적 위험 1101 README 6절, 미검증 1103 README 10.3절(CI runner가 꺼져 있다).

심각도(3절): 전체 리뷰 체계는 1101 README 12절. High 예 1101/05-01, 1101/04-02, 1101/02-03. Medium 예 1101/04-06, 1101/04-05. Low 예 1101/07-11. 확인 리뷰 체계는 1103 README 2절 이후 모든 round, Important 기준은 1103 README 11절, Minor 예는 1103/round4/review.md·round6/. "이번 커밋 / 이전부터"는 1103/round6/04-build-logic.md 「결론」. Minor도 고친다는 규칙은 1103 README 16절, High·Important 재확인은 1101 README 2절.

증거 수준(4절): 이전 결과를 쓰지 않은 예 1101/09-performance-measurement.md 1절, 섞인 증거 수준 표기 예 1103/round6/03-persistence.md RR6-03-01.

통제 수준(5절): M0 예 2026-11-01 시점 JPA 양방향 연관관계 금지(1101/04-03), M1 예 @SystemInvoked를 bean으로 등록하지 말라는 주석(1103/RR-01-02), M4 예 DB 유일 제약(1101/09-02 수정 뒤).

28개 관점(6절)의 지난 예: 1 1101/05-03 · 2 1101/07-08, 1101/08-05 · 3 1101/01-07 · 4 1101/01-01, 1101/07-09 · 5 1101/02-03, 1103/RR-07-02 · 6 1101/04-01, 1101/06-01, 1101/05-01 · 7 1103/RR-05-01, 1103 README 6.1절 · 8 1103 README 16절 r9-a, 1101/01-04 · 9 1101/04-06, 1101/07-11 · 10 1101/05-08, 1101/02-02 · 11 1101/09-02, 1103/RR-02-09 · 12 1101/04-02, 1101/03-10 · 13 1101/03-06, 1101/03-09 · 14 1101/09-01, 1101/09-02 · 15 1101/02-03, 1101/07-03, 1103/RR6-01-05 · 16 1101/05-09, 1101/09-09 · 17 1101/02-01, 1101/02-02 · 18 1101/07-04, 1101/06-02 · 19 1101/05-15, 1101/07-06 · 20 1103/RR-01-01, 1103/RR-01-03 · 21 1101/08-01, 1103/RR-06-02, 1103 README 14절 · 22 1101/04-13 · 23 1101/01-03, 1101/01-12 · 24 1101/05-21 · 25 1101/01-10 · 26 1101/04-16 · 27 1101/07-08, 1101/05-19 · 28 1101/03-10, 1101/06-03.

시나리오(6절)의 지난 추적: 1101/01-core-and-feature-pattern.md 4.1·4.2·4.4절, 1101/09-performance-measurement.md 5.1~5.3절, 1101/05-05·05-06·05-01, 1101/04-01·04-05, 1103/RR-03-03, 1101/06-01, 1103/RR-03-02, 1103/RR-02-09·RR-02-10, 1101/04-02·03-10, 1101/05-08, 1101/03-01·02-09, 1101/06-02·07-07, 1101/08-build-ci-test.md 4절.

테스트 점검표(7절): 1103/RR6-01-08, 1101/02-02, 1101/05-08, 1103 README 14절, 1103/RR6-02-02, 1103/RR6-01-03, 1103 README 17절 r10-01, 1103 README 16.1절. fake 예 1103/RR-01-04, 1103 README 17절 r10-02(손 사본 20건 삭제, skip 17 → 0).

리뷰 문서 양식(10절): 전체 리뷰 README는 1101 README 절 순서, 영역 문서는 1101/01-core-and-feature-pattern.md, 확인 리뷰 문서는 1103/round6/*.md, 확인 리뷰 발견 필드는 1103/round6/03-persistence.md RR6-03-01, 전체 리뷰 발견 필드는 1101/08-build-ci-test.md 08-01.

6. 성능 기준선 (improve.md 4.3)

잰 커밋과 함께만 쓴다. 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서 다시 재고 이 표와 비교한다.

측정 값 커밋·출처
기본 조합 bootJar / 기동 중앙값 / 빈 수 41.4 MB / 3.44 s / 407 01a8a2a70, 1101/09-performance-measurement.md 3.1절
샘플 bootJar / 기동 중앙값 / 빈 수 99.0 MB / 8.05 s / 603 같음
필터 체인만 지나는 요청 27,130 rps, p50 0.51 ms 같은 문서 3.4절 (d)
샘플 단건 조회 5,521 rps, p50 2.70 ms, SQL 7개 같은 문서 3.2·3.3절
샘플 목록 20건 829 rps, p50 15.54 ms, SQL 46개 같음(수정 전)
샘플 목록 20건(수정 뒤) SQL 46 → 6, 765 → 2,528 rps 1101 README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음)
관측 기능 비용 처리량 약 3% 같은 문서 3.4절 (b)
가상 스레드 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) 같은 문서 3.3절
설정만 바꾼 실험 hibernate.default_batch_fetch_size=100만으로 목록 처리량 2.9배 같은 문서 3.4절
게이트 시간(desktop, 12코어·31GB) ci+verifyDependencyLocks 5분 42초, mainCheck 8분 8초, integrationCheck 17분 10초 2c692554, 1103 README 17.2절

측정 스크립트(run-app.sh, Load.java, sqlcount.sh)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 1101/09-performance-measurement.md 「측정 명령 (다시 돌리는 법)」으로 다시 만든다.

7. 리뷰 색인 대조 결과 (2026-11-06)

scripts/check-review-index.py를 지난 리뷰 폴더 두 곳에 돌린 결과다(기준 커밋 3d73b6f1).

폴더 명령 영역 문서 발견 색인에 있음 없음 rc
docs/reviews/2026-11-01-maturity-review/ --index-heading "12. 발견 색인" 124 124 0 0
docs/reviews/2026-11-03-rereview/ README 전체 157 135 22 1
  • 2026-11-01 폴더: 지금은 모두 있다. 같은 검사를 사고 시점 커밋 34565130의 폴더에 돌리면 NN-10~NN-14 5건을 "자리표시자 영역"으로 잡고 rc=1로 실패한다. 이 검사가 그 사고를 막았을 것이다.
  • 2026-11-03 폴더의 22건은 처리되지 않은 발견이 아니라 README가 ID로 적지 않은 발견이다.
    • RR-05-10(색인 누락 5건 자체에 대한 발견)은 README 1절 정정과 6.1절이 내용으로 다룬다.
    • RR-07-05(CSRF 제외 규칙의 이유)는 README 6절 r4-f 행이 내용으로 다룬다.
    • 나머지 20건은 round6 Minor다(RR6-01-0206·08·09, RR6-02-02·04·05, RR6-03-0205, RR6-04-01~06). README 17절은 영역별 건수만 적었고, r10 묶음이 영역 단위로 고쳤다.
  • 이 검사는 "색인에 이름이 있나"만 본다. 고쳤는지는 처리 표와 확인 리뷰가 본다. 앞으로의 리뷰 README는 모든 ID를 이름으로 적는다(improve.md 4.1절 7단계).

8. docs/manual/에서 걷어낸 이력 ID (2026-11-06)

docs/manual/ 본문에서 리뷰 ID와 번호만 쓴 결정을 걷어냈다. 문장의 뜻은 그대로이고, 괄호 안 근거만 여기로 옮겼다. 줄 번호는 걷어내기 전 기준 커밋 06f520e6의 줄이다.

원래 위치 원래 괄호 지금 본문 근거
docs/manual/05-idempotency.md:57 "재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본 docs/web/http-contract.md 2절" 정본 가리킴만 남겼다 1103/RR5-01-05(PostgreSQL 기본 모양에서는 lease 상황이 생기지 않는다, round5/review.md), 1103/RR6-02-05(매뉴얼 첫 문장이 PostgreSQL 항목과 어긋났다, round6/02-idempotency-outbound.md)
docs/manual/05-idempotency.md:78 "라운드6 RR6-02-01" "2026-11-05 확인 리뷰가 찾아 고쳤다" 1103/RR6-02-01(LEASE_EXPIRED로 거절당한 attempt를 다시 보내도 503만 받았다, round6/02-idempotency-outbound.md). 수정 커밋 6e992970(2026-11-05), 1103 README 17절 r10-02
docs/manual/05-idempotency.md:81 "재리뷰 2026-11-04 RR-01-11·RR-03-11" IdempotencyStoreContract 가리킴만 남겼다 1103/RR-01-11(lease가 지난 실행 기록을 Redis가 넘겨받아 다시 실행했다, round2/01-core-app-inbound.md), 1103/RR-03-11(replay TTL이 lease보다 짧으면 key가 lease 도중 사라졌다, round2/03-outbound.md). 수정 커밋 1885bf8d(2026-11-04)
docs/manual/05-idempotency.md:84 "RR3-03-02, 2026-11-04 소유자 결정" "2026-11-04 소유자 결정" 1103/RR3-03-02(서버가 기억하는 기간 문서가 failure-retention을 빠뜨렸다, round3/03-outbound.md)
docs/manual/07-authorization.md:98, :115 "D4 문단", "D4 실패" "권한 선언 검사 문단", "쓰기 유스케이스의 권한 선언 검사 실패" D4는 인증·인가 계약 설계(feature-authentication-authorization-contract)의 결정 번호로, 규칙 MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION을 가리킨다. 그 설계 문서는 이 repo에 없다. ApplicationBoundaryArchitectureTest의 주석 "D1 / D4"와 1101/01-core-and-feature-pattern.md 「ArchUnit D4」가 같은 번호다
docs/manual/08-testing.md:38 "소유자 결정 5" "2026-09-25 소유자 결정" docs/reviews/2026-09-25-review-followup-status.md 「소유자 결정」 5번(@DisplayName은 한국어)
docs/manual/09-outbox-events.md:78 "재리뷰 2차 RR-02-10" runbook 가리킴만 남겼다 1103/RR-02-10(tenant scope가 바뀌는 배포의 rolling 구간에서 새 번호가 옛 버전이 쓴 번호보다 작다, round2/02-persistence-messaging.md)
docs/manual/09-outbox-events.md:89 "재리뷰 RR-05-03" runbook 가리킴만 남겼다 1103/RR-05-03(끝나지 않는 재시도 행을 운영자가 구분·처분할 수단이 없었다, 05-messaging.md)
  • RR-01-11·RR-02-10·RR-03-11은 2차 재리뷰(round2/) 문서의 발견이다. 그 문서들은 1차 번호에 이어 RR- 접두어를 그대로 썼다(머리말 「표기」).

9. cold-read 시험 1회차 빈틈 처리 (2026-11-06)

2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을 시켰다(기준선 1개는 옛 매뉴얼). 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 1~9건씩 나와 모두 불합격이었다. 아래는 시험 기록(design-docs delegation-loop/trials/2026-11-06-*.md)의 「질문」·「위반」 표와 각 세션 공유 노트(~/.config/Claude/side-session-notes/local_fcd89c34-c754-4c5b-a38f-fa322834286f/)의 「매뉴얼에서 답을 못 찾은 곳」을 한 줄씩 처리한 결과다. 기준 커밋 2c8a359d.

  • 세션: T1 c-t1-r10-review(확인 리뷰), B c-t1-baseline(같은 리뷰를 옛 매뉴얼로, 기준선), T2 c-t2-circuit-breaker(결함 수정), T3 c-t3-error-codes(조사·설계 → 구현), T4 c-t4-manual-ids(문서), T5 c-t5-idempotency-opid(결함 수정).
  • 출처 칸: 기록 N은 시험 기록 「질문」 표의 N번, 노트 N은 공유 노트의 N번이다. T3 노트는 1단계 1-N, 2단계 2-N이다.
  • 처리 칸: 고침(고친 곳) / 고치지 않음(이유) / 소유자 결정 필요. 기준선(B)은 새 매뉴얼에도 해당하는 것만 고쳤다.
# 출처 빈틈 처리
T1-1 기록 1, 노트 1 상한을 넘어 나눈 확인 리뷰를 한 세션이 차례로 해도 되나 고침 — improve.md 4.4절: 나누는 것은 맡긴 쪽, brief 하나로 받으면 차례로, 단위마다 문서 하나
T1-2 노트 2 영역 pathspec이 파일 단위로 안 갈림, 수정 커밋 안의 리뷰 기록을 상한에서 빼나 고침 — improve.md 4.4절: 리뷰 기록 docs/reviews/** 제외, 테스트 파일은 지키는 코드의 영역
T1-3 기록 2, 노트 3 수정 보고에 「새로 가정하는 것」 칸이 없을 때 고침 — improve.md 4.1절 2단계: 커밋 본문 「위험·한계」와 처리 표 「결정」에서 뽑고 뽑은 곳을 적는다
T1-4 기록 3, 노트 4 지난 라운드 색인 누락으로 색인 검사가 처음부터 rc=1 고침 — improve.md 4.1절 8단계: 이번 색인 절에 「색인 보완」 한 줄
T1-5 기록 4, 노트 5 리뷰 README를 누가 쓰나: delegate.md(총괄)와 improve.md(리뷰어)가 다름 — 모순 고침 — improve.md 4.1절 7단계, delegate.md 4.2절 표, reference/decisions.md 2.1 「리뷰 README 분담」: 리뷰어는 자기 라운드 색인 절 하나, 나머지는 총괄
T1-6 기록 5, 노트 6 지난 라운드 영역을 나눌 때 영역 번호 고침 — reference/review-criteria.md 10절 「ID」: 그 라운드 영역 표의 순번, 나누면 뒤에 새 번호, 「범위」에 대응
T1-7 기록 6, 노트 7 클래스 이름으로 고르는 strict lane에서 탐침 돌리기 고침 — improve.md 9절(자주 하는 실수): 기존 클래스에 메서드로, -Werror 주의
T1-8 기록 7, 노트 8 --rerun이 바로 앞 태스크에만 걸림 고침 — operate.md 9절, reference/gates.md 6절: 태스크마다 붙인다
T1-9 노트 9 지난 라운드 Declined 30건이 닫힌 기록 없음, 확인 리뷰어가 다시 판정하나 고침 — improve.md 4.1절 9단계(brief가 맡겼을 때만), delegate.md 4.1절(확인 리뷰 brief에 적는다)
T1-10 기록 8, 노트 10 같은 범위를 두 리뷰가 같은 라운드 ID로 씀 고침 — reference/review-criteria.md 10절 「ID」(정본 리뷰 하나, 다른 쪽은 새 ID와 대응표), delegate.md 9절
T1-11 기록 9, 노트 11 다른 브랜치 병합을 기다리는 Declined는 닫힌 것인가 고침 — improve.md 4.5절 2: 합친 트리에서 확인할 때까지 열림
B-1 기록 1, 노트 1 한 리뷰어가 모든 영역을 볼 때 문서 모양 고침 — reference/review-criteria.md 10절 「위치」: roundN/NN-<영역>.md, 영역마다 하나
B-2 기록 2, 노트 2 리뷰어가 리뷰 README에 쓰나 고침 — T1-5와 같은 곳
B-3 기록 3, 노트 3 strict lane 탐침, 탐침에도 -Werror 고침 — T1-7과 같은 곳
B-4 기록 4, 노트 4 확인 리뷰에 넣을 「이전부터」 결함의 경계 고침 — improve.md 4.1절 3단계: 읽은 주변 코드에서 본 것은 적고, 그 밖을 찾아 나서지 않는다
B-5 기록 5, 노트 5 앞 라운드 Declined가 닫히지 않은 채 시작 고침 — T1-9와 같은 곳
B-6 기록 6, 노트 6 리뷰 스킬은 하위 에이전트를 쓰라 하고 매뉴얼은 금지 — 모순 고치지 않음 — 새 매뉴얼에 답이 있다: improve.md 3절 끝 줄, delegate.md 4.3절. 새 매뉴얼로 같은 리뷰를 한 T1은 묻지 않았다
B-7 기록 7, 노트 7 리뷰 기록 문서도 document-contract lane 대상인가 고침 — reference/gates.md 2절, docs-writing.md 4절 9단계: 읽는 테스트를 파일·폴더로 찾고, 없으면 돌리지 않고 grep 결과를 적는다
T2-1 기록 1 push한 커밋은 못 고치고 desktop은 push된 것만 받는다. 커밋 본문에 desktop 결과를 넣으려면 고침 — operate.md 2절·4.1절 「push 전에 검증하기」(패치와 트리 해시)·9절, design-docs conventions/delegation-loop.md 11절 「실행 위치」
T3-1 기록 1, 노트 1-1 「파일 하나여도 큼」 표면에 대한 설계 메모만 쓰는 일의 크기 고침 — design-docs conventions/work-thinking-order.md 2.1절, research-design.md 3절, 스킬 research-first
T3-2 기록 5, 노트 1-2 push 허용: docs/work/README.md 4절·decisions.md는 "커밋·push", 정본 11절은 "push는 소유자" — 모순 고침 — 커밋과 push를 brief 7절이 따로 허용한다: docs/work/README.md 4절, reference/decisions.md 2.1, delegate.md 2·4.1·6절, 루트 CLAUDE.md 5절, design-docs conventions/delegation-loop.md 2·3·4.1·11절, 스킬 delegate
T3-3 기록 2, 노트 1-3 탐침을 생략해도 되는 기준 고침 — research-design.md 4절 3단계
T3-4 기록 3, 노트 1-4 파생 서비스 영향을 어떻게 확인하나 고침 — research-design.md 4절 5단계, design-docs conventions/delegation-loop.md 11절 「세션」(파생 서비스 위치)
T3-5 기록 4, 노트 1-5 조사·설계에서 범위 밖 결함을 어디에 적나 고침 — docs/work/README.md 6절: 모든 보고에 「범위 밖에서 본 것」
T3-6 기록 4, 노트 1-6 하위 세션이 Slack 브리핑을 하나 고침 — design-docs conventions/delegation-loop.md 4.1절 7절 칸·11절 「보고」, reference/decisions.md 2.1 「하위 세션 보고」: 전역 규칙 그대로, brief가 "Slack 말고"면 안 보냄
T3-7 기록 4, 노트 2-1 push 전에 RED를 보려면 desktop에 무엇을 보내나 고침 — operate.md 4.1절 「push 전에 검증하기」 RED 줄
T3-8 기록 4, 노트 2-2 커밋 본문 「검증」 칸과 push 순서 고침 — T2-1과 같은 곳
T3-9 기록 4, 노트 2-3 git add -p 없이 한 파일을 두 커밋으로 나눠 stage 고침 — design-docs conventions/delegation-loop.md 11절 「커밋과 병합」(패치 hunk를 지우고 git apply --cached)
T4-1 기록 1, 노트 「스크립트가 못 잡는 이력 ID」 --history가 "리뷰 NN-NN"·"N라운드 NN-NN"을 못 잡아 0이 나와도 16줄 남음 고침 — scripts/check-work-docs.py 패턴 셋, docs-writing.md 9절. 새로 드러난 docs/manual/ 16줄은 고치지 않음 — 이번 범위 밖, 2회차 시험 과제
T4-2 기록 2 바꾼 문서를 읽는 테스트가 없을 때 무엇을 돌리나 고침 — B-7과 같은 곳
T4-3 기록 3 이 문서 머리말의 ID 표기가 실제(2차 재리뷰도 RR-)와 다름 — 모순 고침 — 이 문서 머리말 「표기」(접두어별 문서), 8절 끝 줄
T4-4 기록 4 원래 문서가 repo에 없는 결정 번호 고침 — docs-writing.md 4절 6단계
T4-5 기록 5 하위 세션이 Slack 브리핑을 하나 고침 — T3-6과 같은 곳
T5-1 기록 1 설계서 둘과 포트 Javadoc이 서로 다를 때 무엇을 따르나 고침 — improve.md 7절: 결정이 없으면 고르지 않고 양쪽 근거로 묻는다
T5-2 기록 2 소유자 지시로 생긴 큰 변경도 따로 멈춰야 하나 고침 — design-docs conventions/work-thinking-order.md 2.3절, 스킬 research-first
T5-V 기록 「위반」 1 총괄 보고를 영어로 씀 고침 — docs/work/README.md 6절, design-docs conventions/delegation-loop.md 5·11절. 훅으로는 막지 않는다(보고 문장은 도구 호출이 아니라 훅이 볼 수 없다)
  • 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 리뷰 방식을 바꿀지는 매뉴얼 규칙으로 넣지 않고 소유자에게 물을 제안으로 남겼다(매뉴얼 수정 세션 보고).
  • 「자주 하는 실수」에 넣은 줄: improve.md(strict lane 탐침), operate.md(--rerun 범위를 기존 줄에 더함, push 뒤 검증), docs-writing.md(--history 0을 믿음), delegate.md(두 리뷰의 ID).