문제: cb67b879가 `docs/web/repository-adaptation.md:65`의 baseline 숫자를
4.0.8에서 4.0.9로 고쳤다. 이 파일은 문서 번역 작업(D2d)이 지금 옮기고 있고,
총괄은 숫자를 하나도 고치지 않기로 정했다(2026-11-07). 번역 작업이 숫자를
복사하는 대신 정본(`src/gradle/libs.versions.toml`)을 가리키게 바꾸므로 4.0.9도
그때 맞춰진다.
고친 방법: 그 한 줄을 4.0.8로 되돌린다. 이 파일은 기준 커밋 5ab1b418과 같아진다.
- cb67b879는 이미 push해서 고쳐 쓰지 않고 되돌림 커밋을 붙인다.
위험·한계: 번역이 끝날 때까지 이 줄과 check-docs 예외로 얼린 8곳이 실제 Boot
4.0.9와 다른 숫자를 말한다.
검증: 앞 커밋과 같다(트리 fbb325c1에서 문서 검사 전부 rc=0).
`git diff 5ab1b418 -- docs/web/repository-adaptation.md`가 비어 있다.
ca-skeleton — Clean Architecture Spring Boot 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 dev.caskeleton입니다. 업무 기능의 예시는 생성 명령 scripts/new-feature.sh의 출력과 docs/manual/입니다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 CLAUDE.md가, 빌드·환경 변수 상세는 src/README.md가 소유합니다.
아키텍처 한눈에
의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다.
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
모든 런타임 모듈 -> shared-contract
family 수준의 책임은 다음과 같습니다.
| 모듈 family | 책임 |
|---|---|
domain-core |
순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 |
application-core |
command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
adapter:inbound:* |
HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
adapter:outbound:persistence-* |
JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
adapter:outbound:* |
support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 app-bootstrap/build.gradle의 runtimeOnly 한 줄로 고릅니다 |
shared-contract |
skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
app-bootstrap |
Spring Boot entrypoint와 composition root |
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
src/config/architecture/modules.json이 SSOT입니다. focused
test는 해당 Gradle path에서 ./gradlew <gradle-path>:test --console=plain 형태로 파생하며, root
문서나 기억에서 개별 leaf edge를 추론하지 않습니다.
퀵스타트
전제조건은 Temurin 21(루트 .tool-versions에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
scripts/bootstrap-local.sh
scripts/bootstrap-local.sh는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, GET /api/healthcheck HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 compose.yaml 하나입니다. 각 단계가 bootstrap N/4 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
docker compose --profile '*' down
--profile '*'가 없으면 profile이 달린 db가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
Redis·Kafka·MongoDB 같은 뒷단 서비스는 compose.yaml의 profile로 고릅니다(docker compose --profile redis up -d --wait). profile 목록은 그 파일 머리에 있습니다.
src/.env.example은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 src/.env는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 src/README.md와 docs/registries/env-keys.yaml에 있습니다.
기본 조립과 부가 기능
기본 조립(bootJar)은 web, 관측, domain-core·application-core·shared-contract, support,
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.
cd src
./gradlew :app-bootstrap:bootRun
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 app-bootstrap/build.gradle에 주석 처리된
runtimeOnly 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
줄마다 필요한 env와 끄는 키는 src/README.md의 "기능 추가 = 한 줄 + env" 표에 있습니다.
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 |
|---|---|---|
local |
Compose PostgreSQL (./gradlew :app-bootstrap:bootRunH2는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) |
Flyway (H2는 Hibernate create-drop) |
dev |
PostgreSQL | Flyway |
prod |
PostgreSQL | Flyway |
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 src/app-bootstrap/src/main/resources/의 application-{local,dev,prod}.yml이, 상세 설명은 src/README.md가 소유합니다.
새 프로젝트로 시작하기
이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 AGENTS.md의 "템플릿 재사용 체크리스트"에 있습니다.
-
src/settings.gradle의
rootProject.name을 새 서비스 이름으로 바꿉니다. -
패키지 루트
dev.caskeleton을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야mainClass·group이 어긋나bootstrap이 깨지지 않습니다.cd src find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
-
CaSkeletonApplication을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은scripts/new-feature.sh <FeatureName>으로 만듭니다. -
모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
./gradlew test를 호출하면 등록된 모든 하위 프로젝트의 test를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 ci task가
담당합니다.
cd src
./gradlew :app-bootstrap:test
./gradlew architectureCheck
병합 전 저장소 전체 검증이 필요하면 ./gradlew ci를 실행합니다.
아키텍처 규칙과 검증
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬 정책 권위는 AGENTS.md이며, CLAUDE.md는 작업을 시작할 때 읽는 지도입니다. 일의 종류별 절차는 docs/work/에 있습니다.
domain-core는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
- inbound DTO는
application-core나domain-core로 들어가지 않습니다. - 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.
이 규칙은 두 축으로 자동 강제합니다. :app-bootstrap:architectureTest의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을,
verifyCleanArchitectureDependencies 게이트가 JSON registry의 허용 Gradle project edge를
검사합니다.
cd src
./gradlew verifyCleanArchitectureDependencies
두 검증 축은 ci-quality-gates.yml의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.
수동 전용 Gradle 태스크
아래 태스크는 어떤 워크플로도 실행하지 않으며, 그게 의도다. 자동 실행이 틀린 이유를 적어 둔다.
여기 적힌 태스크 이름이 실재하는지 검사하던 verifyReadmeCommands는 삭제했다. 그건 이 문서의
```bash 블록을 직접 파싱해 ./gradlew·docker compose·make 토큰을 실제 태스크 그래프와 대조하는
Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의
함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.
cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
grpcPerformanceTest— latency percentile·saturation·drain budget을 측정한다. 공유 CI runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leafbuild.gradle이 이 태스크의 태그를test에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
더 알아보기
- 빌드·검증 게이트·환경 변수 상세: src/README.md
- 모듈 레지스트리(등록 leaf SSOT): src/config/architecture/modules.json
- 에이전트·기여자 작업 규칙: AGENTS.md · CLAUDE.md
- release/publish 자동화는
.github/workflows/release.yml이 소유하며, release provenance·SBOM· 이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다. - 모듈별 설계 결정: domain-core · application-core · adapter:inbound:web · adapter:outbound:persistence-jpa · shared-contract · app-bootstrap