cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.
넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.
버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).
위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.
검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).
- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.
버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.
위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.
검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).
- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
→ 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
가리키기, skills-lock.json 없음)을 더했다.
버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).
위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.
검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.
BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).
- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
따르는지 본다.
버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).
위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.
검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.
BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).
scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
--skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
(DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).
버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).
위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.
검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.
BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).
- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
.claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
.claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
.claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
읽는다. 단언은 그대로다.
버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.
위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.
검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.
BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).
고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.
위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.
검증(트리 f43dbc29, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/C-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0, check-review-index.py 2026-11-03-rereview rc=0
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- MongoNamespaceContractTest --rerun rc=0(3건)
- 테스트 수 세는 명령은 desktop의 지난 결과 XML로 시험했다
문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 README 색인 절은 총괄이 쓴다. 그래서 정본
리뷰어가 커밋한 트리의 색인 검사는 반드시 rc=1인데, improve.md는 리뷰어에게
rc=0을 요구했다(round8 발견 RR8-06-01). 두 규칙을 함께 지킬 수 없었다.
고른 방법: check-review-index.py에 --extra-index <파일>을 더했다. 리뷰어가
보고에 둔 색인 표 파일을 색인의 일부로 센다. improve.md 4.1절 7·8단계와 5절,
delegate.md 4.1절, 결정 색인 「리뷰 README 분담」에 쓰는 법을 적었다. 버린 안:
리뷰가 권한 "보고 표를 붙인 README 임시 사본" 절차 — 복사·붙이기 단계가 늘고
같은 대조를 손으로 한다. 정본 리뷰어가 README 색인 절을 먼저 쓰는 안 — 결정
「리뷰 README 분담」을 뒤집는다.
위험·한계: --extra-index는 넘긴 파일 전체를 색인으로 읽는다. 표만 담은 파일을
넘겨야 한다(노트 전체를 넘기면 본문에 나온 ID도 색인으로 센다). 매뉴얼에
"색인 표만 담은 파일"로 적었다.
검증(트리 3c305d7a, desktop 로그 ~/manual-gap-fix-2-logs/B-*):
- RED: 정본 리뷰어 커밋 27260ad0의 리뷰 폴더에 옵션 없이 rc=1(180 중 172)
- GREEN: 리뷰어 A의 색인 표를 --extra-index로 넘기면 rc=0(180/180)
- 지금 트리 docs/reviews/2026-11-03-rereview rc=0(182/182), 없는 파일을
넘기면 rc=1
- check-work-docs.py 기본·--history docs/manual·--links rc=0
Refs: docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md RR8-06-01
문제: 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-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)
문제: 이 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에서 돌린다