Files
clean-architecture-backend-…/src/app-bootstrap/CLAUDE.md
T
DongHyeonka 6b253c6c75 docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.

고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.

위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).

검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
  'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
  rc=0(3건)
2026-11-07 07:02:09 +09:00

8.4 KiB

app-bootstrap — application entry point & composition root

Registered identity

  • Module ID: app-bootstrap
  • Gradle path: :app-bootstrap
  • Focused test (derived from Gradle path): ./gradlew :app-bootstrap:test --console=plain
  • Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
  • Registry SSOT: src/config/architecture/modules.json.

Package root: dev.caskeleton.bootstrap.

Responsibility

  • Spring Boot entrypoint (CaSkeletonApplication).
  • Runtime settings and logging bootstrap.
  • Final cross-module wiring.
  • Architecture tests that inspect all modules.

Allowed

  • Runtime leaves explicitly declared by this module's Gradle dependencies and permitted by the architecture registry. The resolved Gradle runtime graph is the runtime SSOT; do not duplicate a membership list in metadata.
  • Spring Boot startup/runtime dependencies.
  • ArchUnit in tests.

Forbidden

  • Concrete business policy.
  • Controllers, use cases, repository adapters, or mappers authored directly under bootstrap.
  • Settings classes that implement business logic.
  • Implementing an application-core or domain-core port. A class that implements one is an outbound adapter and belongs in an adapter/outbound/* leaf, however its dependencies are configured — CompositionRootBoundaryArchitectureTest enforces this, with no exceptions.
  • Raising a startup failure with throw new IllegalStateException(...). Use StartupFailures (adapter:outbound:support, package support.startup: envValidation / profileMismatch / requiredAdapterDisabled / migrationFailed), so the failure carries its sysexits exit code and structured log fields — StartupFailureContractArchitectureTest enforces this.
  • Answering "is this production?" locally. dev.caskeleton.shared.runtime.RuntimeEnvironment owns the profile vocabulary for the whole repository.
  • Depending on org.testcontainers from src/test. Real-service tests belong to src/integrationTest; see docs/testing/TESTING_STRATEGY.md.

Package layout

The rules below exist because their absence is what produced the drift this module was reviewed for (docs/reviews/2026-09-07-app-bootstrap-module-code-review.md). Half the capabilities lived under autoconfigure/ and half at the package root; Settings classes were split between a settings/ package and their feature packages with no stated rule; and the same decomposition problem was solved two different ways in the same leaf — Notification as nine focused configurations, Redis as one 376-line class.

  • A capability's assembly lives in the capability's own module, registered by that module's AutoConfiguration.imports, with its settings in the module's config/module-defaults/*.yml. JPA (startup guards, Flyway strategy, lock decorator, readiness and full-off handling in JpaActivationEnvironmentPostProcessor) is adapter:outbound:persistence-jpa; Redis (readiness) is adapter:outbound:cache-redis; notification is composition:notification-platform. Every capability is a commented runtimeOnly line in build.gradle; the default composition is web, observability, the cores, support and identifier. This leaf keeps no list of capabilities: no switch registry, no cross-capability dependency validator, no activation endpoint. Component scan covers dev.caskeleton.bootstrap only; web (WebAdapterAutoConfiguration, WebSecurityAutoConfiguration, WebMethodSecurityAutoConfiguration) and support (OutboundSupportConfig) arrive through their own AutoConfiguration.imports. What stays in autoconfigure/<name>/ is application composition every application needs: common (the clock). The outbox relay, the idempotency executor and the durable operations (use cases and /operations endpoints, 07-08) are composition:outbox-relay, composition:idempotency and composition:durable-operation, selected by one runtimeOnly line each and building nothing until their ports exist (the sample takes the idempotency one too). A capability's role→permission mapping ships in its own config/module-defaults file, not in config/security.yml. The runtime wiring both composition roots need — tracing, the metrics contract filters, domain-context propagation, user-principal pseudonymization (PrivacySettings) and the actuator chain — is composition:service-runtime, which the sample takes by the same line instead of carrying copies.
  • <Capability>Settings lives beside its capability, not in settings/. The settings/ package holds only settings that belong to no capability — BootstrapSettings, RuntimeSafetySettings — bound strictly with StrictSettingsBinder, never scanned. Logging has no settings record: logback-spring.xml reads app.logging.* itself and LoggingConfigurationRule refuses values Logback cannot use.
  • runtime/ holds guards about the application itself — secrets, numeric bounds, error-detail exposure, multi-instance coordination, the runtime-profile check (RuntimeEnvironmentProfileValidator). A guard about a capability's settings (the JPA OSIV/DDL/pool/TLS/vendor guards, the Mongo connection-source rule, the GraphQL deployment-mode rule) ships with that capability's module, so it exists exactly when the capability does.
  • The startup failure vocabulary lives in adapter:outbound:support (support.startup: phases, error codes, exceptions, StartupFailures, StartupValidationContext, StartupOrder, ReadinessGroup, RuntimeWarnings), so capability modules fail the same way without depending on this leaf. runtime/startup/ keeps only StartupFailureExceptionReporter.
  • An environment-only guard is a StartupRule bean (support.startup): it returns violations, and the one StartupRuleRunner raises them before any other singleton exists (declare it with a static @Bean method that takes only the Environment, the bean factory or an ObjectProvider of static RequiredProductionSecrets; in every profile the runner creates each rule and each RequiredProductionSecrets before any rule runs, and fails the boot naming any other bean one of them creates, and naming any whose runtime class has an @Value/@Autowired/ @Inject/@Resource member, a @PostConstruct/@PreDestroy callback or a @ConfigurationProperties binding — those are created before the post-processors and would stay unset). A guard that needs another bean stays a bean. A capability's production secrets are the capability's: its module contributes a RequiredProductionSecrets bean, and SecretSourceValidator checks the names without knowing which roles exist.

Decomposition threshold

State it rather than leaving it to taste, because "it felt long enough" is what produced two different answers for the same question.

  • One @Configuration holds one assembly concern. Split when it passes roughly eight @Bean methods, or as soon as it assembles two unrelated port families — whichever comes first.
  • One @ConfigurationProperties class owns one capability namespace.
  • A capability that needs more than one configuration gets a root class holding its enabled condition, @EnableConfigurationProperties, and an @Import of the per-concern classes. Scan nothing: @Import from a gated root is what keeps enabled=false load-bearing rather than advisory. cache-redis's capability/RedisCapabilityConfig is the reference example. Optional adapter capabilities that own reusable Spring composition publish their own root instead. Notification uses adapter:outbound:notification's NotificationPlatformAutoConfiguration plus composition:notification-platform's NotificationApplicationCompositionAutoConfiguration; JPA uses the package-private PersistenceJpaAutoConfiguration, PersistenceJpaRuntimeConfig and startup.JpaStartupAutoConfiguration from adapter:outbound:persistence-jpa, which is not in the default composition (// runtimeOnly project(':adapter:outbound:persistence-jpa') in build.gradle). Mongo follows the same rule: the persistence-mongo leaf owns MongoRootAutoConfiguration and its internal health bridge; bootstrap owns no Mongo-specific production health configuration.
  • Shared helpers of a split capability get their own type named for what they are, not a *Util bucket — cache-redis's capability/RedisKeys is the reference.

Test

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