템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(AGENTS.md)과 같은 절차(docs/work/)로 일한다. 라이브러리 버전은 src/gradle/libs.versions.toml이 정한다.
프로젝트 구조
저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 scripts/check-repo-layout.py가 PR에서 막는다.
| 폴더 | 하는 일 | 먼저 읽을 곳 |
|---|---|---|
src/ |
Gradle 루트. 모든 코드, 빌드 규칙, registry | src/README.md |
docs/ |
문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | docs/README.md |
scripts/ |
Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | scripts/bootstrap-local.sh, scripts/new-feature.sh |
compose.yaml |
개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
compose/ |
compose.yaml이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) |
compose/redis/acl/README.md |
.github/ |
workflow, 공용 action, PR 양식, 의존성 취약점 정책 | .github/dependency-vulnerability-policy.md |
src/ 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry src/config/architecture/modules.json이 정한다.
| 폴더 | 책임 | 기본 조립에 들어가나 |
|---|---|---|
domain-core/ |
도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
application-core/ |
command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
application-fileserver/, application-notification/, application-objectstorage/ |
capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
shared-contract/ |
저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
adapter/inbound/ |
HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | web만 들어간다 |
adapter/outbound/ |
port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | support·identifier만 들어간다 |
composition/ |
조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | service-runtime·outbox-relay·idempotency·durable-operation이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
app-bootstrap/ |
Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
platforms/ |
들여온 제품: messaging(메시징 플랫폼). gRPC 플랫폼 라이브러리는 2026-11-08에 별도 repo grpc-library로 옮겼다(관련 저장소) |
들어가지 않는다. adapter를 거쳐서만 닿는다 |
build-logic/, config/, gradle/ |
빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
app-bootstrap ─▶ adapter:inbound:* ─▶ application-core ─▶ domain-core
app-bootstrap ─▶ adapter:outbound:* ─▶ application-core ─▶ domain-core
모든 런타임 모듈 ─▶ shared-contract
불변식: 도메인 규칙은 domain-core와 application-core에만 있고, 기술 선택(웹, DB, 메시징)은 adapter에만 있다.
시작하기
전제는 Temurin 21(.tool-versions에 고정)과 Docker Engine 또는 Docker Desktop이다. Gradle은 저장소의 wrapper를 쓴다. 첫 실행 진입점은 하나다.
scripts/bootstrap-local.sh
이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, GET /api/healthcheck 확인. 단계마다 bootstrap N/4 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 compose.yaml 하나다.
성공하면 이 명령이 HTTP 200을 돌려준다.
curl -fsS http://localhost:8080/api/healthcheck
내릴 때는 저장소 루트에서 --profile '*'를 붙인다. 붙이지 않으면 profile로 띄운 db 같은 서비스가 남는다.
docker compose --profile '*' down
환경 변수는 src/.env(로컬 실행 입력)와 src/.env.example(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 src/README.md와 docs/registries/env-keys.yaml이다.
기능 켜고 끄기
기본 조립(bootJar)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, support·identifier뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. cd src && ./gradlew :app-bootstrap:bootRun으로 바로 실행할 수 있다.
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 src/app-bootstrap/build.gradle에 주석 처리된 runtimeOnly 한 줄씩으로 있다.
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의
enabled키를false로 둔다. - 줄마다 필요한 env 키와 끄는 키: src/README.md 「기능 추가 = 한 줄 + env」 표.
- 기능마다 조립·검증 상태: docs/capability-status.md.
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: docs/manual/10-capabilities.md.
뒷단 서비스는 compose.yaml의 profile로 고른다(docker compose --profile redis up -d --wait). profile 목록은 그 파일 머리에 있다.
문서 지도
모든 문서 폴더의 지도는 docs/README.md다. 무엇을 하려는지에 따라 여기서 시작한다.
| 하려는 일 | 시작할 곳 |
|---|---|
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 docs/work/README.md. 지도는 AGENTS.md |
| 새 업무 기능 만들기 | 개발 매뉴얼 docs/manual/README.md와 생성 명령 scripts/new-feature.sh |
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | docs/web/http-contract.md, docs/registries/ |
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(docs/jpa/, docs/redis/ 등), 장애 코드별 런북 docs/runbooks/ |
| 왜 이렇게 정했는지 보기 | 결정 기록 docs/adr/ |
| 예전 설계·계획·리뷰 찾기 | 기록 docs/design/, docs/history/, docs/reviews/. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
| 템플릿 변경을 파생 서비스에 받기 | docs/upgrade/ |
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 AGENTS.md와 README에 있다(예: domain-core, app-bootstrap).
검증
명령은 src/에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 gradle_path에서 읽는다.
cd src
./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain
./gradlew test는 모든 leaf의 test를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 docs/work/reference/gates.md가 정한다. 게이트 태스크 하나하나의 설명은 src/README.md 「build.gradle — 빌드 / 검증 게이트」다.
문서를 고쳤으면 저장소 루트에서 python3 scripts/check-docs.py를 돌린다. 규칙은 docs/README.md 「문서 검사」다.
새 서비스로 시작하기
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
-
src/settings.gradle의rootProject.name을 새 서비스 이름으로 바꾼다. -
패키지 루트
dev.caskeleton을 서비스 패키지로 바꾼다. Java 소스만이 아니라AutoConfiguration.imports·spring.factories·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.git grep -l 'dev\.caskeleton' -- src scripts -
CaSkeletonApplication을 새 애플리케이션 이름으로 바꾼다. -
새 업무 기능은
scripts/new-feature.sh <FeatureName>으로 만들고 docs/manual/README.md 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다. -
쓰는 capability의
runtimeOnly줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다. -
라이브러리 패키지
dev.cakit.*은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는dev.caskeleton과 이름이 겹치지 않게 정했다. 라이브러리 목록은 관련 저장소다. -
Docker 이미지 이름과 애플리케이션 이름(
spring.application.name)을 새 서비스 기준으로 바꾼다. -
src/.env.example,src/.env.local.example,application.yml의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다. -
README와 운영 문서를 새 서비스 설명으로 고친다.
복사한 뒤 지워도 되는 것은 템플릿의 기록(docs/design/, docs/history/, docs/reviews/)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 python3 scripts/check-docs.py와 링크 검사(docs/work/reference/gates.md 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(docs/upgrade/2026-11-docs-records.md).
이름을 바꾼 뒤에는 위 「검증」의 두 명령과 ./gradlew :app-bootstrap:test --console=plain을 돌린다.
규칙과 기여
- 규칙의 정본이자 일을 시작할 때 읽는 지도는 AGENTS.md다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 CLAUDE.md가 이 파일을 가져온다.
- 일의 종류별 절차는 docs/work/README.md다.
- 각 모듈의 지역 규칙은 가장 가까운
src/**/AGENTS.md다. - 커밋 정책과 메시지 형식은 docs/work/README.md 「커밋」이다. PR은 .github/pull_request_template.md 양식을 채운다.