DongHyeonka 7140f27948 docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).

- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
  규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
  지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
  지킬 규칙 몇 줄을 남겼다.
  - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
    멱등성(KEYED) → 337줄에서 190줄.
  - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
    TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
    194줄.
  - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
  TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
  찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
  AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
  가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
  자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
  코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
  맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
  `lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
  PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.

위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.

검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.

BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
2026-11-07 22:33:08 +09:00

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·grpc-advanced(gRPC 라이브러리, 다른 빌드 optional-build) 들어가지 않는다. 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 「문서 검사」다.

새 서비스로 시작하기

이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.

  1. src/settings.gradle의 rootProject.name을 새 서비스 이름으로 바꾼다.

  2. 패키지 루트 dev.caskeleton을 서비스 패키지로 바꾼다. Java 소스만이 아니라 AutoConfiguration.imports·spring.factories·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.

    git grep -l 'dev\.caskeleton' -- src scripts
    
  3. CaSkeletonApplication을 새 애플리케이션 이름으로 바꾼다.

  4. 새 업무 기능은 scripts/new-feature.sh <FeatureName>으로 만들고 docs/manual/README.md 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.

  5. 쓰는 capability의 runtimeOnly 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.

  6. gRPC 플랫폼을 쓰면 proto 조직 이름 caskeleton도 바꾼다. src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/ 디렉터리와 각 .proto의 package·java_package다. buf lint로 확인한다.

  7. Docker 이미지 이름과 애플리케이션 이름(spring.application.name)을 새 서비스 기준으로 바꾼다.

  8. src/.env.example, src/.env.local.example, application.yml의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.

  9. 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 양식을 채운다.
S
Description
No description provided
Readme
46 MiB
Languages
Java 97.6%
Python 1.1%
Shell 0.9%
Go Template 0.3%