문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-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` 한 줄이다.
문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language
예외), 몇 가지 주장이 지금 코드와 달랐다.
- repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨
적었다(number 예외 두 줄).
- 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh·
verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도
있고 lane을 돌린다.
- testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와
`mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다.
- ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은
없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`·
`noProductionPackageDependsOnTheTestkit`이다.
- support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이
lockfile과 달랐다(예: driver 5.6.1 → 5.6.5).
- consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다
(reference 예외).
- document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5).
고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과
leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile,
container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른
단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다.
버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시
틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다.
위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는
그대로 두었다.
검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0).
docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java`
— package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는
advanced 문서의 파일 존재만 본다.
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.
방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.
위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).
검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.