Files
clean-architecture-backend-…/docs/manual/03-placement.md
T
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00

4.9 KiB

03. 새 기능을 둘 곳 고르기

핵심

새 기능을 두는 모양은 셋이다. 업무 기능의 기본은 ① 계층 leaf 안 <feature> 패키지다. 선택해서 켜고 끄는 플랫폼 기능만 ② 별도 application-* leaf로 만든다. ③ 한 leaf 수직 슬라이스는 지울 수 있는 샘플 전용이다. 생성 명령은 ①만 만든다.

① 계층 leaf 안 패키지 (기본)
   domain-core/.../domain/<f>  ->  application-core/.../application/<f>  ->  adapter:*/.../<f>  ->  app-bootstrap/.../autoconfigure/<f>

② 기능 전용 leaf (capability)
   application-<f>  ->  persistence-<f>, adapter:outbound:<f>, adapter:inbound:web-<f>  ->  composition:<f>-platform
   app-bootstrap/build.gradle 에 runtimeOnly 한 줄

③ 한 leaf 수직 슬라이스 (샘플 전용)
   sample-portfolio = domain + application + adapter + bootstrap 패키지

기준표

질문 ① 계층 leaf 패키지 ② 기능 leaf ③ 수직 슬라이스
서비스마다 켜고 끌 수 있어야 하나 아니오 예 —
다른 서비스가 같은 기능을 라이브러리로 받나 아니오 예 아니오
한 줄 지워 기능을 통째로 빼야 하나 아니오(패키지 삭제) 예(runtimeOnly 한 줄) 예(leaf 삭제)
leaf 단위 의존 방향 검사가 기능 안에도 걸리나 예(계층이 leaf) 예 아니오(ArchUnit 패키지 규칙에만 기댐)
고칠 공용 파일 없음(+ imports 한 줄) modules.json, settings.gradle 매핑, app-bootstrap/build.gradle, lockfile modules.json
예시 생성 명령 출력, application-core/.../operation application-notification, application-fileserver, application-objectstorage sample-portfolio

판단: ①과 ② 중 무엇인가

  • 고르는 기준: 이 기능을 쓰지 않는 서비스(또는 같은 서비스의 다른 배포)가 있는가.
  • 기본값: ①. 업무 기능은 그 서비스의 존재 이유라 끌 일이 없다. 파일 추가만으로 끝나고, leaf 경계 검사가 계층마다 걸린다.
  • 예외: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기 저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(AGENTS.md, 10장).
  • 다시 볼 조건: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트 시간이 문제가 되면 ①을 ②로 옮긴다(리뷰 01 영역 5.2절).

판단: ③을 써도 되나

  • 기본값: 쓰지 않는다. ③은 leaf 하나가 모든 계층에 의존해서 leaf 단위 방향 검사가 기능 안에서는 아무것도 막지 못한다.
  • 예외: 통째로 지울 수 있어야 하는 샘플·데모. sample-portfolio가 그 예다. 샘플을 계층 leaf로 쪼개지 않는 이유는 "leaf 하나 지우면 끝"이라는 성질을 지키려는 것이다.

① 안의 패키지 규칙

계층 패키지 하위 패키지
domain dev.caskeleton.domain.<f> fake·계약은 testFixtures dev.caskeleton.domain.<f>.testkit
application dev.caskeleton.application.<f> 종류별 하위 패키지(command, usecase, port)를 만들지 않는다. 기능별 한 패키지(sample P30 결정과 같다)
outbound dev.caskeleton.adapter.outbound.<leaf>.<f>
inbound dev.caskeleton.adapter.inbound.web.<f>
bootstrap dev.caskeleton.bootstrap.autoconfigure.<f> @AutoConfiguration만(BOOTSTRAP_AUTOCONFIGURE_STEREOTYPES_ARE_AUTO_CONFIGURATIONS)
  • <f>는 템플릿 패키지 이름(operation, outbox, lock, cache, secret, notification…)과 겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를 이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
  • 어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 src/application-core/CLAUDE.md 「Package ownership」이다. 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 뒤에는 ArchUnit(NamingConventionTest의 package ownership 규칙 두 개)이 다시 막는다.
  • 이름 규칙은 같은 파일 「Naming convention」이 정본이다.

저장 adapter는 어디에

① 기능의 저장 adapter 위치는 04장 「판단: 저장 adapter를 둘 leaf」. 요약: persistence-jpa에 업무 코드를 넣지 않는다(그 leaf는 capability라 "모듈을 아는 곳은 모듈 자신뿐" 규칙이 걸린다).

지금 이해하면 되는 것

  • 업무 기능 = ① 계층 leaf 패키지. 생성 명령이 이 모양을 만든다.
  • 켜고 끄는 플랫폼 기능 = ② 별도 leaf, capability 기준 7개.
  • sample-portfolio는 기법 참고용이지 배치 예시가 아니다.