Files
clean-architecture-backend-…/docs/improvement/03-folder-module-structure.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.

방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).

위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.

검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
2026-11-05 21:59:44 +09:00

160 lines
11 KiB
Markdown

# 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-<capability>/ 선택 기능의 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 안 `<feature>` 패키지, 켜고 끄는 플랫폼 기능만 `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/<YYYY-MM-DD>-<종류>/`, 설계서는
`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` 표 하나, 마이그레이션은 스트림마다, 적용된 파일은 고치지 않는다.