문제: 이미 적용된 전이를 다시 보낸 호출에 Redis·PostgreSQL 저장소와 in-memory fake가 다르게 답한다. - 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete를 다시 보내면 Redis·PostgreSQL은 ALREADY_COMPLETED_SAME_RESULT, fake는 NOT_OWNER. - 같은 경우의 markFailed는 Redis ALREADY_MARKED_SAME_OPERATION, PostgreSQL OPERATION_CONFLICT, fake NOT_OWNER. markFailed를 적용한 핸들이 응답을 잃고 다시 보내면 fake만 NOT_OWNER. - release한 핸들로 start하면 PostgreSQL은 NOT_OWNER, Redis·fake는 ABSENT. - 같은 원인(재생 판정이 "어느 핸들이 적용했나"를 보지 않음)이 다른 전이에도 있다. PostgreSQL은 기록된 renew·release와 digest가 다른 핸들을 모두 OPERATION_CONFLICT로 답해, 주인이 renew가 돌려준 핸들로 다시 renew해도 거절하고 넘겨받기 전 핸들의 renew·release도 OPERATION_CONFLICT다. fake는 적용한 핸들이 start·renew를 다시 보내도 NOT_OWNER다. 방법: 소유자 결정(2026-11-06) 「넘겨받기 전 핸들의 재전송」「해제된 핸들로 start」대로 맞춘다. "적용한 핸들"은 owner identity가 같고 기록보다 revision이 하나 낮은 핸들이다. 라운드6에서 start에 쓴 기준을 모든 전이에 쓴다. - Redis TRANSITION과 command fake: ALREADY 조건에서 "start가 아니면 아무 핸들" 분기를 지우고 rev == handle rev + 1만 남긴다. 다른 핸들은 revision 검사로 내려가 NOT_OWNER·WRONG_STATE. - PostgreSQL: replayVerdict가 적용한 핸들일 때만 재생(같은 digest → 이미 처리됨, 다른 digest → OPERATION_CONFLICT)으로 읽는다. 다른 핸들은 owner 검사로 내려가 NOT_OWNER. complete 재생 판정도 owner token 대신 적용한 핸들을 본다. - fake: 마지막으로 적용한 전이와 그 핸들·인자(renew lease, fail disposition) 를 기억해 start·renew·complete·markFailed 재전송에 저장소와 같게 답한다. - release한 핸들의 start는 계약이 ABSENT·NOT_OWNER를 둘 다 받고 포트 Javadoc(IdempotencyStartOutcome)에 적는다. 코드 동작은 그대로. 버린 대안: PostgreSQL complete·fail 재생을 전이 digest 비교만으로 하기(complete digest에 replay TTL이 들어가 같은 결과·다른 TTL 재전송이 RESPONSE_CONFLICT가 된다), Redis를 원래 주석 의도대로 두고 fake·PostgreSQL을 "operation의 아무 핸들"로 넓히기(소유자 결정과 반대, 넘겨받기 전 핸들이 남의 결과를 자기 것으로 확인받는다), 재생 핸들을 attempt만으로 가리기(같은 attempt가 넘겨받으면 attempt가 올라가지만 renew 뒤의 낡은 핸들은 attempt가 같다). 공유 계약 IdempotencyStoreContract에 10케이스를 더했다. 포트 결과 enum Javadoc 넷, application-core CLAUDE.md·README, persistence-jpa·cache-redis README, TESTING_STRATEGY, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다. 위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 넘겨받기 전 핸들로 다시 보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르는 코드는 넘겨받기 전 핸들의 재전송에 NOT_OWNER를 받고, PostgreSQL에서 renew를 이어 부를 수 있게 된다. fake로 응답 유실을 흉내 내던 테스트는 이제 "이미 처리됨"을 받는다. 적용한 핸들이 markFailed를 다른 retention·disposition 으로 다시 보낼 때의 답은 저장소마다 다르고 IdempotencyFailOutcome Javadoc과도 다르다(범위 밖, 보고에 적음). 검증: desktop, 공유 잠금, 기준73d39212. - RED(기준 커밋 + 계약 테스트만, 로그 ~/r8-f4-red-logs/): in-memory fake 계약 59 중 4 실패(적용한 핸들의 start·renew·markFailed 재전송, "expected: ALREADY_MARKED_SAME_OPERATION but was: NOT_OWNER" 등), Redis command fake 2·실 Redis(redisContainerContractTest) 2 실패("expected: NOT_OWNER but was: ALREADY_COMPLETED_SAME_RESULT"·"…ALREADY_MARKED_SAME_ OPERATION"), 실 PostgreSQL(jpaPlatformContractTest) 5 실패(complete는 ALREADY_COMPLETED_SAME_RESULT, markFailed·renew·release는 OPERATION_CONFLICT, 두 번째 renew는 "expected: RENEWED but was: OPERATION_CONFLICT"). release한 핸들의 start 케이스는 동작 변경이 없어 처음부터 셋 다 통과한다. lane마다 실패 수는 위 계약 실패 수와 같다. - GREEN(이 커밋과 같은 트리377d1232, 로그 ~/r8-f4-green-logs/): 네 leaf check(application-core 422·skip 19 fake 시간 케이스, persistence-jpa 664, cache-redis 225, redis-runtime 65), 네 leaf testQualityCheck, redisContainerContractTest 100, jpaPlatformContractTest 429, postgresqlIdempotencyIntegrationTest 10, fake를 쓰는 leaf(composition: idempotency check 32, redis-sdk test 310, web test 329, sample-portfolio test 339), documentContractTest 66 — 모두 rc=0, 실패 0. - scripts/check-work-docs.py, git diff --check 통과. BREAKING CHANGE: IdempotencyStorePort 구현은 이미 적용된 전이의 재전송을 그 전이를 적용한 핸들(기록보다 revision이 하나 낮은 핸들)에게만 "이미 처리됨" 으로 확인하고 다른 핸들은 NOT_OWNER로 답해야 한다. 직접 구현한 store는 IdempotencyStoreContract의 새 케이스로 확인한다.
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