문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).
방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.
위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).
검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).
Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
24 KiB
AGENTS.md
프로젝트 정체성
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
기본 패키지는 dev.caskeleton이며, 예시 도메인은 production 모듈이 아니라 sample-portfolio 모듈(WorkLog 엔지니어링 작업 기록 게시판)에 격리한다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
Prime Directive
에이전트는 속도보다 아키텍처 보존을 우선한다.
동작하는 코드라도 HARD-STOP 조건을 하나라도 위반하면 완료된 작업이 아니다.
다음 HARD-STOP 7개 항목이 이 저장소의 정본(canonical) 로컬 정책 권위이자 SSOT다.
domain-core가 framework, transport, database, cloud 의존성을 가진다.- controller가 repository, Spring Data interface, persistence entity를 직접 사용한다.
- inbound DTO가
application-core또는domain-core로 유출된다. - 비즈니스 규칙이 mapper, filter, configuration, settings, controller로 이동한다.
- 프로젝트 의존성이
src/config/architecture/modules.json또는 Gradle 의존성 검증을 위반한다. - 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다.
- 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다.
root CLAUDE.md는 이 목록의 동기화된 요약이다. 두 문서가 어긋나면 이 AGENTS.md 목록이
우선한다. 자동 강제 범위는 아래 Gradle 정책 권위와 ArchUnit/Test가 담당한다.
Superpowers Workflow
이 프로젝트에서 에이전트는 관련 Superpowers 스킬을 먼저 확인하고, 작업 성격에 맞는 스킬을 사용한다. 사용자 지시와 이 AGENTS.md가 로컬 프로젝트의 최상위 규칙이며, Superpowers는 그 규칙을 실행하기 위한 작업 방식이다.
사용 가능한 주요 스킬과 트리거:
superpowers:using-superpowers: 대화나 작업을 시작할 때 관련 스킬을 확인한다.superpowers:brainstorming: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다.superpowers:writing-plans: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다.superpowers:executing-plans: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다.superpowers:subagent-driven-development: 계획을 작업 단위로 나누어 독립 에이전트에게 맡길 때 사용한다.superpowers:dispatching-parallel-agents: 서로 독립적인 조사나 구현을 병렬로 진행할 때 사용한다.superpowers:test-driven-development: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다.superpowers:systematic-debugging: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다.superpowers:verification-before-completion: 완료, 수정됨, 통과함을 주장하기 전에 사용한다.superpowers:requesting-code-review: 의미 있는 구현을 마친 뒤 병합 또는 PR 전에 사용한다.superpowers:receiving-code-review: 리뷰 피드백을 적용하기 전에 사용한다.superpowers:finishing-a-development-branch: 구현과 검증이 끝난 브랜치를 정리할 때 사용한다.superpowers:using-git-worktrees: 격리된 작업 공간이 필요할 때 사용한다.superpowers:writing-skills: 스킬을 만들거나 수정할 때 사용한다.
Gradle 정책 권위
src/config/architecture/modules.json: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가 받을 수 있는 모듈은allowed_dependencies가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 — 산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다:verifyDocumentedLeafCount는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든CLAUDE.md와build.gradle을 정규식으로 훑는 파서였다.src/settings.gradle:ca.architecture-registry설정 플러그인이 registry를 읽어 project를 include/mapping 한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은verifyCleanArchitectureDependencies가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.src/build-logic/: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나 (strictTestLanes). leaf는ca.java-library/ca.spring-library/ca.platform-module중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.ca.architecture가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging· graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test taskinputs로 선언한다. 저장소 문서와 대조하는 테스트는mainStage()레인(document-contract태그)으로 leafmainCheck에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstraprepository-contract)에 둔다. 저장소 루트(ca.repository.root)는 이 두 레인에만 주므로 태그 없이 저장소를 읽는 테스트는test에서 실패한다.- strict lane 캐시:
TEST·ARCHITECTURElane은 입력이 같으면 up-to-date·build cache를 쓴다.INTEGRATION·SYSTEM·PERFORMANCElane과mainStage()lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다. verifyEnvKeys는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의ca.config-contract다.src/build-tools/included build는 비워서 삭제했다.src/build.gradle: 루트 라이프사이클(ci,mainCheck,integrationCheck,performanceCheck,releaseCheck,qualityCheck,configContractCheck)과 버전/리비전.verifyStrictLaneStages --dry-run(PR 게이트)은 그 빌드에서explicitOnly가 아닌 strict lane이 workflow가 실제로 실행하는 단계(main 빌드:ci·sample-portfolio:check·mainCheck·integrationCheck·performanceCheck·releaseCheck, optional-platforms 빌드:-p optional-platforms로 부르는ci·integrationCheck·performanceCheck·releaseCheck) 중 하나에 들어 있는지, 그리고 workflow의 접힌(>) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다.-x로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(--dry-run·-m·-v·--help·--status·--stop·--foreground, 묶음-qm·-qv포함)과 Gradle이 거부하는 짧은 옵션 묶음(-mx), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다. (1) 실패해도 단계가 실패하지 않을 수 있다:|| exit <0 아닌 값>밖의||(|| true등), pipefail 없는 파이프 왼쪽,!,&,if·while조건, 스크립트 마지막이 아닌&&목록의 앞쪽,set +e뒤,exit 0하는EXIT·ERRtrap 뒤,continue-on-error. (2) 돌지 않을 수 있다:||뒤, 마지막이 아닌&&목록의 뒤쪽,if·while·for·case·함수 본문 안, 최상위exit·exec·set -n뒤, 조건부이거나 부른 함수 안의exit 0(인자 없는exit, 값을 모르는exit포함)·exec·set -n뒤, 상태 함수(always()·success()·!cancelled())가 아닌if:아래, 요청으로만 시작하는 workflow(workflow_dispatch·repository_dispatch·issue_comment등), 세는 job이 부르지 않는workflow_call재사용 workflow, 조건부이거나continue-on-error인 job을needs로 기다리는 job. (3) 실패하면 단계도 실패하지만 검사가 읽지 않는다:|| exit 1,{ }·( )·$( )·bash -c안, 다른 명령의 인자인gradlew, 따라갈 수 없는cd(cd "$VAR"·cd -·pushd·조건부·서브셸 등) 뒤,bash·sh가 아닌shell:, Windows일 수 있는 runner의 기본 셸(pwsh). 실패 메시지는 명령마다 이유를 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는working-directory에서 시작해 같은 셸이 그 앞에서 확실히 실행한cd <상대 경로>를 따라간 뒤-p를 합친 디렉터리로 정한다.
작업 파일의 소유 leaf는 registry의 source_path로 판단하고 가장 가까운 src/**/CLAUDE.md를
함께 읽는다. focused test는 registry의 gradle_path에서
./gradlew <gradle-path>:test --console=plain 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고,
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
commit 정책은 모든 플랫폼에서 human-only이며 agent는 stage/commit/amend/push하지 않는다.
강제 수준
이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다.
이 프로젝트의 규칙은 세 단계로 관리한다.
AGENTS.md: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다.- ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다.
- Code Review/CI: 문서와 자동 검증이 놓친 설계 품질, 운영 위험, 템플릿 일관성을 최종 확인한다.
에이전트는 AGENTS.md를 따라 작업해야 하며, 현업 수준의 스켈레톤 완성도는 반드시 자동 검증과 리뷰로 보강해야 한다.
모듈 책임
모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성은
src/config/architecture/modules.json이 SSOT다. focused test는 소유 leaf의 gradle_path에서
파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운
src/**/CLAUDE.md를 함께 읽는다.
domain-core: 순수 도메인 모델, 불변식, 이벤트, port. Spring/JPA/transport/IO 타입 금지.application-core: command, use case, application policy, transaction port, application 예외. inbound DTO, persistence entity, adapter 타입 금지.adapter:inbound:*: HTTP/gRPC/GraphQL/WebSocket transport, DTO, validation, 인증·인가 매핑, error mapping. repository 직접 호출과 비즈니스 정책 금지.adapter:outbound:persistence-*: JPA/PostgreSQL 또는 MongoDB persistence 구현과 mapping, migration/vendor 동작. 유스케이스 정책 금지.- 그 밖의
adapter:outbound:*: support, messaging, cache, notification, object storage, file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는 registry만 따른다. shared-contract: skeleton-wide 운영 계약. business/domain 개념 저장 금지.sample-portfolio: 샘플/fixture consumer. production leaf가 의존하면 안 된다.app-bootstrap: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
의존성 방향
family 수준 기본 방향:
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
runtime modules -> shared-contract
sample-portfolio -> registered runtime leaves (fixture consumer only)
개별 edge는 src/config/architecture/modules.json의 allowed_dependencies가 유일한 목록이다.
Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억에서 leaf edge를 추론하지 않는다.
기능 개발 프로토콜
새 기능이나 동작 변경은 다음 순서로 진행한다.
- 요구사항을 읽고 소유 계층을 판단한다.
- 구조나 동작이 바뀌면
superpowers:brainstorming으로 설계를 먼저 확정한다. - 여러 단계의 작업이면
docs/superpowers/specs/에 설계 문서를 남긴다. - 구현 전
docs/superpowers/plans/에 실행 계획을 작성한다. - 동작 변경은 테스트를 먼저 작성한다.
- 새 비즈니스 개념은
domain-core에 먼저 둔다. - 유스케이스는
application-corecommand와 use case/service method로 표현한다. - 외부 연동은 registry가 가리키는
adapter:outbound:*leaf에서 port 구현으로 추가한다. - endpoint는 마지막에 해당
adapter:inbound:*leaf에서 얇게 연결한다. - focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 docs/manual/, 뼈대는
scripts/new-feature.sh <FeatureName>이 계층 leaf에 만든다. sample-portfolio는 모든 계층을 한 leaf에
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
테스트 전략
계층별 테스트 기준:
domain-core: Spring 없이 순수 unit test로 도메인 규칙을 검증한다.application-core: fake/in-memory port를 사용해 유스케이스 흐름을 검증한다.adapter:inbound:*: transport validation, auth mapping, status/response contract를 검증한다.adapter:outbound:persistence-*: persistence mapping, repository adapter, vendor/migration 동작을 검증한다.- 그 밖의
adapter:outbound:*: external capability adapter contract를 검증한다. app-bootstrap/settings: configuration binding, validation, logging 설정을 검증한다.
테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용):
- 이름은 lowerCamelCase 행동 문장(
<상황/주체><결과>)이다. 이름에 적은 성질은 반드시 단언한다. @DisplayName은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 쓴다(소유자 결정 5). 기존 영어@DisplayName은 그 테스트를 고칠 때 한국어로 바꾼다.- 본문 문장이 3개 이상이면
// given// when// then주석과 구역 사이 빈 줄을 둔다. 준비할 것이 없으면// given은 생략한다.// when은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. 예외 테스트는catchThrowable로 when을 분리한다(기존assertThatThrownBy는 손댈 때// when & then까지 허용). 한 줄 테스트와 ArchUnit.check()는 주석 없이 쓴다. @Nested는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.- then은 when의 결과 하나만 단언한다. 여러 필드는
usingRecursiveComparison()또는extracting(..).containsExactly(..)로 한 번에 비교한다.isNotNull/isPresent/doesNotThrowAnyException만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은@ParameterizedTest로 쓴다. - 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는
포트는 fake와 adapter가 같은 추상 계약 테스트(
XxxContract)를 통과한다. Mockito는 프레임워크 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, 실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
검증 원칙:
- 완료를 주장하기 전에
superpowers:verification-before-completion을 사용한다. - 실행한 명령과 결과를 최종 응답에 적는다.
- 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다.
권장 절차:
cd src
./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne
./gradlew check # 모든 leaf의 check
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
./gradlew ci # PR 게이트 = leaf check + architecture + quality
./gradlew mainCheck # main 단계 = env 계약·전체 기동(샘플 포함)·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly)
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p optional-platforms로 따로)
./gradlew verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys
leaf의 check는 그 leaf만 검사한다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다.
소유 leaf의 정확한 Gradle path는 src/config/architecture/modules.json에서 읽고 focused test
명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다.
부가 기능(capability) 모듈 규칙
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
각 서비스는 app-bootstrap/build.gradle에 필요한 모듈만 runtimeOnly 한 줄로 고른다.
설계 근거는 docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md.
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: adapter:inbound:web, 운영 관측(actuator·metrics·
tracing·로그), domain-core·application-core·shared-contract, adapter:outbound:support·
adapter:outbound:identifier. 그 밖의 기능(JPA 포함)은 한 줄을 추가해서 켠다.
capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
- 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을
runtimeOnly로 받을 수 있다. - 모듈이 자기
AutoConfiguration.imports를 가진다. 모듈이 있으면 켜지고, 필요하면enabled설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(afterName). - 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다.
- 설정 prefix는 하나만 쓴다. 바인딩은
StrictSettingsBinder, 값 검증은 설정 record의 compact constructor에서 한다. 예외(리뷰 05-18): Redis는app.redis.*(redis-runtime, setter+validate())·app.capabilities.*·app.rate-limit.*세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중 하나에 넣고 네 번째 트리는 만들지 않는다. 이유는src/adapter/outbound/cache-redis/CLAUDE.md. - 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
- 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
- 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지 않고, 한 줄을 지우면 기능이 완전히 사라진다.
모듈 설정 기본값은 config/module-defaults/<모듈>.yml에 두고 adapter:outbound:support의
ModuleDefaultsEnvironmentPostProcessor 하나가 읽는다. 의존성 closure에 support가 없는 leaf
(persistence-mongo, graphql)만 자기 EPP가 config/<이름>.yml을 읽는다.
서비스 코드가 모듈 타입을 직접 호출해야 하는 라이브러리형 기능은 runtimeOnly로 컴파일되지
않는다. 그런 기능은 가능한 한 포트 뒤로 옮기고, 불가피하면 서비스의 어댑터 leaf에서
implementation으로 받는다.
설정과 런타임
설정 규칙:
- secrets를 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다.
- 새 설정 그룹은 typed settings class로 만든다.
- 흩어진
@Value보다 configuration properties와 settings class를 선호한다. .env.local은 로컬 오버라이드로 취급한다.application.yml은 환경별로 안전한 기본값과 명확한 placeholder만 담는다.- 새 settings class를 만들면 binding/validation 테스트를 추가한다.
Docker/runtime 규칙:
- Dockerfile 변경 시 build context와 runtime env 요구사항을 함께 확인한다.
- container 안에서 필요한 profile, port, env var를 문서나 예시 설정에 반영한다.
- local-only 경로와 운영 경로를 섞지 않는다.
템플릿 재사용 체크리스트
이 저장소를 새 프로젝트 시작점으로 사용할 때:
src/settings.gradle의rootProject.name을 새 프로젝트명으로 바꾼다.- Java package
dev.caskeleton을 새 organization/project package로 바꾼다. gRPC 플랫폼을 쓰면 proto 조직 이름caskeleton(src/grpc/grpc-contract/src/main/proto/caskeleton/의 디렉터리, 각.proto의package·java_package)도 함께 바꾸고buf lint로 확인한다. CaSkeletonApplication이름을 새 애플리케이션 이름으로 바꾼다.- production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가하고, 예시 코드는
sample-portfolio에 격리한다. - 모듈 이름과 경계는 유지한다.
- Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
.env,.env.local,application.yml의 예시 값을 새 런타임 요구사항에 맞춘다.- README와 운영 문서를 새 프로젝트 설명으로 갱신한다.
- 전체 테스트를 실행한다.
cd src
./gradlew test
금지된 지름길
에이전트는 다음을 하지 않는다.
domain-core에 Spring/JPA annotation 추가- controller에서 repository 직접 호출
- application method가 web request DTO를 인자로 받게 만들기
- application이나 domain에서 JPA entity 반환
- mapper에 비즈니스 정책 넣기
- filter/config/settings class에 유스케이스 넣기
- 요청 범위 밖의 대규모 리팩터링
- 사용자 변경사항 되돌리기
- 명시적 요청 없는 destructive git command 실행
- 테스트 미실행 상태에서 "완료"라고 말하기
작업 보고 규칙
최종 응답에는 다음을 포함한다.
- 변경한 파일
- 핵심 변경 내용
- 실행한 검증 명령
- 실패하거나 실행하지 못한 검증
- 남은 위험 또는 후속 작업
짧은 작업이라도 검증 여부는 생략하지 않는다.