# 03. 폴더·모듈 구조 기준 ## 핵심 이 repo의 모듈 구조는 **디렉터리가 아니라 registry가 정한다.** `src/config/architecture/modules.json`이 leaf의 ID· 소스 경로·Gradle path·허용 의존을 가진 유일한 목록이고, settings와 의존 방향 게이트가 그 파일을 읽는다 (`AGENTS.md` 「Gradle 정책 권위」). 폴더 구조를 바꾸는 일은 곧 registry를 바꾸는 일이다. ```text src/config/architecture/modules.json leaf 목록과 허용 edge (정본) ├─> src/settings.gradle ca.architecture-registry가 읽어 project include·디렉터리 매핑 ├─> verifyCleanArchitectureDependencies 허용되지 않은 edge를 막는다 (architectureCheck) └─> leaf build.gradle ca.java-library / ca.spring-library / ca.platform-module 중 하나 ``` 이 장은 구조를 평가하거나 바꿀 때의 기준이다. 새 기능을 **어디에 둘지**는 `docs/manual/03-placement.md`가 정한다. ## 1. 구조 지도 leaf 개수는 적지 않는다. 문서에 적은 수는 leaf가 추가되는 순간 틀린다(`AGENTS.md` 「Gradle 정책 권위」). ```text src/ Gradle 루트 (명령은 여기서 실행) domain-core/ 순수 도메인 application-core/ 유스케이스·포트 application-/ 선택 기능의 application (notification, fileserver, objectstorage) shared-contract/ skeleton 전체의 운영 계약 adapter/inbound/*/ 전송 경계 (web, graphql, grpc, websocket, messaging …) adapter/outbound/*/ 저장소·외부 능력 (persistence-*, cache-redis, httpclient …) composition/*/ 조립 전용 leaf (bootstrap에서 떼어 낸 조립) messaging/*/ vendored 메시징 제품 — 계층이 아니다 grpc/*/, grpc-advanced/*/ optional-platforms 빌드 (`-p optional-platforms`) sample-portfolio/ 지울 수 있는 샘플 app-bootstrap/ Spring Boot 진입점·조립 루트 build-logic/ convention plugin (included build) config/ architecture registry, spotbugs 제외, testing 이미지 목록 … optional-platforms/ gRPC 플랫폼용 별도 빌드 루트 docs/ scripts/ infra/ .github/workflows/ ``` | 묶음 | 책임의 정본 | | --- | --- | | family별 책임 | `AGENTS.md` 「모듈 책임」, `CLAUDE.md` 「Module families」 | | leaf별 규칙 | 가장 가까운 `src/**/CLAUDE.md` | | leaf별 Gradle path·허용 의존 | `src/config/architecture/modules.json` | | vendored family의 예외 | `CLAUDE.md` 「Module families」 마지막 문단, `src/messaging/CLAUDE.md` | ## 2. 기준 각 기준은 "규칙 → 왜 → 지키는 장치 → 지난 결함" 순서다. ### 2.1 leaf는 registry 한 곳에서 생기고 사라진다 - **규칙**: leaf를 더하거나 지우는 일은 `modules.json`에서 시작한다. registry에 없는 디렉터리에 build 스크립트가 있으면 빌드가 실패해야 한다. - **왜**: registry에 없는 leaf 디렉터리가 조용히 빌드에서 빠진 적이 있다(`1101/08-05`). - **장치**: `ModuleRegistry.unregisteredBuildScripts`(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java`)가 잡는다. git이 무시하는 IDE 출력 `bin/`은 건너뛴다(`1101` README 14.2절). ### 2.2 문서는 leaf 목록과 개수를 복제하지 않는다 - **규칙**: root 문서와 매뉴얼은 family만 말하고 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf의 명령은 registry의 `gradle_path`에서 만든다. - **왜**: 복제한 목록은 drift한다. 개수를 대조하던 파서(`verifyDocumentedLeafCount`)는 지웠다 — 문서에 틀린 수가 있으면 결함이지만 빌드 실패 사유는 아니다(`AGENTS.md` 「Gradle 정책 권위」). - **장치**: 없다(의도). 리뷰가 본다. ### 2.3 새 기능은 기본적으로 계층 leaf 안의 패키지다 - **규칙**: 업무 기능은 계층 leaf 안 `` 패키지, 켜고 끄는 플랫폼 기능만 `application-*` leaf. 고르는 기준표는 `docs/manual/03-placement.md`가 정본이다. - **왜**: 모양이 세 갈래이고 고르는 기준이 없던 것이 결함이었다(`1101/01-01`, `1101/07-09`). - **장치**: `scripts/new-feature.sh`가 기본 모양만 만들고, `verifyFeatureScaffold`(`mainCheck`)가 왕복을 검사한다. ### 2.4 템플릿 패키지와 기능 패키지를 섞지 않는다 - **규칙**: 템플릿이 소유한 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표가 정본이다. 기능은 그 이름을 쓰지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다. - **왜**: 이름이 겹치면 upstream 템플릿 업데이트가 파생 서비스의 기능 패키지에 섞여 들어간다(`1101/01-10`). - **장치**: ArchUnit 2개(템플릿 이름 재사용 금지, 템플릿→기능 import 금지), 표와 `TemplatePackageOwnership`을 대조하는 `TemplatePackageOwnershipDocumentTest`(`1103` README 16절 r9-a). `new-feature.sh`가 이미 있는 패키지 이름을 거절한다 (`1101` README 16절 r3-g). - **한계**: 표에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(`1103` README 16절 r9-a "한계로 문서화"). 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. ### 2.5 조립은 그 능력의 모듈이 한다 - **규칙**: capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. 여러 leaf에 걸친 조립은 `composition:*` leaf가 한다. - **왜**: 한 줄을 지웠을 때 기능이 완전히 사라져야 한다(capability 기준 7). 기본 조립 루트가 선택 capability를 알던 것이 결함이었다(`1101/07-08`, `1101/05-19`). - **정본**: `AGENTS.md` capability 기준 2·7, 결정 3(outbox relay·멱등성 executor 조립은 `composition:*`). ### 2.6 vendored family는 앱 계층에 기대지 않는다 - **규칙**: `messaging:*`(그리고 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 앱은 `adapter:outbound:messaging`의 anti-corruption bridge로만 닿는다. - **왜**: 다른 제품이라 앱 계층에 의존하면 경계가 무너진다(`CLAUDE.md` 「Module families」, messaging 리뷰 MSG-023). - **결과**: 공용 헬퍼를 쓸 수 없어 복사본이 남는다. 복사본은 이유를 family `CLAUDE.md`에 적는다(`1101` README 15절 01-11, `src/messaging/CLAUDE.md` 「공용 다이제스트 헬퍼를 복사해 두는 이유」). 값이 같아야 하는 복사본은 대조 테스트를 붙인다 (`1103` README 17절 r10-03 Flyway 정책 사본). ### 2.7 source set은 실행 조건이 다를 때만 나눈다 - **규칙**: 별도 source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 만든다. 공유 테스트 코드는 `src/testFixtures/java`(`java-test-fixtures`)에 둔다. - **정본**: `docs/testing/TESTING_STRATEGY.md` 4·5절, `docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`. - **왜**: 같은 일을 하는 두 관례(`ca.testkit-publisher`와 `java-test-fixtures`)가 있던 것이 결함이었다(ADR-BUILD-001 「Context」). ### 2.8 마이그레이션은 스트림마다 따로, 적용된 파일은 고치지 않는다 - **규칙**: 저장소마다 자기 마이그레이션 디렉터리와 history table을 가진다(예: `.../db/migration/jpa/core`, `.../jpa/notification-platform`, `src/sample-portfolio/src/main/resources/db/sample-migration`). 번호는 스트림 안의 순번이고, 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 겹치지 않는 번호를 쓴다(`V8_1`). 어딘가에 적용된 마이그레이션은 고치지 않는다. - **정본**: `docs/manual/04-persistence.md`, `docs/jpa/migration-guide.md`. - **장치**: `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`(적용된 파일의 해시 고정), 잠금 대기 검사기의 동결 목록(`1103` README 10절 r5-c, 12절 r6-b). - **예외의 근거**: 아직 어디에도 적용되지 않은 마이그레이션만 직접 고쳤다. 고칠 때는 main과 파생 서비스에 그 파일이 없음을 확인했다(`1103` README 6절 r4-c "V21 직접 수정", 11절 "고친 마이그레이션 9개가 main `01a8a2a70`과 파생 서비스에 없음"). ### 2.9 문서는 정해진 디렉터리에 둔다 - **규칙**: 문서 위치 규칙은 `docs/README.md`가 정본이다. 리뷰 결과는 `docs/reviews/-<종류>/`, 설계서는 `docs/superpowers/specs/`, 계획서는 `docs/superpowers/plans/`, 결정 기록(ADR)은 `docs/adr/`, 파생 서비스용 변경 안내는 `docs/upgrade/`. - **왜**: 계획서를 사후에 고치지 않는다. 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다 (`docs/README.md` 「설계와 계획」). ## 3. 구조 변경 체크리스트 leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾸는 것이다. 근거는 `docs/manual/03-placement.md` 기준표의 "고칠 공용 파일" 칸과 이 장 2절이다. - [ ] `src/config/architecture/modules.json`: ID·`source_path`·`gradle_path`·`allowed_dependencies` - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄, 자기 `AutoConfiguration.imports` - [ ] leaf `CLAUDE.md`(가까운 안내 — 없으면 `1101/04-16` 같은 결함), capability면 README 세 가지(capability 기준 6) - [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/CLAUDE.md` 「Package ownership」 표 - [ ] ArchUnit 규칙과 그 위반·허용 fixture(05장 5절) - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) - [ ] 파생 서비스에 영향이 있으면 업그레이드 안내 행(`docs/upgrade/2026-11-maturity-review.md` 형식) 검증은 07장 2절 "leaf 경계·의존·registry" 행이다. ## 4. 구조 변경에서 하지 않는 것 - 요청 범위 밖의 대규모 리팩터링(`AGENTS.md` 「금지된 지름길」). 한 계층 안의 일은 그 leaf와 그 테스트 안에서 끝낸다. 범위를 넘어야 하면 멈추고 범위를 다시 받는다(`CLAUDE.md` 「Layer workflow」). - 전 leaf의 import를 바꾸는 이동을 다른 수정 묶음과 동시에. 그런 묶음은 나머지를 합친 뒤 단독으로 마지막에 한다 (`1101` README 15.1절 r3-G). ## 지금 이해하면 되는 것 - 구조의 정본은 registry다. 폴더를 바꾸면 registry·build·문서를 같은 변경에서 바꾼다. - 문서는 leaf 목록과 개수를 적지 않는다. - 템플릿 패키지 목록은 `application-core/CLAUDE.md` 표 하나, 마이그레이션은 스트림마다, 적용된 파일은 고치지 않는다.