문제: 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.
7.5 KiB
7.5 KiB
CLAUDE.md — 이 repo의 지도
이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.
1. 이 repo
- Java 21 + Spring Boot 4.0.8 Gradle 멀티모듈 Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
- Gradle 루트는
src/다. Gradle 명령은src/에서 실행한다. - 규칙의 정본은
AGENTS.md다. leaf 목록·경로·허용 의존의 정본은src/config/architecture/modules.json(registry)이다. 각 leaf의 지역 규칙은 가장 가까운src/**/CLAUDE.md가 정한다.
2. HARD-STOP — 하나라도 어기면 완료가 아니다
정본은 AGENTS.md 「Prime Directive」다. 두 문서가 다르면 AGENTS.md가 맞다.
domain-core가 framework·transport·database·cloud 의존성을 가진다.- controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
- inbound DTO가
application-core나domain-core로 들어간다. - 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
- 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
- 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
- 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
3. 맡은 일 → 읽을 문서
먼저 docs/work/README.md를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.
| 맡은 일 | playbook |
|---|---|
| 새 업무 기능, 새 capability 모듈 | docs/work/new-feature.md → docs/manual/ |
| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | docs/work/improve.md |
| 바꾸기 전에 대안 비교와 소유자 결정 | docs/work/research-design.md |
| 매뉴얼·안내 문서 쓰기 | docs/work/docs-writing.md |
| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | docs/work/operate.md |
| 큰 일을 나눠 다른 세션에 맡기기 | docs/work/delegate.md |
brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.
4. 검증 명령과 실행 위치
- 실행 위치: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 docs/work/operate.md 4.1절이다.
- leaf 하나: registry에서 그 leaf의
gradle_path를 읽고./gradlew <gradle-path>:test --console=plain또는:check를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다. - 저장소 전체 질문:
./gradlew architectureCheck --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
./gradlew verifyPublicPathSnapshot --console=plain
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체
test·check·ci는 brief가 시킬 때 돌린다. - 게이트 목록(
ci,mainCheck,integrationCheck,performanceCheck,releaseCheck등)과 바꾼 것에 맞는 게이트는 docs/work/reference/gates.md다. docs/work/, 이 파일,AGENTS.md,src/**/CLAUDE.md를 고쳤으면python3 scripts/check-work-docs.py를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
5. 코드만 보고는 헷갈리는 곳
- 최상위 폴더는 정해진 것만 둔다. 저장소 루트는
compose.yaml(개발 환경)·compose/(그 보조 파일)·docs/·scripts/·src/(Gradle 루트)다.src/아래는 계층 leaf 폴더,composition/(조립),platforms/(들여온 제품:messaging·grpc·grpc-advanced와 optional 빌드optional-build), Gradle 루트 표준(build-logic·gradle·config)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. - leaf 목록은 registry 하나다. 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의
allowed_dependencies가 정하고, 방향 게이트가 그 밖의 edge를 막는다. src/platforms/messaging/*는 Clean Architecture 계층이 아니다. 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다.domain-core·application-core·shared-contract에 의존하지 않는다. 이 애플리케이션은adapter:outbound:messaging의 bridge로만 닿는다. 이유와 지역 규칙은src/platforms/messaging/CLAUDE.md다.composition:*leaf는 조립만 한다. outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각runtimeOnly한 줄로 고른다.- capability는 한 줄로 켜고 끈다. 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도
src/app-bootstrap/build.gradle의runtimeOnly한 줄로 켠다. 규칙은AGENTS.md「부가 기능(capability) 모듈 규칙」이다. - gRPC 플랫폼 라이브러리는 다른 빌드다.
src/platforms/grpc/*·src/platforms/grpc-advanced/*(registry의"build": "optional-grpc")는-p platforms/optional-build로 돈다.adapter:inbound:grpc는 애플리케이션 adapter라 주 빌드에 있다. - 새 기능의 예시는
scripts/new-feature.sh의 출력이다. 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는docs/manual/이 실제 코드(fileserver, durable operation)를 가리킨다. - 성능 lane에는 단언을 끄는 스위치가 없다. convention이 상한을 매번 단언하고,
performance.assertions.enabled에true아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(AGENTS.md「Gradle 정책 권위」). - 저장소 파일을 읽는 테스트는 태그가 있다. 문서와 대조하는 테스트는
document-contract(main 단계mainCheck), 빌드 스크립트·workflow를 읽는 테스트는repository-contract(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다. - 커밋 정책은
human-only다. brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 docs/work/README.md 4절이다. - 문서 위치 규칙은 docs/README.md다. 설계서는
docs/superpowers/specs/, 결정 기록은docs/adr/, 리뷰는docs/reviews/, 파생 서비스용 변경 안내는docs/upgrade/다.
6. 소유자 환경
- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: docs/work/operate.md 4.1절(실행 위치)과 docs/work/delegate.md 4.3절(세션). 공용 정본은 design-docs
conventions/delegation-loop.md11절이다. - Agent 도구(세션 안의 하위 에이전트)는 이 repo의
.claude/settings.json이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다. - 작업 사고 순서의 정본은 design-docs
conventions/work-thinking-order.md, 커밋·PR 형식은conventions/commit-and-pr.md다. - 보고 말투와 형식은 소유자의 전역
~/.claude/CLAUDE.md를 따른다.