# 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` 목록이 우선한다. 자동 강제 범위는 아래 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 task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. - `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의 `ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다. - `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`, `integrationCheck`)과 버전/리비전 작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를 함께 읽는다. focused test는 registry의 `gradle_path`에서 `./gradlew :test --console=plain` 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고, 변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다. commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다. ## 강제 수준 이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다. 이 프로젝트의 규칙은 세 단계로 관리한다. 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를 돌린다. ## 테스트 전략 계층별 테스트 기준: - `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`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 언어는 영어로 통일한다. 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 ci # PR 게이트 = leaf check + architecture + quality ./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인 ./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에서 한다. 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 실행 - 테스트 미실행 상태에서 "완료"라고 말하기 ## 작업 보고 규칙 최종 응답에는 다음을 포함한다. - 변경한 파일 - 핵심 변경 내용 - 실행한 검증 명령 - 실패하거나 실행하지 못한 검증 - 남은 위험 또는 후속 작업 짧은 작업이라도 검증 여부는 생략하지 않는다.