Files
clean-architecture-backend-…/docs/design/2026-09-25-capability-module-packaging-design.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

12 KiB
Raw Blame History

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-09-25
  • 요약: 부가 기능을 붙이면 켜지고 떼면 사라지는 capability 모듈로 바꾸고 기본 조립을 web으로 줄인 설계다.
  • 현재 정본: docs/capability-status.md

부가 기능(capability) 제공 방식과 리뷰 후속 정리 — 설계 초안

  • 상태: 확정 (2026-09-25 소유자 결정 2건 반영 — 10절). 실행 계획: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
  • 작성: 2026-09-25
  • 입력:
    • docs/reviews/2026-09-24-src-module-code-review.md (1차, 결함 중심 — Critical 15 / Required 76)
    • docs/reviews/2026-09-24-src-maintainability-review.md (2차, 구조·SRP·공통 계약·테스트·빌드 비례성)
  • 목표: 템플릿에서 새 프로젝트를 만들 때 도메인과 비즈니스 로직을 바로 붙이고, 실무에서 자주 쓰는 부가 기능(Redis, Kafka 등)은 필요할 때 빠르게 붙일 수 있게 한다.

1. 전제 (소유자 설명)

2차 리뷰에서 "연결 안 된 코드 약 15만 줄"로 잡힌 코드 상당수는 의도적으로 넣어 둔 부가 기능이다. 프로젝트마다 자주 쓰는 외부 기술(Redis, Kafka 등)을 템플릿이 미리 제공하려고 만들었다. 그러다 너무 커져서 지금 리팩터링하는 중이다. 따라서 목표는 부가 기능을 없애는 것이 아니라 제공 방식을 바꾸는 것이다.

2. 핵심 결론

부가 기능을 제공하는 방향은 유지한다. 문제는 제공 방식이다. 지금은 부가 기능이 두 가지 상태로 흩어져 있다.

  • (a) 기본 모듈 안에 섞여 있다.
  • (b) 설정으로 켜도 실제로 동작하지 않는 반쪽 상태다.

그래서 그 기능을 쓰지 않는 서비스도 비용을 낸다. 해법은 두 가지다.

  • 부가 기능 하나하나를 **"의존성을 붙이면 켜지고, 떼면 사라지는 capability 모듈"**로 포장한다(Spring Boot starter와 같은 방식).
  • 각 서비스는 필요한 모듈만 runtimeOnly 한 줄로 고른다.

3. 흐름

[도메인·유스케이스 코드] ──(포트만 호출)──▶ application-core 포트 (CachePort, LockPort …)
                                                  ▲ 구현
app-bootstrap/build.gradle                        │
  runtimeOnly ':adapter:outbound:cache-redis' ──▶ cache-redis 모듈
                                                   ├─ META-INF/spring/…AutoConfiguration.imports
                                                   └─ app.redis.* 설정 + 연결 env

기능 추가: app-bootstrap/build.gradle에 한 줄을 넣고, .env에 연결 정보를 넣는다. 유스케이스는 원래 쓰던 포트를 그대로 호출한다. 기능 제거: 그 한 줄을 지운다. 다른 파일은 손대지 않는다.

// app-bootstrap/build.gradle — 이 서비스가 쓰는 부가 기능 목록 (한 곳에서 관리)
dependencies {
    runtimeOnly project(':adapter:outbound:cache-redis')      // Redis: cache / lock / idempotency / rate-limit
    runtimeOnly project(':adapter:outbound:messaging-kafka')  // Kafka 발행
    // runtimeOnly project(':adapter:outbound:persistence-mongo')
    // runtimeOnly project(':adapter:outbound:objectstorage')
}

4. 조립 방식 비교

방식 추가 속도 비용
A. 모든 모듈을 runtimeOnly로 기본 포함 + 설정으로 on/off 설정만 바꾸면 됨 끄는 장치 필요, 모든 서비스가 모든 의존성·CVE·이미지 크기를 짊어짐
B. 서비스가 고른 것만 runtimeOnly 한 줄 + "모듈이 있으면 켜짐" (권장) 한 줄 + env 끄는 장치 불필요. upstream(템플릿) merge 시 서비스 쪽 차이는 이 목록 한 곳뿐
C. 각 기능을 버전 붙은 사내 라이브러리로 배포 버전 한 줄 배포 파이프라인 필요. 파생 서비스가 3개 이상일 때 검토

A를 권하지 않는 이유: Spring Boot는 "라이브러리가 classpath에 있으면 켠다"가 기본 동작이다. 쓰지 않는 기능을 jar에 넣어 두면 그것을 끄는 장치가 따로 필요하다. 지금 저장소에 있는 아래 목록이 바로 그 장치이고, 2차 리뷰에서 "활성화 규칙 6곳, 기본값 3가지"로 나온 복잡도의 원인이다.

  • MongoOptInAutoConfigurationImportFilter
  • GraphQlOffAutoConfigurationImportFilter
  • DisabledMessagingSentinelAutoConfiguration
  • CaSkeletonApplication의 scan 제외 정규식(18개 패키지)
  • MasterSwitch
  • 흩어진 startup validator 19개

runtimeOnly라는 방식 자체는 맞다. 비즈니스 코드가 어댑터를 import하지 못하게 되기 때문이다. 다만 서비스가 고른 것만 넣어야 끄는 장치가 필요 없어진다.

5. "연결 안 된 코드" 4분류

분류 예 처리
1. 제공할 부가 기능 (포트 뒤에 있음) Redis cache/lock/idempotency/rate-limit, Kafka 발행, S3 object storage, SES/SMTP 알림, httpclient, Mongo 기본 연결 유지. 6절 완료 기준을 채워 capability 모듈로 포장
2. 라이브러리형 API (서비스 코드가 직접 호출) redis-sdk facade(구현체 없음), Mongo advanced 연산, JPA bulk/copy, graphql advanced, websocket 플랫폼 라이브러리 완성해서 1번처럼 포장하거나 optional-platforms로 이동
3. 리팩터링 잔재 (이전·병행 세대) web 2세대, WebFlux 쌍둥이, outbox V2와 v1, 멱등성 v1, notification R1, messaging R1 encoder, fileserver R2 publication, STOMP 스택 2벌, main에 있는 governance gate 하나만 남기고 삭제. 제공 기능이 줄지 않으면서 크기가 가장 많이 줄어듦
4. SDK도 없는 실험용 자리 pulsar, nats, kafka-share, stream-bridge, 기동 시 거부되는 rabbit, grpc-advanced optional-platforms로 이동하거나 삭제

모듈별 LOC와 근거는 2차 리뷰의 "조립되지 않은 코드 추정치" 표와 S1–S7 절에 있다.

6. capability 모듈 완료 기준

  1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 runtimeOnly로 받을 수 있다.
  2. 모듈이 자기 AutoConfiguration.imports를 가진다. 모듈이 있으면 켜지고, 필요하면 enabled 설정으로 끌 수 있다. 다른 자동 설정에 기대는 경우 순서를 명시한다(afterName). 1차 리뷰 Critical #6(messaging bridge)이 이 순서 문제였다.
  3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작해야 하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다. 반례: 알림 provider 7종 중 5종은 켜면 기동에 실패한다.
  4. 설정 prefix는 하나만 쓴다. 바인딩은 StrictSettingsBinder로 하고, 값 검증은 설정 record의 compact constructor에서 한다.
  5. application-core testFixtures에 있는 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
  6. README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
  7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 MasterSwitch 목록에 등록할 필요가 없고, 한 줄을 지우면 기능이 완전히 사라진다.

7. 주의할 점

  • runtimeOnly의 한계: 분류 2처럼 서비스 코드가 모듈 타입을 직접 호출하는 경우에는 runtimeOnly로 컴파일되지 않는다. 이런 모듈은 서비스의 어댑터 leaf에서 implementation으로 받아야 한다. 부가 기능은 가능한 한 분류 1(포트 뒤) 형태로 만든다.
  • 아키텍처 검사 범위: 운영 jar에 고른 모듈만 들어가면, app-bootstrap architectureTest의 classpath 기준으로 도는 ArchUnit이 빠진 모듈을 보지 못한다. 그래서 둘을 분리한다.
    • architectureTest classpath에는 모든 모듈을 테스트 의존으로 넣는다.
    • 운영 runtimeClasspath에는 고른 모듈만 넣는다.
    • 참고로 Gradle 방향 검사는 이미 모든 leaf를 본다.
    • 1차 리뷰 L-4에서 sample과 grpc 어댑터가 ArchUnit에서 빠진 것도 같은 원인이다.

8. 리뷰 결정 D1–D6 권고 (이 방향 기준)

# 결정 권고
D1 연결 안 된 코드 5절 4분류를 적용한다: 1은 포장, 2는 완성 또는 이동, 3은 삭제, 4는 이동
D2 outbox 정본 앱 outbox를 하나로 합친다. v1 테이블을 유지하고 V2/V1002의 owner+token fencing을 이식한 뒤 V2를 삭제한다. Kafka capability는 이 outbox를 relay한다. messaging platform outbox는 vendored라 유지한다
D3 멱등성 정본 V2. Redis와 PostgreSQL 두 provider가 같은 포트를 구현하고, executor는 한 곳에서 조립한다
D4 WebFlux 템플릿은 servlet(가상 스레드)으로 정하고 WebFlux 쌍둥이 코드는 삭제한다. 필요해지면 capability로 다시 추가한다
D5 빌드 목표 O3. 기능별 검증은 각 capability 모듈의 테스트로 옮기고, build-logic에는 아키텍처 검사와 공통 규칙만 남긴다. 먼저 2차 리뷰 BUILD 절의 "바로 할 것" 1–12를 적용한다
D6 테스트 컨벤션 2차 리뷰 TEST 절의 제안안을 채택한다. 포트 계약 테스트가 6절 완료 기준 5번과 같은 것이다

9. 진행 순서

  1. capability 완료 기준(6절)과 테스트 컨벤션을 AGENTS.md에 고정한다. CLAUDE.md는 요약만 동기화한다.
  2. 1차 리뷰 Critical을 수정한다. 대부분 제공 기능 자체의 결함이라 먼저 고친다. 수정 PR마다 해당 포트의 계약 테스트를 함께 추가한다.
    • Wave 0(결정 불필요): 빌드 plugin(O-1), CI job(O-2), 마이그레이션 원복 + 새 버전(E-1), @EnableScheduling(L-1), bridge 순서/producer-id(H-1), prod 에러 상세 validator(L-2), sample loggers read-only(L-3)
    • Wave 1: 나머지 데이터·보안 Critical
  3. 분류 3·4를 삭제하거나 이동한다. 크기가 가장 많이 줄어든다.
  4. 분류 1을 capability 모듈로 하나씩 포장한다. 끝날 때마다 bootstrap의 끄는 장치(import filter, scan 정규식, MasterSwitch 항목, 해당 validator)를 걷어낸다.
  5. 빌드를 O3로 옮기고, 테스트 컨벤션을 적용한다(sample-portfolio부터 모범 예제로).

10. 결정 (2026-09-25 소유자 확정)

  1. 기본 조립 방식은 **B(서비스가 고른 것만 runtimeOnly)**로 확정한다.
  2. 템플릿이 처음부터 켜 두는 기능은 web에서 쓰는 부분뿐이다.
    • 기본 포함: HTTP 인바운드(adapter:inbound:web — servlet, 보안, 에러 응답, 요청 로깅), 운영 관측(actuator·metrics·tracing·로그), 도메인·유스케이스 코어(domain-core, application-core, shared-contract), 저장소가 필요 없는 보조(adapter:outbound:support, adapter:outbound:identifier).
    • 기본 제외(한 줄로 추가): JPA/PostgreSQL(Flyway·outbox·JDBC 멱등성·분산 락 포함), Redis, Kafka, 알림, Mongo, object storage, HTTP client, GraphQL, WebSocket, gRPC, 파일 서버.
    • 해석 근거: "web에서 사용하는 부분"을 인바운드 HTTP와 그 운영 요소로 읽었다. DB도 기본에서 뺐으므로 새 서비스는 DB가 필요하면 persistence-jpa 한 줄을 넣는다. 이 해석이 다르면 app-bootstrap/build.gradle의 해당 줄 주석만 푼다(다른 파일 변경 없음 — 6절 7번).

실행 계획: docs/superpowers/plans/2026-09-25-capability-module-packaging.md (Wave 0부터).