# 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다. 1. `domain-core`가 framework, transport, database, cloud 의존성을 가진다. 2. controller가 repository, Spring Data interface, persistence entity를 직접 사용한다. 3. inbound DTO가 `application-core` 또는 `domain-core`로 유출된다. 4. 비즈니스 규칙이 mapper, filter, configuration, settings, controller로 이동한다. 5. 프로젝트 의존성이 `src/config/architecture/modules.json` 또는 Gradle 의존성 검증을 위반한다. 6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다. 7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다. root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면 이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 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`: 이 저장소에서는 쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠 맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다. - `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 task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap `repository-contract`)에 둔다. 저장소 루트(`ca.repository.root`)는 이 두 레인에만 주므로 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다. - strict lane 캐시: `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다. `INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다. - `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. - `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`·`ERR` trap 뒤, `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 :test --console=plain` 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고, 변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다. commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다. 예외는 하나다: 작업 지시(brief)가 허용하면 그 작업의 자기 브랜치에만 commit·push한다. main 병합, 다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」). ## 강제 수준 이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다. 이 프로젝트의 규칙은 세 단계로 관리한다. 1. `AGENTS.md`: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다. 2. ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다. 3. 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 수준 기본 방향: ```text 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를 추론하지 않는다. ## 기능 개발 프로토콜 새 기능이나 동작 변경은 다음 순서로 진행한다. 1. 요구사항을 읽고 소유 계층을 판단한다. 2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다. 3. 여러 단계의 작업이면 `docs/superpowers/specs/`에 설계 문서를 남긴다. 4. 구현 전 `docs/superpowers/plans/`에 실행 계획을 작성한다. 5. 동작 변경은 테스트를 먼저 작성한다. 6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다. 7. 유스케이스는 `application-core` command와 use case/service method로 표현한다. 8. 외부 연동은 registry가 가리키는 `adapter:outbound:*` leaf에서 port 구현으로 추가한다. 9. endpoint는 마지막에 해당 `adapter:inbound:*` leaf에서 얇게 연결한다. 10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다. 단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는 `scripts/new-feature.sh `이 계층 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 설정을 검증한다. 테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용): 1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다. 2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다. 3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할 것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. 예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때 `// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다. 4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다. 5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는 `extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`/`isPresent`/ `doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다. 6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는 포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다. GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, 실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다. 검증 원칙: - 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다. - 실행한 명령과 결과를 최종 응답에 적는다. - 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다. 권장 절차: ```bash cd src ./gradlew :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개 모두 충족해야 "포장 완료"): 1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다. 2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(`afterName`). 3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다. 4. 설정 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`. 5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다. 6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키. 7. 이 모듈을 아는 곳은 모듈 자신뿐이다. 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 경로와 운영 경로를 섞지 않는다. ## 템플릿 재사용 체크리스트 이 저장소를 새 프로젝트 시작점으로 사용할 때: 1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다. 2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다. gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/grpc/grpc-contract/src/main/proto/caskeleton/`의 디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다. 3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다. 4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가하고, 예시 코드는 `sample-portfolio`에 격리한다. 5. 모듈 이름과 경계는 유지한다. 6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다. 7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다. 8. README와 운영 문서를 새 프로젝트 설명으로 갱신한다. 9. 전체 테스트를 실행한다. ```bash 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 실행 - 테스트 미실행 상태에서 "완료"라고 말하기 ## 작업 보고 규칙 최종 응답에는 다음을 포함한다. - 변경한 파일 - 핵심 변경 내용 - 실행한 검증 명령 - 실패하거나 실행하지 못한 검증 - 남은 위험 또는 후속 작업 짧은 작업이라도 검증 여부는 생략하지 않는다.