S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를 충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에 올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다 닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은 runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로 붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를 세며, JDK transport는 그 설정을 읽지 않는다. 고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로 본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막 close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용 lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다. 압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍 본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈 본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원 (transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이 transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지 않으면 반환 타입 mapping이 갈라진다). 위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다. S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다 (Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이 돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다. 검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과. Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31 BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(AGENTS.md)과 같은 절차(docs/work/)로 일한다. 라이브러리 버전은 gradle/libs.versions.toml이 정한다.
프로젝트 구조
저장소 루트가 Gradle 루트다. 빌드 도구와 빌드 파일은 루트에, 코드는 src/에 둔다. 허용 목록 밖의 최상위 항목은 scripts/check-repo-layout.py가 PR에서 막는다.
| 폴더·파일 | 하는 일 | 먼저 읽을 곳 |
|---|---|---|
src/ |
계층별 앱 코드. leaf(Gradle 프로젝트)만 있다 | 아래 표 |
settings.gradle, build.gradle, gradlew |
Gradle 빌드. 단계 태스크(prCheck·mainCheck 등)와 registry를 읽는 settings |
docs/build.md |
gradle/ |
wrapper, 버전 카탈로그 libs.versions.toml, 모듈 registry modules.json, 시험 컨테이너 이미지 목록 container-images.properties |
gradle/README.md |
build-logic/ |
빌드 규칙(convention plugin, registry 검사) | build-logic/README.md |
config/ |
코드 검사 도구 설정(checkstyle, spotbugs) | — |
Dockerfile, .env.example |
릴리스 이미지(빌드 context는 저장소 루트), env 계약 | docs/build.md |
docs/ |
문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | docs/README.md |
scripts/ |
Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 검증 진입점, 저장소 배치·문서 검사 | scripts/bootstrap-local.sh, scripts/new-feature.sh, scripts/verify.sh |
compose.yaml |
개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
compose/ |
compose.yaml이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) |
compose/redis/acl/README.md |
.gitea/ |
workflow(pr·main·release)와 공용 action |
docs/work/reference/gates.md |
.github/ |
CODEOWNERS, PR 양식, 의존성 취약점 정책 | .github/dependency-vulnerability-policy.md |
src/ 아래 폴더는 계층이다. 같은 계층의 leaf는 그 계층 폴더 아래에 있다. leaf 목록·폴더·Gradle path·허용 의존은 registry gradle/modules.json이 정한다. Gradle path는 폴더와 다르다(:application-core는 src/application/core, :composition:outbox-relay는 src/bootstrap/outbox-relay).
| 폴더 | 책임 | 기본 조립에 들어가나 |
|---|---|---|
src/domain/core/ |
도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
src/application/core/ |
command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
src/application/fileserver/, src/application/notification/, src/application/objectstorage/ |
capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
src/shared-contract/ |
저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
src/adapter/inbound/ |
HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | web만 들어간다 |
src/adapter/outbound/ |
port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | support·identifier만 들어간다 |
src/bootstrap/app/ |
Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
src/bootstrap/ 의 나머지 |
조립만 하는 composition:* leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 |
service-runtime·outbox-relay·idempotency·durable-operation이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
의존은 항상 바깥에서 안으로 흐른다. 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
환경 변수는 .env(로컬 실행 입력)와 .env.example(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 docs/build.md와 docs/registries/env-keys.yaml이다.
기능 켜고 끄기
기본 조립(bootJar)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, support·identifier뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. ./gradlew :app-bootstrap:bootRun으로 바로 실행할 수 있다.
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 src/bootstrap/app/build.gradle에 주석 처리된 runtimeOnly 한 줄씩으로 있다.
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의
enabled키를false로 둔다. - 줄마다 필요한 env 키와 끄는 키: docs/build.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).
검증
명령은 저장소 루트에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 gradle_path에서 읽는다.
./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain
./gradlew test는 모든 leaf의 test를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 docs/work/reference/gates.md가 정한다. 게이트 태스크 하나하나의 설명은 docs/build.md 「build.gradle — 빌드 / 검증 게이트」다.
문서를 고쳤으면 저장소 루트에서 python3 scripts/check-docs.py를 돌린다. 규칙은 docs/README.md 「문서 검사」다.
새 서비스로 시작하기
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
-
settings.gradle의rootProject.name을 새 서비스 이름으로 바꾼다. -
패키지 루트
dev.caskeleton을 서비스 패키지로 바꾼다. Java 소스만이 아니라AutoConfiguration.imports·spring.factories·빌드 스크립트·설정 파일·생성 명령 템플릿, SpotBugs 제외 목록(config/spotbugs/), 루트build.gradle과 build-logic의group, registry와 공개 API 스냅숏(docs/registries/,docs/architecture/,docs/notification/api-surface-snapshot.txt)도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. build-logic 자신의 패키지(dev.caskeleton.buildlogic)는 앱 패키지가 아니라 그대로 둬도 된다.git grep -l -e 'dev\.caskeleton' -- src scripts config build.gradle docs/registries docs/architecture docs/notification git grep -l -e '"dev\.caskeleton"' -- build-logic/src/mainSpotBugs 목록을 빼먹으면
qualityCheck가, 스냅숏을 빼먹으면 각 leafcheck의 API surface 검사가 실패한다. -
CaSkeletonApplication을 새 애플리케이션 이름으로 바꾼다. -
새 업무 기능은
scripts/new-feature.sh <FeatureName>으로 만들고 docs/manual/README.md 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다. -
쓰는 capability의
runtimeOnly줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다. -
라이브러리 패키지
dev.cakit.*은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는dev.caskeleton과 이름이 겹치지 않게 정했다. 라이브러리 목록은 관련 저장소다. -
Docker 이미지 이름과 애플리케이션 이름(
spring.application.name)을 새 서비스 기준으로 바꾼다. -
.env.example,.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 양식을 채운다.