문제: 살아 있는 문서의 언어, 기록의 상태 표시, 인라인 코드 경로, 복사한 버전·개수를 아무 검사도 보지 않는다. lychee는 마크다운 링크만 보는데 경로 대부분은 인라인 코드로 쓰여 있고, leaf CLAUDE.md는 Spring Boot 버전을 4.0.0으로 적어 둔 채 낡았다. 고른 방법: Gradle 밖 scripts/check-docs.py 하나에 검사 넷을 둔다. - language: 살아 있는 문서와 ADR 본문이 한국어인가. 판정은 보고 언어 훅 H11과 같다(코드·명령·경로·인용을 빼고 영어 낱말 3개 이상, 한글 비율 0.3 미만이면 영어). - head: 기록·ADR 맨 위 머리 블록의 칸, 종류별 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로. - reference: 인라인 코드 안 src/·docs/·scripts/·infra/·.github/ 경로와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, 「> 이력」 인용, 제거 표, upgrade/는 건너뛴다. leaf 기준 경로는 어느 파일의 끝부분과 맞으면 있다고 본다. - number: Spring Boot x.y.z와 leaf 개수 문장. 예외 목록(scripts/check-docs-exceptions.txt)은 2026-11-07 기준선 217줄이고 줄기만 한다. 줄마다 sha256 지문이 스크립트의 FROZEN에 있어야 해서 목록에 새 줄을 더하면 실패하고, 더는 걸리지 않는 줄을 남겨 두면 실패한다. workflow docs-check.yml이 PR마다 경로 필터 없이 자기 시험과 검사를 돌린다. 코드에서 파일을 지우는 변경이 문서를 낡게 만들기 때문이다. 같은 커밋에서 지도 CLAUDE.md의 Spring Boot 버전 복사를 정본 가리키기로 고쳤다. 버린 대안: 예외 목록 하나에 「늘리지 않는다」는 약속만 두는 방식(테스트의 KNOWN_DEVIATIONS와 같은 꼴)은 brief가 요구한 「더하면 실패」를 기계로 막지 못한다. 기준선을 git 이력(merge-base)과 비교하는 방식은 얕은 checkout에서 깨진다. 검사를 link-check.yml에 더하는 방식은 그 workflow가 docs 경로에만 걸리고 repository-contract 테스트가 trigger를 고정한다. CI 재편 때 단계 workflow로 접는다. 위험·한계: 타입 이름 검사(지운 클래스 이름)는 넣지 않았다. 외부 타입과 구분하려면 git 전체 이력이 필요하다. 경로 검사는 루트 폴더로 시작하는 경로만 보므로 src/ 기준 상대 경로(adapter/outbound/...)는 보지 않는다. leaf 개수 규칙은 설계 문서의 개수 같은 정당한 숫자도 잡을 수 있다(지금 generator 출력 예 하나가 예외 목록에 있다). 구조 정리가 src/messaging 등을 옮기면 예외 줄의 경로가 바뀌므로 그 병합에서 FROZEN을 함께 고쳐야 한다. 레지스트리 yaml 설명 칸의 언어는 보지 않는다. 검증: python3 -m unittest discover -s scripts/tests 42개 통과. 변이 시험: 기준선 확인·낡은 예외 확인·언어 판정·이력 인용 건너뛰기·소스 세트 이름· 끝부분 대조·상태 어휘를 하나씩 끄면 해당 시험이 실패했다. python3 scripts/check-docs.py rc=0(language 181·reference 7·number 29가 모두 예외, head 0), check-work-docs.py rc=0.
ca-skeleton — Clean Architecture Spring Boot 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 dev.caskeleton이며, 예시 도메인은 production 모듈이 아니라 sample-portfolio 모듈(WorkLog 작업 기록 게시판)에 격리합니다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 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
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)
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 |
sample-portfolio |
WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
등록된 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 # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
scripts/bootstrap-local.sh는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, GET /api/healthcheck HTTP smoke를 순서대로 실행합니다. 각 단계가 bootstrap N/4 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
docker compose -f docker-compose.yml -f docker-compose.local.yml down
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 모듈에 추가합니다. 예시 코드는sample-portfolio에만 둡니다. -
모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서
./gradlew test를 호출하면 등록된 모든 하위 프로젝트의 test를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 ci task가
담당합니다.
cd src
./gradlew :app-bootstrap:test
./gradlew :sample-portfolio:check
./gradlew architectureCheck
병합 전 저장소 전체 검증이 필요하면 ./gradlew ci를 실행합니다.
sample-portfolio는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.
아키텍처 규칙과 검증
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. 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
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
grpcPerformanceTest— latency percentile·saturation·drain budget을 측정한다. 공유 CI runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leafbuild.gradle이 이 태스크의 태그를test에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.openapiCheckSnapshot— 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는OpenApiDriftContractTest는:sample-portfolio:test의 일부이고, 그건check안이며 stage 1에서 실행된다. 이 태스크의 고유한 역할은-PapproveOpenApiChange로 커밋된 스냅샷을 다시 만드는 것 — 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.
더 알아보기
- 빌드·검증 게이트·환경 변수 상세: 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