Files
clean-architecture-backend-…/src/bootstrap/app/AGENTS.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

9.2 KiB

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

등록 정보

  • 모듈 ID: app-bootstrap
  • Gradle 경로: :app-bootstrap
  • 이 모듈만 시험(Gradle 경로에서 나온 명령): ./gradlew :app-bootstrap:test --console=plain
  • 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 gradle/libs.versions.toml이 정한다.
  • registry 정본: gradle/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. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 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가 참조 예다.

테스트

  • settings 패키지: 설정 바인딩, 값 검증, 로깅 설정을 검증한다. 새 settings 클래스에는 바인딩·검증 테스트를 더한다.
  • 설정·런타임·Docker 규칙은 .claude/rules/settings-and-runtime.md다.
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies