문제: 앞 커밋이 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
9.2 KiB
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(유스케이스와/operationsendpoint. 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는
StartupRulebean이다(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의 것이다: 그 모듈이RequiredProductionSecretsbean을 내놓고,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-privatePersistenceJpaAutoConfiguration,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