Commit Graph
12 Commits
Author SHA1 Message Date
DongHyeonka 447a77a35d docs(work): 운영 playbook 시험에서 나온 게이트 실행 빈틈 여섯을 닫는다
문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
  http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
  명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
  앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
  dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
  remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다

고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
  (다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
  더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
  pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
  로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
  실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.

위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
  한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
  objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
  범위 밖)

검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
  delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
  본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
  걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
  7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
  --rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
  직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
  --history docs/manual 16줄 rc=1(기대대로)
  (desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
  (desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
2026-11-07 00:35:12 +09:00
DongHyeonka b619c44298 docs(work): 세 경우의 확인 리뷰를 독립 리뷰어 둘로 하고 총괄이 합친다
문제: 2026-11-06 같은 커밋을 두 세션이 따로 확인 리뷰했더니 합친 결함
8건 중 1건만 겹쳤다. 라운드의 Important 2건도 한 리뷰어의 첫 리뷰 밖에서
나왔다. 반복은 마지막 확인 리뷰의 0건으로 멈추는데, 리뷰어 하나의 0은
남은 결함이 0이라는 증거로 약하다.

고른 방법: 2026-11-07 소유자 결정("(c)로 받기")대로 세 경우에만
서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 보고 총괄이 합친다.
- 멈추는 확인 리뷰: 리뷰어 하나가 0을 내면 두 번째가 본다. 둘 다 0이어야
  멈춘다(improve.md 4.5 1)
- 수정 diff가 상한에 가까운 리뷰: 추가 1,000줄 이상
- Critical·Important를 고친 수정의 리뷰
정본 리뷰어만 리뷰 폴더에 커밋하고 ID를 매긴다. 다른 쪽은 보고에 같은
양식을 두고 임시 번호 B-NN-MM을 쓴다. 합칠 때 총괄이 같은 결함끼리
짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어가 탐침으로 다시 확인해 다음
번호로 넣는다. 겹침 비율을 색인 절과 지표 기록(M11)에 적는다.
버린 대안: 언제나 둘(비용 약 2배), 지금처럼 하나(멈춤 판정이 약함).
소유자가 2~3라운드 겹침 비율을 보고 다시 정한다.

위험·한계:
- "상한에 가까움"을 추가 1,000줄 이상으로 정한 것은 기본값이다
  (decisions.md 2.1에 적음)
- 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립성은 brief의
  금지 문장과 노트 이름 분리에 기대고, 막는 장치는 없다
- 같은 범위를 두 번 보므로 그 리뷰의 비용이 약 두 배다

검증: 이 커밋의 트리에서 python3 scripts/check-work-docs.py rc=0. desktop 검증은 다음 커밋의 트리로 했다(그 커밋 본문)
2026-11-07 00:28:14 +09:00
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
DongHyeonka 2c8a359d32 docs(work): 소유자 결정 네 건을 결정 색인에 적는다
round7 확인 리뷰와 멱등 저장소 수정(t5)이 소유자 결정 네 건을 남겼고,
소유자가 2026-11-06 모두 권하는 안으로 정했다. 다음 수정 묶음이 다시
묻지 않도록 결정 색인의 해당 절에 내용과 출처를 적는다.

- 계약·오류: 네 전송이 원인 사슬의 첫 carrier를 본다
- 멱등성: 넘겨받기 전 핸들의 재전송은 적용한 핸들에게만 확인한다,
  해제된 핸들의 start는 ABSENT와 NOT_OWNER를 둘 다 받는다
- 영속성: 실패한 동시 인덱스 마이그레이션은 그 버전의 실패 이력 행만
  지우고 다시 배포한다
- 빌드·게이트: paths 필터 trigger만 있는 workflow는 단계 실행으로
  세지 않는다

검증: scripts/check-work-docs.py rc=0.
2026-11-06 22:57:15 +09:00
DongHyeonka 0fa01019d0 Merge remote-tracking branch 'origin/claude/t5-idempotency-operation-id-9bd973' into claude/integration-r7 2026-11-06 22:56:39 +09:00
DongHyeonka ddf174cdbc Merge remote-tracking branch 'origin/claude/t3-error-codes-loglevel-fcf427' into claude/integration-r7 2026-11-06 22:56:39 +09:00
DongHyeonka 200019aa5c fix(idempotency)!: 두 멱등 저장소가 operation id·release·inspect에 같게 답한다
문제: 같은 호출에 Redis와 PostgreSQL 저장소(와 in-memory fake)가 다르게
답한다.
- owner token이 같아도 호출이 claim과 다른 operation id를 대면 Redis는
  다섯 전이(start·renew·complete·fail·release)를 OPERATION_CONFLICT로
  거절하고 PostgreSQL·fake는 적용한다. PostgreSQL은 CAS에 핸들의 claim
  operation만 쓰고 호출의 id는 last_transition_operation_id에 적기만 한다.
- PostgreSQL complete 재생은 operation id만 보고 owner를 보지 않아, 같은
  id를 쓴 다른 attempt의 늦은 complete를 이미 적용된 완료로 확인한다.
  Redis는 NOT_OWNER.
- fake의 claim·inspect는 같은 token·다른 operation에 OwnerOperationConflict
  ·OPERATION_CONFLICT를 내지 않는다. PostgreSQL·fake의 inspect는 완료된
  기록이면 그 응답을 재생하고 Redis는 OPERATION_CONFLICT.
- 기록이 없는 release에 Redis는 ALREADY_RELEASED_SAME_OPERATION, PostgreSQL
  ·fake는 ABSENT. Redis release는 revision을 보지 않아, 같은 attempt가 claim을
  넘겨받기 전 핸들로 지금의 claim을 지운다.

방법: 소유자 결정 (a)로 PostgreSQL·fake를 Redis에 맞춘다. owner token이
같고 호출 id가 기록의 claim id와 다르면 다섯 전이 모두 OPERATION_CONFLICT,
기록은 그대로. 나머지 셋은 "거절이 안전한 쪽, 운영 호출자 경로가 안 바뀌는
쪽"으로 정했다.
- complete 재생은 같은 owner token에만 확인한다(Redis에 맞춤).
- fake claim은 진행 중 기록에 OwnerOperationConflict, inspect는 같은 token·
  다른 operation이면 상태와 상관없이 OPERATION_CONFLICT. PostgreSQL inspect도
  완료 재생보다 이 검사를 먼저 한다.
- 기록 없는 release는 셋 다 ABSENT. Redis adapter가 ABSENT를 그대로 넘기고
  RELEASE 스크립트와 command fake가 핸들 revision을 본다. release한 기록을
  지울지 남길지는 저장소 선택이라 release 재시도는 ABSENT(Redis·fake)와
  ALREADY_RELEASED_SAME_OPERATION(PostgreSQL)으로 갈리는 것을 계약이 허용한다.
버린 대안: Redis를 PostgreSQL에 맞추기(Redis에는 전이 id를 둘 필드가 없어
인자가 죽는다), PostgreSQL release를 삭제로 바꾸기(release 뒤 기록 모양은
계약이 저장소 선택으로 정해 두었다), 기록 없는 release를 셋 다
ALREADY_RELEASED로(찾지 못한 것을 성공으로 확인한다 — JPA 설계 22.2와 반대).
공유 계약 IdempotencyStoreContract에 12케이스를 더했다. 포트·결과 enum
Javadoc, persistence-jpa·cache-redis README, TESTING_STRATEGY, application-core
CLAUDE.md, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.

위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 늘 claim의 id를 넘기고
release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 전이마다
다른 id를 넘기던 코드는 OPERATION_CONFLICT를 받는다. PostgreSQL 통합
테스트가 그렇게 쓰고 있어 claim의 id로 바꿨다. last_transition_operation_id
열은 이제 늘 claim_operation_id와 같다(마이그레이션은 건드리지 않음).
같은 token의 넘겨받기 전 핸들로 이미 끝난 complete·markFailed를 다시 보내는
경우는 저장소마다 답이 다르다(범위 밖, 보고에 적음).

검증: desktop, 공유 잠금, 기준 06f520e6.
- RED(기준 커밋 + 계약만): in-memory fake 계약 49 중 8 실패, Redis
  command fake 2, 실 Redis(redisContainerContractTest) 2, 실 PostgreSQL
  (jpaPlatformContractTest) 7 — 실패 메시지가 위 차이 그대로("expected:
  OPERATION_CONFLICT but was: STARTED", "expected: ABSENT but was:
  ALREADY_RELEASED_SAME_OPERATION" 등).
- GREEN(이 커밋과 같은 트리): 네 leaf check(application-core 412·skip 19
  시간 케이스, persistence-jpa 664, cache-redis 215, redis-runtime 65),
  네 leaf testQualityCheck, jpaPlatformContractTest 419,
  postgresqlIdempotencyIntegrationTest 10, redisContainerContractTest 90,
  app-bootstrap integrationTest 10, sample integrationTest 63,
  documentContractTest 65, architectureTest 228, composition:idempotency
  check 32 — 모두 rc=0, 실패·skip 0(fake 시간 케이스 19 제외).
- scripts/check-work-docs.py, --links docs, git diff --check 통과.

Refs: docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md Declined to judge
BREAKING CHANGE: 멱등 store 포트를 직접 부르는 코드는 전이마다 claim의
operation id(IdempotencyOwner.claimOperationId())를 넘겨야 한다. 다른 id는
OPERATION_CONFLICT다. Redis release는 기록이 없으면 ABSENT를 돌려준다.
직접 구현한 store는 IdempotencyStoreContract의 새 케이스를 통과해야 한다.
2026-11-06 22:25:45 +09:00
DongHyeonka e0beeca214 fix(error-codes)!: 레지스트리에서 log_level 칸을 지운다
문제: docs/registries/error-codes.yaml의 log_level 칸은 읽는 코드가 없다.
로그 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다
(ServerFailureLog, AuthErrorResponseWriter). 그래서 그 코드를 내는 곳이 있는
47행 중 33행이 실제 레벨과 달랐고, 런북 2곳이 틀린 레벨을 증상으로 적었다.

고른 방법: 칸을 지우고, 머리말이 레벨을 정하는 코드를 가리킨다(설계 메모 안
A, 소유자 결정 2026-11-06). 칸이 다시 생기지 않게
OperationalErrorRegistryContractTest에 단언을 둔다. client_safe_message를
코드에 고정한 테스트가 있는 자리다. 모든 레지스트리의 공통 스키마를 보는
ContractRegistrySchemaGovernanceTest는 한 레지스트리의 칸 뜻을 다루지 않아
고르지 않았다. 런북은 실제 로그 줄을 증상으로 적는다. 결정 색인 2.3절과
설계 메모 10절에 결정을 남겼다.
버린 대안: 칸을 코드에 맞추고 테스트로 고정(B) — 규칙의 손 사본이 생기고,
템플릿이 내지 않는 13행은 고정할 값이 없다. 칸을 규범으로 만들어 코드가
읽기(C) — 4xx를 남기지 않는 설계를 뒤집고 로그 양이 는다.

위험·한계: 자기 error-codes.yaml 행에 log_level을 둔 파생 서비스는 merge
뒤 mainCheck(documentContractTest)가 실패한다. upgrade 안내 「반드시 할 일」
17과 B-44에 적었다. repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다(소유자
결정 4).

검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 yaml로 OperationalErrorRegistryContractTest 3건 중
  noRegistryRowCarriesALogLevel 1건 실패(log_level이 있는 행 목록 출력).
  rc=1, red-registry.log
- GREEN: :app-bootstrap:documentContractTest rc=0, 66건 실패 0
  (RunbookCoverageContractTest 포함). green-doc-contract.log
- :app-bootstrap:testQualityCheck :app-bootstrap:spotlessCheck rc=0.
  green-quality.log
- python3 scripts/check-work-docs.py rc=0, --links docs 깨진 링크 0

BREAKING CHANGE: error-codes.yaml 행에 log_level이 있으면
OperationalErrorRegistryContractTest가 실패한다. 파생 서비스는 자기 행에서
log_level: 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다.
2026-11-06 22:17:13 +09:00
DongHyeonka aef713b3c5 docs(manual): 본문의 이력 ID를 걷어내고 근거를 evidence로 옮긴다
docs/manual/ 본문 9줄에 리뷰 ID(RR-, RR3-, RR5-, RR6-), 설계 결정 번호(D4),
번호만 쓴 소유자 결정("소유자 결정 5")이 있었다. 지난 리뷰를 모르는
독자는 이 괄호를 따라갈 수 없고, docs-writing.md 4절 6단계가 금지한다.

괄호 안의 ID만 걷어내고 문장의 뜻은 바꾸지 않았다. 지난 일을 근거로 든
곳은 날짜와 내용으로 바꿨다(2026-11-05 확인 리뷰, 2026-09-25 소유자 결정).
D4는 규칙 이름 대신 "쓰기 유스케이스의 권한 선언 검사"로 풀었다. 걷어낸
ID와 원래 괄호, 원래 리뷰 문서는 docs/work/evidence.md 8절에 모았다.
리뷰 문서로 링크를 거는 안은 본문이 다시 이력을 가리키게 되어 버렸다.

검사 스크립트 패턴이 못 잡는 "리뷰 NN-NN", "1라운드 NN-NN" 꼴의 ID는
이 커밋 범위 밖이라 남겼다.

검증: python3 scripts/check-work-docs.py --history docs/manual
(lines with history IDs: 0, rc=0), check-work-docs.py 전체 rc=0,
--links docs 깨진 링크 0. document-contract lane은 desktop에서 돌린다.
2026-11-06 21:44:33 +09:00
DongHyeonka 06f520e667 docs(work): 성능 lane 단언 강제와 캐시 결과의 한계를 매뉴얼에 맞춘다
문제: 성능 lane 단언을 빌드가 강제하게 된 뒤에도 docs/work/는 옛 동작을
안내했다. gates.md 5절은 "desktop에서 -Pperformance.assertions.enabled=true를
준다. 안 주면 httpclient의 시간 단언 없이 통과한다"고 했고, 3절 라운드 끝
명령과 improve.md·operate.md의 「자주 하는 실수」도 그 속성을 맞추라고 했다.
지금은 convention이 단언을 켜고 true 아닌 값이나 skip이 있으면 테스트 전에
실패하므로, 그 문장은 틀렸고 그 속성은 필요 없다. 또 2026-11-06 B3 desktop
ci rc=0은 캐시 결과(태스크 701개 중 403개)였는데, 그 사이 httpclient
CircuitBreakerStatusAccountingTest 2건은 기준 커밋에서도 10번 중 10번 실패하고
있었다. 캐시 결과를 현재 통과의 증거로 쓰면 이런 기존 결함을 놓친다.

고른 방법:
- gates.md 5절을 새 동작으로 다시 쓰고(정본 AGENTS.md 「Gradle 정책 권위」,
  docs/testing/TESTING_STRATEGY.md), 1절 표와 6절 거짓 통과 표를 맞췄다.
  3절 명령에서는 그 속성을 뺐다. workflow도 이제 주지 않는다.
- improve.md의 같은 실수 줄은 지웠다. 빌드가 막으므로 더는 실수가 아니다.
- operate.md 「자주 하는 실수」의 그 줄 자리에 캐시 교훈을 넣었다: 기준 상태와
  시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. gates.md
  6절에도 한 줄, 근거는 evidence.md 2절, 결정은 decisions.md 2.7, 장치는
  defect-patterns.md A7에 더했다.

위험·한계: --rerun은 지정한 태스크 하나만 다시 돈다. 집계 태스크 전체를 캐시
없이 돌리려면 --rerun-tasks가 필요하고 시간이 훨씬 길다. 이 매뉴얼은 그 둘을
가르는 기준까지는 정하지 않았다.

검증
- python3 scripts/check-work-docs.py: rc=0, 본문 이력 ID 0줄, improve.md
  131/150, operate.md 115/150
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 깨진 링크 0
2026-11-06 21:30:26 +09:00
DongHyeonka d04de2e85f docs(work): 확인 리뷰 상한을 넘는 한 커밋은 영역 pathspec으로 나눈다
문제: improve.md 4.4절은 확인 리뷰 하나가 보는 수정 diff를 추가 1,500줄로
묶고, 넘으면 "묶음 커밋별로" 나누라고만 했다. 여러 영역 묶음을 한 커밋에
합친 수정(예: 영역 묶음 넷을 합친 +5,143줄 커밋)은 커밋으로 나눌 수 없어,
그 확인 리뷰를 맡은 세션이 어떻게 나눌지 답이 없었다.

고른 방법: 커밋이 따로 있으면 커밋별로, 한 커밋에 섞였으면 영역 pathspec별로
`git diff --shortstat <base>..<head> -- <pathspec>`를 재서 각각 상한 안이 되게
나눈다. 지난 확인 리뷰도 영역 4개를 pathspec으로 나눠 봤다.

위험·한계: pathspec 하나가 그 자체로 1,500줄을 넘으면 더 나눌 기준은 아직
없다. 그때는 그 영역을 맡은 리뷰를 둘로 나누거나 맡긴 쪽에 묻는다.

검증
- python3 scripts/check-work-docs.py: rc=0, improve.md 132/150
2026-11-06 20:00:49 +09:00
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).

고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
  AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
  곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
  내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
  reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
  (new-feature, improve, research-design, docs-writing, operate, delegate, 모두
  같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
  decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
  review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
  나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
  improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
  수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
  수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
  +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
  README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
  (reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
  docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
  CLAUDE.md 「Layer workflow」를 가리키던 줄).

위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.

검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
  playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
  .guidanceNamesTheArchitectureSourceSetTask가 기대하는
  "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
  이 커밋을 push한 뒤 desktop에서 돌린다
2026-11-06 19:58:44 +09:00