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

11 KiB

03. 폴더·모듈 구조 기준

핵심

이 repo의 모듈 구조는 디렉터리가 아니라 registry가 정한다. src/config/architecture/modules.json이 leaf의 ID· 소스 경로·Gradle path·허용 의존을 가진 유일한 목록이고, settings와 의존 방향 게이트가 그 파일을 읽는다 (AGENTS.md 「Gradle 정책 권위」). 폴더 구조를 바꾸는 일은 곧 registry를 바꾸는 일이다.

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 정책 권위」).

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 표 하나, 마이그레이션은 스트림마다, 적용된 파일은 고치지 않는다.