Files
clean-architecture-backend-…/src/app-bootstrap/CLAUDE.md
T
DongHyeonka c91cc3fb10 docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap,
composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다.
세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를
모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을
4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로
둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다.
다른 문서·코드가 제목으로 가리키는 절(application-core의
Naming convention·Package ownership·Canonical use case shape·Allowed
transactional shapes, shared-contract의 Responsibility·Forbidden,
messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가
계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다.
코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을
`adapter-persistence`에서 `adapter:outbound:persistence-jpa`의
`SpringTransaction`으로, registry README의 빈 의존 목록 예를
persistence-mongo(실제 목록은 application-core·shared-contract)에서
domain-core·shared-contract·messaging-core-api로 고친다.
TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로
머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을
대조하는 계약은 그대로다.

위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로
바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01,
11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다.

검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개,
number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위)
깨진 링크 0, unittest discover scripts/tests 43개 통과.
2026-11-07 17:07:16 +09:00

8.9 KiB

app-bootstrap — 애플리케이션 진입점과 조립 루트

등록 정보

  • 모듈 ID: app-bootstrap
  • Gradle 경로: :app-bootstrap
  • 이 모듈만 시험(Gradle 경로에서 나온 명령): ./gradlew :app-bootstrap:test --console=plain
  • 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 src/gradle/libs.versions.toml이 정한다.
  • registry 정본: src/config/architecture/modules.json.

패키지 루트: dev.caskeleton.bootstrap.

책임

  • Spring Boot 진입점(CaSkeletonApplication).
  • 런타임 설정과 로깅 시작.
  • 모듈을 가로지르는 마지막 배선.
  • 모든 모듈을 들여다보는 아키텍처 시험.

허용

  • 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
  • Spring Boot 시작·런타임 의존성.
  • 시험에서 ArchUnit.

금지

  • 구체적인 업무 정책.
  • bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
  • 업무 로직을 구현하는 설정 클래스.
  • application-core나 domain-core 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 설정했든 outbound 어댑터이고 adapter/outbound/* leaf에 둔다 — CompositionRootBoundaryArchitectureTest가 예외 없이 강제한다.
  • 기동 실패를 throw new IllegalStateException(...)으로 내기. StartupFailures (adapter:outbound:support, 패키지 support.startup: envValidation / profileMismatch / requiredAdapterDisabled / migrationFailed)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 필드를 싣게 한다 — StartupFailureContractArchitectureTest가 강제한다.
  • 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 dev.caskeleton.shared.runtime.RuntimeEnvironment가 가진다.
  • src/test에서 org.testcontainers에 의존하기. 실제 서비스를 쓰는 시험은 src/integrationTest에 둔다. docs/testing/TESTING_STRATEGY.md를 본다.

패키지 배치

아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 (docs/reviews/2026-09-07-app-bootstrap-module-code-review.md). capability의 절반은 autoconfigure/ 아래, 절반은 패키지 루트에 있었다. Settings 클래스는 규칙 없이 settings/ 패키지와 각 기능 패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 설정 아홉 개로, Redis는 376줄 클래스 하나로.

  • capability의 조립은 그 capability 자신의 모듈에 있다. 그 모듈의 AutoConfiguration.imports가 등록하고, 설정은 그 모듈의 config/module-defaults/*.yml에 둔다. JPA(기동 guard, Flyway 전략, lock decorator, readiness, JpaActivationEnvironmentPostProcessor의 완전히 끄기 처리)는 adapter:outbound:persistence-jpa, Redis(readiness)는 adapter:outbound:cache-redis, 알림은 composition:notification-platform이다. 모든 capability는 build.gradle에서 주석 처리한 runtimeOnly 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. component scan은 dev.caskeleton.bootstrap만 본다. web(WebAdapterAutoConfiguration, WebSecurityAutoConfiguration, WebMethodSecurityAutoConfiguration)과 support (OutboundSupportConfig)는 자기 AutoConfiguration.imports로 들어온다. autoconfigure/<name>/에 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 common(시계)뿐이다. outbox relay, 멱등성 executor, durable operation(유스케이스와 /operations endpoint, 07-08)은 composition:outbox-relay, composition:idempotency, composition:durable-operation이다. 각각 runtimeOnly 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 role → permission 대응은 config/security.yml이 아니라 그 capability의 config/module-defaults 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context 전파, 사용자 principal 가명화(PrivacySettings), actuator chain — 은 composition:service-runtime이다.
  • <Capability>Settings는 settings/가 아니라 그 capability 옆에 둔다. settings/ 패키지는 어느 capability에도 속하지 않는 설정 — BootstrapSettings, RuntimeSafetySettings — 만 담는다. 이 설정은 StrictSettingsBinder로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 없다. logback-spring.xml이 app.logging.*을 직접 읽고 LoggingConfigurationRule이 Logback이 쓸 수 없는 값을 거절한다.
  • runtime/은 애플리케이션 자체에 대한 guard를 담는다 — 비밀 값, 숫자 한계, 오류 상세 노출, 여러 인스턴스 조율, runtime profile 검사(RuntimeEnvironmentProfileValidator). capability 설정에 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.
  • 기동 실패 어휘는 adapter:outbound:support에 있다(support.startup: phase, 오류 코드, 예외, StartupFailures, StartupValidationContext, StartupOrder, ReadinessGroup, RuntimeWarnings). 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. runtime/startup/에는 StartupFailureExceptionReporter만 남는다.
  • 환경만 보는 guard는 StartupRule bean이다(support.startup). 위반을 돌려주고, 유일한 StartupRuleRunner가 다른 singleton이 생기기 전에 그것을 올린다(Environment, bean factory, 정적 RequiredProductionSecrets의 ObjectProvider만 받는 static @Bean 메서드로 선언한다. 모든 profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 RequiredProductionSecrets마다 하나씩 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 @Value/@Autowired/@Inject/@Resource 멤버, @PostConstruct/@PreDestroy 콜백, @ConfigurationProperties 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 비밀 값은 그 capability의 것이다: 그 모듈이 RequiredProductionSecrets bean을 내놓고, SecretSourceValidator는 어떤 role이 있는지 모르는 채로 이름을 검사한다.

분해 기준

취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.

  • @Configuration 하나는 조립 관심사 하나를 담는다. 대략 @Bean 메서드 여덟 개를 넘거나, 서로 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.
  • @ConfigurationProperties 클래스 하나는 capability namespace 하나를 가진다.
  • 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 enabled 조건, @EnableConfigurationProperties, 관심사별 클래스의 @Import를 가진다. 아무것도 scan하지 않는다: 조건이 걸린 루트에서 @Import해야 enabled=false가 권고가 아니라 실제로 끄는 스위치가 된다. cache-redis의 capability/RedisCapabilityConfig가 참조 예다. 다시 쓸 Spring 조립을 가진 optional 어댑터 capability는 자기 루트를 내놓는다. 알림은 adapter:outbound:notification의 NotificationPlatformAutoConfiguration과 composition:notification-platform의 NotificationApplicationCompositionAutoConfiguration을 쓴다. JPA는 adapter:outbound:persistence-jpa의 package-private PersistenceJpaAutoConfiguration, PersistenceJpaRuntimeConfig, startup.JpaStartupAutoConfiguration을 쓰고, 이 모듈은 기본 조립에 없다(build.gradle의 // runtimeOnly project(':adapter:outbound:persistence-jpa')). Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다.
  • 나눈 capability의 공용 도우미는 *Util 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — cache-redis의 capability/RedisKeys가 참조 예다.

테스트

cd src
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies