Files
clean-architecture-backend-…/src/bootstrap/app/AGENTS.md
T
DongHyeonka f4d832dfaf
pr / done (pull_request) Canceled after 0s
fix(arch): 아키텍처 규칙이 놓친 HARD-STOP 2 사각지대 다섯을 닫는다
문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
   dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
   걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
   gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
   @SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
   거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
   AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
   AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
   쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
   registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
   (설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
   MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
   주석과 다름).

고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
   ..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
   않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
   USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
   유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
   oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
   AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
   설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).

위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.

검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
  변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
  모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
  spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
  :app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
  :verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
  ~/r9-be-logs/b14-{red,green2}.log.

Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05
2026-11-13 00:28:00 +09:00

9.3 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. controller는 CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS가 빌드에서 막는다.
  • 업무 로직을 구현하는 설정 클래스.
  • 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