템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).
지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
integration-main.yml optional 성능 단계와 job
grpc-optional-platform-integration, release.yml job
grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
adopter API 표면 검사의 optional-build 제외 경로
남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).
살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.
위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.
검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.
BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
착수 예측(21:46, p30 150분·호출 450·출력 45만) 뒤 끝 보고 직전의 실측을
세션 기록에서 뽑아 같은 task로 한 줄 더한다: 벽시계 94분, 작업 중 68분, 호출
270, 출력 34.6만 토큰, 다시 읽은 입력 1.33억 토큰, 최대 컨텍스트 80.5만. 모두
p30 안이다. 틀린 이유와 다음에 바꿀 근거는 줄의 why 칸에 있다.
작업 중 시간의 정의를 선례(design-docs harness 설계 14절)가 잰 방식과 같게
「빈틈을 5분까지만 더한 시간」으로 README에 적었다.
검증: test_ledger(예측보다 뒤의 실측, 구간 판정), check-docs, check-work-docs rc=0.
매뉴얼 보강 묶음이 각 빈틈을 어디에 넣었는지, 넣지 않았으면 왜인지를 다음
cold-read 시험과 총괄 대조가 찾을 곳이 없다. 1·2회차는 evidence.md 9·11절에
처리 표를 두었다. 같은 방식으로 12절을 더한다.
- 22행: 3회차 빈틈 9건(R3-1~R3-8), 장부의 통합·배치·문서·번역 세션 빈틈,
공유 노트 목록, repo-structure 세 문서의 매뉴얼 규칙. 고침 21행(기본값 2),
고치지 않음 1행(design-docs 몫).
- 리뷰 ID와 세션 이름은 이 근거 문서에만 둔다(매뉴얼 본문 이력 ID 0 규칙).
검증: check-work-docs, check-docs rc=0.
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md`
한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고
CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이
된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다.
- check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든
src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다
(build 출력 제외).
- scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄·
CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가
네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위
규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄,
하위 규칙의 깨진 링크.
- gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가
보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의
검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다).
위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서
지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로
두고 시험은 상한을 낮춰 계산식을 본다.
검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두
rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md,
첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다.
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.
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.
- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
docs-system.md 6.2절 다섯 칸)을 더했다.
버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).
위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).
검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 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행.
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).
- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.
위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.
검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.
BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
문제: cb67b879는 `docs/upgrade/2026-11-maturity-review.md` 머리의 「커밋:」 목록에
「의존성 취약점 수정(3.7절 B-54)」을 더했다. 그 안내는 PR #2(03a313ed)로 이미
main에 합쳐졌다. 결정 색인 「아직 합치지 않은 업그레이드 안내」는 합쳐진 안내를
고치지 말고 새 행을 더하라고 한다. 머리의 「범위:」도 main → 리뷰 브랜치라 V1을
포함하지 않는다.
고친 방법: 머리 「커밋:」 목록을 main과 같게 되돌리고, 3.7절 첫머리에 이 절의
범위(`5ab1b418..claude/v1-vuln-fix-e089b9`)와 머리를 고치지 않은 이유를 적는다.
B-54 행은 그대로다. 이제 이 파일의 main과의 차이는 3.7절 하나다.
검증: check-docs.py rc=0, check-work-docs.py rc=0.
main(b3f63be6, 문서 2단계 통합 PR #3)을 V1 브랜치에 합친다. 충돌은 없었다.
- docs/web/repository-adaptation.md: V1이 숫자를 고쳤다가 되돌려(23f04afb) 기준과
같았으므로 main의 번역(숫자 없이 카탈로그를 가리킴)이 그대로 들어왔다.
- src/adapter/outbound/persistence-jpa/README.md: V1의 Querydsl 문장(71~75줄)과
main의 번역이 자동으로 함께 남았다.
- docs/work/reference/decisions.md, docs/upgrade/2026-11-maturity-review.md: V1이
더한 행과 main의 행이 모두 남았다.
- main 쪽에서 들어온 workflow 변경은 없다.
검증(노트북, 합친 트리): check-docs.py rc=0(넓어진 숫자 검사 포함 걸림 0),
자기 시험 OK, check-work-docs.py rc=0, check-repo-layout.py rc=0. 게이트는
desktop에서 이 커밋으로 돌린다.
문제: cb67b879가 `docs/web/repository-adaptation.md:65`의 baseline 숫자를
4.0.8에서 4.0.9로 고쳤다. 이 파일은 문서 번역 작업(D2d)이 지금 옮기고 있고,
총괄은 숫자를 하나도 고치지 않기로 정했다(2026-11-07). 번역 작업이 숫자를
복사하는 대신 정본(`src/gradle/libs.versions.toml`)을 가리키게 바꾸므로 4.0.9도
그때 맞춰진다.
고친 방법: 그 한 줄을 4.0.8로 되돌린다. 이 파일은 기준 커밋 5ab1b418과 같아진다.
- cb67b879는 이미 push해서 고쳐 쓰지 않고 되돌림 커밋을 붙인다.
위험·한계: 번역이 끝날 때까지 이 줄과 check-docs 예외로 얼린 8곳이 실제 Boot
4.0.9와 다른 숫자를 말한다.
검증: 앞 커밋과 같다(트리 fbb325c1에서 문서 검사 전부 rc=0).
`git diff 5ab1b418 -- docs/web/repository-adaptation.md`가 비어 있다.
문제: persistence-jpa README 「라이브러리 API」가 Querydsl을 쓰는 서비스에
`com.querydsl:querydsl-jpa:5.1.0:jakarta`를 직접 추가하라고 한다. 그 좌표에는
HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다.
8e3bef0f가 이 leaf를 querydsl-core로 옮겼는데, 살아 있는 문서는 아직 그
좌표를 권한다.
고친 방법: 총괄이 권한 안 A를 확인하고 이 문장도 고치라고 했다(2026-11-07).
문장을 넷으로 나눴다: 템플릿은 querydsl-core의 `Predicate`만 쓴다, JPA 질의가
필요한 서비스는 querydsl-jpa를 직접 더한다, 그 좌표 5.1.0에는 CVE-2024-49203이
있고 고친 버전이 없다, 쓰려면 OpenFeign 포크(`io.github.openfeign.querydsl`)를
검토한다. Envers 안내는 그대로다. 결정 색인 「Querydsl 취약 좌표」 행의 「누가」를
「총괄 확인 전」에서 위임(총괄 확인)으로 바꾸고 README를 출처에 더했다.
- 원래는 8e3bef0f와 같은 커밋이어야 했다. 그 커밋은 이미 push해서 고쳐 쓰지
않고 바로 뒤에 붙인다.
위험·한계: README 줄은 문서 번역 작업(D2b) 범위 안이다. 총괄이 D2b에 이 줄을
건드리지 말라고 알린다.
검증(desktop, 이 커밋과 다음 커밋을 얹은 트리 fbb325c1):
`python3 -m unittest discover -s scripts/tests` OK, `check-docs.py` rc=0,
`check-work-docs.py` rc=0, 같은 범위 상대 링크 555개 깨짐 0, `check-repo-layout.py`
rc=0. lychee(0.22.0 이미지)는 rc=2이고 실패 4건이 앞 트리와 같다(기록 문서의
404, 이 변경 전부터). 이 README를 읽는 테스트는 없다(`grep -rn --include='*.java'`).
참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가
있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를
디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는
통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을
옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈
docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다.
「있다」를 git이 아는 파일(추적 + 무시되지 않은 새 파일, 문서 목록과 같은
git ls-files)과 그 위 폴더로 바꿨다(known_paths). leaf 기준 상대 경로를
위 폴더로 올라가며 찾는 규칙은 그대로다. 무시되는 경로(src/.env 등)는
전처럼 git check-ignore가 건너뛴다.
버린 대안: 빈 폴더만 따로 빼기. 아무도 추가하지 않은 파일(디스크에만 있는
build 밖 산출물)도 같은 거짓 통과를 만든다. git이 보는 것과 같게 하면
노트북과 PR workflow가 같은 답을 낸다.
자기 시험 셋을 더했다(79 OK): 빈 폴더를 가리키는 참조가 실패, 파일이 든
폴더는 통과, 빈 폴더를 가리키는 「현재 정본」이 실패. 변이 시험: 디스크의
모든 경로를 다시 세게 하면 rc=1, 빈 폴더 시험 둘이 실패한다.
검증(노트북): check-docs.py OK(여섯 검사 걸림 0, 0.8초), 자기 시험 79 OK.
빈 docs/notification/adr/를 다시 만들어도 known_paths는 그 폴더를 모른다.
runtime-jvm-oom runbook이 「컨테이너가 코드 137로 끝난다
(-XX:+ExitOnOutOfMemoryError가 동작함)」고 적는다. 그 옵션으로 JVM이 스스로
끝나면 종료 코드는 3이고 stderr에 「Terminating due to
java.lang.OutOfMemoryError: …」가 남는다. 137은 SIGKILL이다. 힙이 아니라
프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 경우이고, 원인과
볼 것이 다르다(번역 묶음 D2c가 확인 필요로 넘긴 것).
증상 절을 둘로 나눴다: 코드 3 + 그 stderr 줄은 이 runbook, 코드 137 +
OOMKilled는 다른 일(힙과 네이티브 메모리의 합, MaxRAMPercentage가 남긴 몫,
힙 덤프 없음).
검증: desktop에서 이 저장소 이미지(caskeleton:0.0.1_local_0000000-default,
9ae52229)를 공유 잠금 아래 java -Xmx4m·-Xmx6m
-XX:+ExitOnOutOfMemoryError -jar application.jar로 띄웠다. 둘 다 rc=3,
stderr 「Terminating due to java.lang.OutOfMemoryError: Java heap space」.
노트북 check-docs.py OK.
한계: ContainerRuntimeOomContractTest Javadoc의 「exit 137」은 테스트 코드라
이 변경에서 고치지 않았다.
AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다
(docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가
남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」,
messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지
않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것).
ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은
docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸).
검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0,
check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java').
runbook 상태 어휘가 초안·운영으로 바뀌었는데(docs/runbooks/template.md,
RunbookCoverageContractTest) docs/mongodb/runbooks/의 두 runbook은 옛 값
status: active를 쓴다. 그 시험은 docs/runbooks만 보므로 걸리지 않았다
(번역 묶음 D2c가 범위 밖으로 넘긴 것).
failover.md, unknown-commit.md의 status: active → 운영(옛 active의 뜻).
본문은 바꾸지 않았다.
검증(노트북): check-docs.py OK. 살아 있는 문서의 머리말 status 중 초안·운영
밖의 값 0(git grep '^status:').
번역 묶음(D2b)이 확인하지 못하고 넘긴 대문자 식별자 넷을 코드와 대조했다.
MAX_CONCURRENT_STREAMS(RFC 9113 HTTP/2 설정 이름)와 DEFAULT_MAX_PAGE_SIZE
(Spring Data 상수)는 바깥 이름이라 맞다. 둘은 틀렸다.
- 예외 대응 표의 MaxUploadSizeExceededException 행이 「multipart 전용
413(UPLOAD_SIZE_EXCEEDED)은 이 영역의 책임 — 병합 후 정제」라고 적는다.
그런 오류 코드는 레지스트리에도 코드에도 없다.
GlobalExceptionHandler.handleMaxUploadSizeExceededException은 multipart와
JSON 본문 모두 PAYLOAD_TOO_LARGE(413)로 답한다. 그대로 적었다.
- 「클라이언트 IP」 절이 지운 모드의 이름(FORWARDED_HEADERS_TRUSTED)을 지금
있는 것처럼 인라인 코드로 적는다. 이름을 빼고, 지운 사실은 제거 표
(docs/capability-status.md 「제거된 코드」)를 가리킨다.
검증(노트북): check-docs.py OK. 이 README를 읽는 테스트는 없다
(git grep 'inbound/web/README').
src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친
두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를
「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이
문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다.
- 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다,
입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다,
쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」),
바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다.
- 「Docker Compose 최소 버전 `2.24.4`」가 정본
(compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도
값을 복사했다. 값을 지우고 정본 키를 가리킨다.
버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른
문체를 허용할 근거가 없다.
이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크
검사 범위 목록 테스트 하나만 경로를 적는다).
검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
숫자 검사(number)는 「Spring Boot 4.0.8」처럼 이름 바로 뒤에 붙은 버전만
본다. 이름과 떨어진 복사는 지나간다. 기준 커밋 03a313ed의 살아 있는
문서에 그런 복사가 넷 있었다.
- docs/web/repository-adaptation.md:65 「baseline is **4.0.8**」
(의존성 세션이 손으로 찾아 고친 줄. 그 브랜치는 **4.0.9**로 바꾼다)
- docs/compatibility/grpc-support-matrix.md:29 「| Spring Boot | 4.0.8 …」
- docs/mongodb/support-matrix.md:12 「| Spring Boot | 4.0.0 |」
- docs/jpa/repository-adaptation.md:100 「Boot 4.0.0 resolves …」
번역 묶음이 넷 모두 정본을 가리키게 고쳤지만, 검사가 막지 않으면
다시 생긴다.
규칙 셋을 더했다(Spring Boot 버전에만).
1. 이름 규칙이 「Spring」 없는 「Boot x.y.z」도 잡는다.
2. 표 행에 칸 전체가 「Spring Boot」(굵은 글씨·코드·링크를 벗긴 뒤,
뒤에 BOM·버전이 붙어도 됨)인 칸이 있으면 그 행의 세 자리 버전.
3. 정본(src/gradle/libs.versions.toml의 springBoot)과 같은 버전 문자열은
어디에 쓰든(굵은 글씨, 표 칸, 인라인 코드). 앞이 낱말·점·§이거나
뒤가 낱말·「.숫자」이면 다른 수의 일부로 보고 넘긴다(RFC §4.0.8,
14.0.8, 4.0.80, 4.0.8.1).
이름 옆 복사는 한 번만 센다(2·3이 그 안의 버전을 다시 세지 않는다).
결정 기록·제거 표·upgrade/를 빼는 범위는 그대로다(checked_for_drift).
버린 대안: 굵은 글씨 안의 모든 세 자리 버전을 잡기. 살아 있는 문서를
훑으면 Spring Boot 아닌 것이 둘 걸린다. docs/jpa/support-matrix.md의
Hibernate **7.1.8.Final**은 JpaDocumentationContractTest가 release
registry의 값과 같은지 단언하는 렌더링이라 지울 수 없다. 그것을 잡으면
굵은 글씨만 빼서 검사를 피하게 된다. 규칙 3은 정본 값을 직접 보므로,
지금 버전의 복사는 모양과 상관없이 생길 수 없고, 버전을 올리는 변경
때 옛 값의 복사가 남아 있을 수 없다.
한계: 정본 값과 다르고 이름과도 떨어진 버전(「4.0.0 / 5.0.0」 같은
문장)은 잡지 않는다. Spring Boot 밖의 버전 복사는 이 검사의 범위가
아니다(docs/README.md 「문서 검사」 number 행).
시험: 03a313ed 트리와 의존성 브랜치(cb67b879) 트리에 옛·새 검사를
돌렸다. 새 검사가 위 네 줄(의존성 브랜치는 **4.0.9**)을 더 잡고,
옛 검사가 잡던 28건은 모두 그대로 잡는다. 합친 트리는 걸림 0이라
예외를 더하거나 고칠 문서가 없다.
자기 시험 8개를 더했다(76 OK). 조건을 하나씩 끈 변이 시험 7개가 모두
rc=1이다: 옛 이름 정규식, 표 칸 규칙 끔, 정본 값 규칙 끔, 중복 세기
제거 끔, 정본 값 앞 § 허용, 정본 값 뒤 경계 끔, 칸 이름 앞부분만 맞춤.
검증(노트북): check-docs.py OK, 자기 시험 76 OK, check-work-docs.py OK.
번역 네 묶음(D2a~D2d)을 합친 트리는 문서만이 아니라 문서를 읽는
테스트의 기대 문구도 바꿨다. runbook 머리말 status 어휘(stub·active →
초안·운영), 루트 README의 「## 시작하기」, 알림 지원 매트릭스의 등급 칸
이름, 파일서버·JPA 문서의 한국어 제목과 문구, 패키지 소유 표의 머리
칸이다. 자기 runbook을 두었거나 그 문서를 고친 파생 서비스는 merge 뒤
mainCheck의 document-contract lane이 실패한다. 그런데 이것을 적은
안내가 없다. docs/README.md도 「아직 옮기지 않은 문서는 예외 목록에
있다」고 적어 지금(목록이 빔)과 맞지 않고, ADR 본문을 옮긴 사실이 「본문은
원문 그대로」라는 기록 규칙 설명과 부딪친다.
- docs/upgrade/2026-11-docs-records.md에 4절(2단계)을 더했다. 할 일
다섯과, 기대 문구가 바뀐 문서·테스트 표다. 범위·「누가 읽나」·3절의
「본문은 원문 그대로」를 2단계에 맞게 고쳤다.
- docs/README.md 「문서 수명과 언어」: 모두 옮겼고 예외 목록이 비었다,
ADR 번역은 뜻을 바꾸지 않은 옮김이고 원문은 03a313ed에 있다.
「기록 문서의 머리 블록」: ADR만 본문을 옮겼다.
버린 대안: 새 업그레이드 문서를 따로 쓰기. 같은 날 같은 문서 체계 일의
두 단계이고, 옮긴 경로 표(2절)를 2단계의 ADR 이동과 함께 한 곳에서
찾게 하는 편이 낫다.
한계: ADR 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 고치지
않았다. 그 문구는 design-docs conventions/docs-system.md가 정하고
check-docs.py가 글자 그대로 본다. 바꾸려면 정본부터 바꿔야 한다.
docs-check를 파생 서비스가 유지할지(docs/ci-cd/template-vs-consumer.md
분류)는 이 변경이 정하지 않는다.
검증(노트북): check-docs.py OK, 자기 시험 68 OK, check-work-docs.py OK.
안내의 테스트 이름·기대 문구는 각 테스트 소스에서 확인했다
(RunbookCoverageContractTest RUNBOOK_STATUSES, DeveloperExperience
ContractTest, NotificationEvidenceVerifier GRADE_COLUMN_HEADER,
NotificationReleaseGateTest, FileserverDocumentationCoverageTest,
JpaDocumentationContractTest, TemplatePackageOwnershipDocumentTest).
예외 목록은 줄기만 해야 하는데 빈틈이 있다. check-docs.py는 목록의
줄이 FROZEN에 있는지만 보고, FROZEN의 지문이 목록에 있는지는 보지
않는다. 그래서 번역해서 지운 줄의 지문이 FROZEN에 남고, 같은 줄을 다시
더해도 검사가 통과한다. 기준 커밋 03a313ed에서 이미 FROZEN 217개 중
9개가 목록에 줄이 없었다(앞 단계의 이름 바꾸기에서 남은 것).
- run()이 FROZEN - (목록 줄의 지문)을 실패로 낸다. --only와 상관없이
돈다(목록의 줄이 FROZEN에 있는지 보는 검사와 같다).
- 합친 트리의 목록이 비었으므로 FROZEN에서 217개를 모두 뺐다. 이제
목록에 어떤 줄을 더해도 실패한다.
- 설명(스크립트 머리, 예외 목록 머리 주석, docs/README.md 「문서
검사」)에 「줄을 지우면 FROZEN에서 그 지문도 뺀다」를 더했다.
스크립트 머리의 「넷 모두」를 지금의 여섯 검사로 고쳤다.
버린 대안: FROZEN을 그대로 두고 자기 시험만 더하기. 실제 검사(PR
workflow)는 자기 시험과 따로 돌므로, 목록과 FROZEN이 어긋난 트리가
check-docs.py만으로는 통과한다. 검사 자신이 막아야 한다.
자기 시험(scripts/tests/test_check_docs.py)에 셋을 더했다.
- test_a_frozen_fingerprint_whose_line_was_removed_fails: 고장 낸 입력
(빈 목록 + 지문 하나)이 language·head 어느 검사로 돌려도 실패한다.
- test_a_removed_line_added_back_fails_once_its_fingerprint_is_gone:
지문을 뺀 뒤 줄을 다시 더하면 「기준선에 없는 예외다」로 실패하고,
남은 줄에는 고아 지문 오류가 나지 않는다.
- test_every_frozen_fingerprint_has_its_line_in_the_real_exception_list:
실제 FROZEN과 실제 목록이 맞는다.
조건을 끈 변이 시험(사본에 문자열 치환, 자기 시험 실행):
- 고아 지문 검사를 지움 → rc=1, 첫째 시험 실패
- FROZEN을 03a313ed의 217개로 되돌림 → rc=1, 셋째 시험 실패.
실제 트리의 check-docs.py도 고아 지문 217건으로 실패한다.
- 둘 다(바꾸기 전 코드) → rc=1, 첫째·셋째 시험 실패
검증(노트북): check-docs.py OK(여섯 검사 걸림 0), 자기 시험 68 OK,
check-work-docs.py OK.
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다.
문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이
모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지
보기」도 두 곳을 가리킨다.
NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리
블록 그대로). 가리키던 곳을 함께 고친다.
- 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절
- scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명
- NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다
- docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령
파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가
NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면
기록 본문의 부름이 맞지 않게 된다.
위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야
한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로
필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험
(NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification:
check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다.
이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다).
검증(노트북): check-docs.py OK(language·head·reference·number·map·
readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK,
check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0.
BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
문제: 앞 커밋 아홉 개가 파생 서비스가 받는 버전을 바꿨다(Spring Boot 4.0.9,
gRPC 1.75.0, httpclient5·httpcore5, 새 `pinned-*` 고정, Querydsl 컴파일 의존,
lockfile 옛 줄). 업그레이드 안내에 행이 없으면 파생 서비스는 merge 때 lockfile
충돌과 httpcore5의 새 응답 헤더 상한을 미리 알 수 없다. 버전을 고르는 규칙과
Querydsl 처리도 결정 색인에 없어 다음 세션이 다시 묻는다.
고친 방법:
- `docs/upgrade/2026-11-maturity-review.md`: 새 3.7절과 B-54 행(무엇이 바뀌었나,
증상, 할 일, 근거 커밋). 이 안내는 아직 main에 합쳐지지 않았으므로 결정 색인
「아직 합치지 않은 업그레이드 안내」대로 머리 「커밋:」 목록에 한 항목을 더했다.
- `docs/work/reference/decisions.md` 2.7절: 「취약점이 있는 의존성 버전」(고르는
순서와 놓는 곳)과 「Querydsl 취약 좌표」 두 행. 둘 다 기본값이고, Querydsl은
총괄 확인 전이라고 적었다.
- `docs/web/repository-adaptation.md:65`: baseline 숫자 4.0.8→4.0.9만 고쳤다.
같은 숫자가 있는 다른 살아 있는 문서 8곳은 `scripts/check-docs-exceptions.txt`의
number 예외로 얼어 있어 고치지 않았다(고치면 문서 검사가 실패하고, 예외 파일은
이 작업의 범위 밖이다).
위험·한계: 위 8곳은 Boot 4.0.8로 남는다. 번역 작업이 그 문서를 옮길 때 숫자를
정본(카탈로그)을 가리키는 말로 바꾸고 예외 줄을 지워야 한다.
검증: `python3 scripts/check-docs.py` rc=0(number 걸림 28, 예외 28, 실패 0),
`python3 scripts/check-work-docs.py` rc=0. 고친 세 문서를 읽는 테스트는 없다
(`grep -rn --include='*.java'`로 파일 이름을 찾았다).
문제: persistence-jpa의 compileOnly·testImplementation
`com.querydsl:querydsl-jpa:5.1.0:jakarta`에 HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있다. 그 좌표에는 고친 버전이
없다(GHSA-6q3q-6v5j-h6vg: com.querydsl:querydsl-jpa·querydsl-apt <=5.1.0, 고친
버전 없음). trivy 37건 중 마지막 남은 한 건이다.
고친 방법: 이 leaf가 쓰는 Querydsl 타입은 `querydsl.PredicatePolicy`의
`com.querydsl.core.types.Predicate` 하나이고, 이것은 querydsl-core에 있다(공지 대상이
아니다). 그래서 두 줄을 `com.querydsl:querydsl-core`(Boot BOM이 관리하는 5.1.0)로
바꾼다. 둘 다 compileOnly·test 범위라 배포물은 원래부터 Querydsl을 싣지 않는다.
JPAQuery를 만드는 querydsl-jpa는 이 capability를 켜는 서비스가 직접 더하는 것으로
그대로 둔다(README의 안내와 같다). build.gradle 주석에 이유를 적었다.
- 버린 대안: OpenFeign 포크 `io.github.openfeign.querydsl:querydsl-jpa`(5.6.1, 6.10.1+)로
옮기기. 좌표가 바뀌어 파생 서비스가 같이 바꿔야 하고, 이 leaf에는 필요 없는 jar다.
- 버린 대안: `.trivyignore.yaml`에 90일 무시. 쓰지 않는 jar의 위험을 기한부로 안는다.
이 선택은 총괄에게 물었고 답을 받기 전에 권하는 안으로 진행했다.
위험·한계: querydsl-jpa를 직접 더하는 서비스는 여전히 고친 버전이 없는 좌표를 쓴다.
업그레이드 안내 B-54에 OpenFeign 포크를 검토하라고 적는다. 동작 변화는 없다
(compileOnly 클래스패스에서 쓰지 않는 jar 하나가 빠진다).
검증(desktop, 이 트리 6831ad47):
- 세 빌드를 `--write-locks`로 다시 썼다. persistence-jpa lockfile에서 querydsl-jpa가
7개 구성에서 빠졌고 querydsl-core 5.1.0은 그대로다.
- `:adapter:outbound:persistence-jpa:check :adapter:outbound:persistence-jpa:testQualityCheck
verifyDependencyLocks` rc=0, test 666 실패 0(`PredicatePolicyTest`,
`JpaModuleBoundaryTest` 포함).
- `:adapter:outbound:persistence-jpa:compileJava --rerun` rc=0: 운영 코드가
querydsl-core만으로 컴파일된다.
- 앞 커밋 트리(c5ed4659)를 깨끗한 worktree로 꺼내 돌린 trivy에서 남은
HIGH·CRITICAL은 이 한 건이었다.
문제: `docs/storage-capability-boundary.md`가 영어였다.
고친 것: 번역했다. 주장은 바꾸지 않았다. 예외 목록에서 이 파일의 language 줄을 지웠다.
이 커밋으로 이 작업 범위(runbook·알림·JPA·관측·호환·storage)의 language·number 예외
줄이 0이 된다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
문제: `docs/compatibility`의 두 문서가 영어였고, `grpc-support-matrix.md`는 Spring Boot
버전을 복사했다(number 예외). 지운 `GrpcAdvancedSupportMatrix`·
`GrpcAdvancedPromotionEvidence`와 없는 `runtime_memberships`, `src/build.gradle`의
`ext.grpcVersion`을 가리켰다.
고친 것: 둘을 번역했다. 버전은 `src/gradle/libs.versions.toml`을 가리키고, 등급의 정본은
`GrpcAdvancedCapability.defaultGrade`, 빌드 상태는 registry의 `"build": "optional-grpc"`로
적었다. 예외 목록에서 language 줄 2개와 number 줄 1개를 지웠다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값
`adapter-check`가 있었다.
고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`,
`profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다.
예외 목록에서 이 파일의 language 줄을 지웠다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.
고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
`` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
- support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
`JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
- repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
`src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
`composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
`JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
- experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.
버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.
위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
`JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
`PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.
고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
그대로다.
- 코드에 맞춘 주장:
- configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
(`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
(`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
- at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
`NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
대로 짧은 교체 순서를 더했다.
- module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.
버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.
위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
`NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
`:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
("support-matrix.md has no table that assigns a grade (a '등급' column …)").
문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.
고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
- adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
`failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
곳은 `RoutingNotifier`뿐이다.
- startup-required-adapter-disabled: `startup.phase=adapter-check` →
`adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
- cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
- db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
→ `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
- dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
(`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
- management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
(`config/observability.yml`).
- runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
경로(`src/Dockerfile`)를 적었다.
- auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
- grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
`GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
- grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.
버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.
위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
`-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.
검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.
검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
`:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
`postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
`postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
`:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
`everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
문제: Boot 4.0.9가 고르는 kafka-clients 4.1.2가 압축 라이브러리 두 개의 낡은
버전을 가져온다.
- at.yawk.lz4:lz4-java 1.10.1: HIGH CVE-2026-106451(공유 임시 폴더로 native
라이브러리를 풀어 코드 실행). 1.11.4에서 고쳤다.
- org.xerial.snappy:snappy-java 1.1.10.7: HIGH CVE-2026-93451(손상된 압축
입력으로 버퍼 넘침), CVE-2026-108106(압축 해제 중 메모리 할당 제한 없음).
1.1.10.9에서 고쳤다.
messaging 플랫폼의 kafka leaf 셋, adapter:inbound:messaging,
adapter:outbound:messaging-kafka, app-bootstrap이 가진다.
고친 방법: `pinned-*` 묶음에 `pinned-lz4-java`(1.11.4)와
`pinned-snappy-java`(1.1.10.9)를 더한다. 둘 다 고친 가장 작은 버전이다.
lz4 1.11.4는 1.11.1~1.11.4에서 고친 lz4 MEDIUM·LOW 공지 다섯도 함께 푼다.
- 버린 대안: kafka-clients를 올리기(`kafka.version` override). 4.1 줄에는
고친 패치가 없고, 4.3.2가 lz4 1.11.4·snappy 1.1.10.11을 가져오지만 Boot 4.0의
spring-kafka가 시험한 Kafka 줄을 벗어난다.
위험·한계: kafka-clients 4.1.2는 lz4 1.10.1에 맞춰 빌드됐다. Kafka 4.2.2가
1.11.2를, 4.3.2가 1.11.4를 쓰므로 Kafka가 쓰는 lz4 API는 1.11에서도 같다.
이 저장소는 Kafka 압축을 켜지 않아(설정·테스트에 `compression.type` 없음) 기존
테스트는 두 라이브러리를 부르지 않는다. 그래서 아래 탐침으로 kafka-clients의 압축
경로를 따로 봤다. 압축을 켠 실제 브로커 왕복은 보지 않았다.
검증(desktop, 이 트리 c5ed4659):
- 세 빌드를 `--write-locks`로 다시 썼다. Kafka를 쓰는 lockfile 6개에서
lz4-java 1.10.1→1.11.4, snappy-java 1.1.10.7→1.1.10.9만 바뀌었다.
- `:messaging:messaging-kafka:check :messaging:messaging-spring-boot-starter-kafka:check
:messaging:messaging-spring-boot-starter:check :adapter:inbound:messaging:check
:adapter:outbound:messaging-kafka:check :app-bootstrap:check verifyDependencyLocks`
rc=0. 클래스패스가 바뀐 leaf의 test가 다시 돌았다: messaging-kafka 87,
starter 77, starter-kafka 2, adapter:outbound:messaging-kafka 4, 실패 0.
- `verifyMessagingCertificationEvidence`(messaging-certification workflow의 PR job,
실제 Kafka 컨테이너) rc=0, 인증 lane 37 실패 0.
- 탐침(커밋하지 않음): kafka-clients 4.1.2의 `MemoryRecords.withRecords`로 lz4·snappy
batch를 만들고 다시 읽는 프로그램. 새 jar 쌍과 옛 jar 쌍 모두 rc=0, 두 레코드와
값 10006바이트를 그대로 읽었고 batch 크기도 같다(lz4 145, snappy 581바이트).
문제: 앞 커밋이 레지스트리 주석의 `# source:`를 `# 출처:`로 바꾸고, 출처 줄 안의 기록 절
이름(「In scope」「Decisionized Work Items」「decisions」「Exposure Policy」「AuthN/AuthZ
Decision Matrix」)까지 한국어로 옮겼다. 출처 줄은 기록 이름·날짜·절 이름으로 원문을
찾아가는 줄이라, 옮기면 그 기록에서 같은 이름을 찾을 수 없다. 또 metrics.yaml 주석 세 줄에
변환 실수로 `\"`(백슬래시가 붙은 따옴표)가 들어갔다.
고른 방법: 총괄 기준(2026-11-07)대로 나눈다.
- 원문으로 둔다: 출처 줄의 꼬리표 `source:`, 기록 이름·날짜·절 이름, 따옴표 인용.
- 한국어로 둔다: 같은 줄의 나머지 설명, 행마다의 이유·조건·주의 산문, 값 칸, 파일 머리 블록.
- `\"`는 `"`로 고친다.
위험·한계: 출처가 가리키는 `feature-*` 계약 기록 24개는 저장소 어디에도(이력 포함) 그 이름의
파일이 없다. `docs/design/`에 있는 것은 `five-adapter-runtime-remediation`과
`redis-production-capability` 둘이고, 파일 이름에 날짜와 `-design`이 붙어 있다. 이름은 고치지
않았다.
검증: 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 앞 커밋과 같다(주석만 바뀜).
`python3 scripts/check-docs.py` rc=0.
문제: Checkstyle 13.5.0의 doxia 1.12.0이 plexus-utils 3.3.0을 가져온다. HIGH
CVE-2025-67030(extractFile 경로 조작)이 있고 3.x 줄에서는 3.6.1, 4.x에서는
4.0.3에서 고쳤다. 모든 leaf의 checkstyle 구성에 걸린다.
고친 방법: 앞 커밋의 `pinned-*` 묶음에 `pinned-plexus-utils`(3.6.1)를 더한다.
3.x 안에서 고친 가장 작은 버전이다.
- 버린 대안: 4.0.3. 메이저다. 4.0은 XML 클래스를 plexus-xml로 떼어 냈다.
- 버린 대안: doxia를 뺀 Checkstyle 13.11.0으로 올리기. plexus-utils는
사라지지만 Checkstyle 규칙이 여섯 마이너만큼 바뀐다.
위험·한계: doxia는 Checkstyle의 사이트 문서 생성에만 쓰여 Gradle checkstyle
태스크에서는 plexus-utils를 거의 부르지 않는다. 그래도 모든 leaf의
checkstyle이 이 구성으로 돈다.
검증(desktop, 이 트리 00b8e235):
- 세 빌드를 `--write-locks`로 다시 썼다. lockfile 64개의 checkstyle 구성에서
plexus-utils 3.3.0→3.6.1만 바뀌었다.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 32초,
태스크 752(executed 641, up-to-date 111). checkstyle 태스크 109개가 실제로 돌았다.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0,
checkstyle 태스크 17개 실행.
문제: guava의 HIGH CVE-2026-102554(역직렬화 중 메모리 할당 제한 없음)는
33.7.2에서 고쳤다. 그런데 guava는 어떤 leaf도 직접 선언하지 않고, 낡은 버전이
셋에서 들어온다.
- gRPC 1.75.0: 33.3.1-android(lockfile에는 jre 변형 이름으로도 남는다)
- Error Prone 2.49.0(annotationProcessor 구성): 33.5.0-jre
- Checkstyle 13.5.0(checkstyle 구성): 33.6.0-jre
leaf 거의 전부의 lockfile에 걸린다.
고친 방법: 카탈로그에 `pinned-*` 라이브러리 묶음을 두고, JavaConventionsPlugin이
그 묶음을 Spring dependency management로 모든 leaf에 건다. 첫 항목이
`pinned-guava`(33.7.2-jre)다. 버전 키 주석에 CVE와 낡은 버전을 가져오는 곳을
적고, 그곳들이 고친 버전을 가져오면 지운다.
- dependency management를 쓰는 이유: Boot BOM처럼 모든 구성에 걸린다.
checkstyle·annotationProcessor 구성도 받는다(lockfile에서 checkstyle 구성의
commons-lang3가 BOM override 3.20.0인 것이 이미 그 증거다). Gradle constraint는
구성마다 따로 걸어야 한다.
- 버전을 카탈로그에 두는 이유: 이 빌드가 고르는 버전이다(카탈로그 머리말).
BOM이 관리하는 것을 덮는 override와 다르다.
- build-logic `PlatformModuleConventionTest`에 시험을 하나 더했다. fixture
카탈로그의 `pinned-fixture`는 checkstyle 구성의 관리 버전이 되고,
`unpinned-fixture`는 관리되지 않는다.
- 버린 대안: Error Prone 2.51.0, Checkstyle 14.4.0으로 올리기. 둘 다 guava
33.7.2를 가져오지만 gRPC 쪽은 남고, 새 검사 규칙이 들어와 범위가 커진다.
Checkstyle 14는 메이저다.
위험·한계: dependency management는 하한이 아니라 정확한 고정이다. 나중에
33.7.2보다 새 guava를 요구하는 라이브러리가 들어와도 33.7.2로 내린다. 그때는
그 leaf가 guava를 버전과 함께 직접 선언하면 그 선언이 이긴다. gRPC가 쓰던
android 변형 대신 jre 변형이 들어간다. jre 변형은 android 변형의 API를 모두
가진다. guava 33.7.2가 요구하는 대로 error_prone_annotations 2.50.0,
failureaccess 1.0.3, j2objc-annotations 3.1, jspecify 1.0.1이 같이 들어오고
checker-qual은 빠진다.
같은 커밋의 작은 정리: 앞 커밋이 넣은 httpcore5 주석의 줄바꿈을 고쳤다.
검증(desktop, 트리 49191720 위에 시험·주석 정리를 얹은 9a97dbbb):
- 세 빌드를 `--write-locks`로 다시 썼다. lockfile 64개에서 guava가 33.7.2-jre
하나가 됐다(checkstyle·annotationProcessor 구성 포함). 위 동반 라이브러리 외에
바뀐 것은 없고, 새로 생기거나 사라진 구성 0.
- RED: 장치 없는 트리(앞 커밋)에 새 시험만 얹으면 실패한다
("pinned=null unpinned=null").
- GREEN: `./gradlew -p build-logic check javadoc` rc=0, 테스트 174 실패 0.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 33초,
태스크 752(executed 641, up-to-date 111, from cache 0). 모든 leaf가 새 guava로
Error Prone·Checkstyle을 돌렸다.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0, 1분 11초.
문제: `docs/notification/adr/`의 NOTIF-ADR-001~004는 머리 블록만
한국어이고 본문이 영어다. NOTIF-ADR-005는 한국어지만 상태 값과 절
제목 하나, 인용문이 영어로 남아 있다.
방법: 결정의 뜻을 바꾸지 않고 제자리에서 옮긴다(폴더 옮기기는 통합
단계의 몫이다). 머리 블록은 바꾸지 않는다. 식별자·타입 이름·상태 값
같은 코드 표기는 원문으로 두고, NOTIF-ADR-005가 인용한 영어 원문에는
뜻을 괄호로 붙인다. 파일 이름이 그대로라 NotificationReleaseGateTest가
보는 존재 단언은 영향이 없다.
위험: 없음. 본문 뜻은 바꾸지 않았다.
검증: python3 scripts/check-docs.py rc=0(language 줄 4개 지움, head
실패 0), 머리 블록이 HEAD와 같은지 5개 모두 diff로 대조.
문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이
영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로
정했다(design-docs `repo-structure/README.md` 3.2절).
방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약·
현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위
줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드·
명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한
영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을
괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본
지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은
`scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에
남긴다.
위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤
문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다.
검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움,
head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조,
check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
문제: docs/websocket/runbook.md가 영어였다(language 예외).
고친 방법: 뜻을 그대로 옮기고 식별자·명령·close code·nginx 지시어·표 구조는 원문으로
둔다. 적힌 클래스·lane(`TomcatWebSocketShutdownIT`, `websocketNginxTest`,
`websocketJettyTest`, `nginx-no-upgrade.conf` 등)은 모두 지금 있다.
위험·한계: 내용 감사는 하지 않았다.
검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/websocket을 읽는 테스트는
없다(`grep -rn 'docs/websocket' src --include=*.java` 결과 0).