clean-architecture-backend-template/AGENTS.md

AGENTS.md

프로젝트 정체성

이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + Spring Boot 4.0.0 + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.

기본 패키지는 dev.caskeleton이며, 예시 도메인은 production 모듈이 아니라 sample-portfolio 모듈(WorkLog 엔지니어링 작업 기록 게시판)에 격리한다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.

Prime Directive

에이전트는 속도보다 아키텍처 보존을 우선한다.

동작하는 코드라도 HARD-STOP 조건을 하나라도 위반하면 완료된 작업이 아니다.

HARD-STOP 8개 항목의 SSOT 는 .agents/plugins/ca-superpowers/rules/clean-architecture.md §HARD-STOP 이다. 이 문서는 목록 사본을 유지하지 않는다 — 불일치 시 SSOT 파일이 우선한다. (항상 로드되는 요약 사본은 root CLAUDE.md Prime Directive 에 있다.)

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: 스킬을 만들거나 수정할 때 사용한다.

Harness 정책 SSOT

• .harness/manifest.yaml: Java 21 / Spring Boot 4.0.0 프로젝트 identity와 task packet 진입점
• .harness/project/modules.yaml: 19개 leaf의 ID, 소스 경로, Gradle path, 허용 edge, focused command
• .harness/core/risk-policy.yaml: change-surface 기반 risk 분류
• .harness/core/evidence-policy.yaml: risk별 evidence/review profile
• .harness/core/review-policy.yaml: orchestration, option/counterargument, human-only commit 정책
• .harness/core/report-policy.yaml: concise/durable report와 citation self-grep 정책

작업 시작 시 task packet을 한 번 resolve하고 stable packet/rule hash를 재사용한다. overlay나 관련 hash가 바뀔 때만 다시 resolve하거나 rule 전문을 재정독한다. 파일 수는 risk 분류 기준이 아니다. commit 정책은 모든 플랫폼에서 human-only이며 agent는 stage/commit/amend/push하지 않는다.

LLM Wiki 캡처 워크플로우

구현, 아키텍처, 빌드, 테스트, 런타임, 문서 워크플로우 변경처럼 의미 있는 작업을 끝낸 뒤에는 최종 응답 전에 LLM Wiki 기록을 갱신한다.

기준 vault:

/home/donghyeon/workspace/ai-tool/llm-wiki-private/

에이전트는 해당 vault의 AGENTS.md, CLAUDE.md, rules/, .agents/, .claude/, .codex/ 지침을 확인한 뒤 작성한다. ca-tmpl 내부의 상세 실행 규칙은 .agents/plugins/ca-superpowers/rules/llm-wiki-capture.md를 따른다.

필수 순서:

1. /home/donghyeon/workspace/ai-tool/llm-wiki-private/raw/branch-notes/<branch-name>.md를 생성하거나 갱신한다.
2. 구현 내용, 변경 파일, 의사결정, 검증 명령, 실패/차단 사항, 증거 등급을 branch-note에 기록한다.
3. 실제로 파생 자료가 있으면 다음 raw 문서를 생성하거나 갱신한다.
   • raw/errors/: 오류, 실패한 테스트, 샌드박스/도구 문제, 재발 가능한 트러블슈팅
   • raw/interviews/: 이 작업에서 정직하게 뽑을 수 있는 면접 질문
   • raw/blog-topics/: 채용공고가 아닌 구현·설계·트러블슈팅 기반 블로그 글감
4. 파생 문서는 ## Parent에서 branch-note로 upward link하고, branch-note의 ## Cluster / 묶음에는 파생 문서 wikilink를 되돌려 적는다.
5. canonical 추출 요청이 없는 한 wiki/blog/, wiki/interview/, wiki/portfolio/, wiki/concepts/, wiki/projects/를 바로 만들지 않는다.

파생 문서가 필요 없을 때도 그냥 생략하지 말고, branch-note의 cluster 섹션에 "없음" 또는 "추출할 별도 글감 없음"처럼 판단 결과를 남긴다.

강제 수준

이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다.

이 프로젝트의 규칙은 세 단계로 관리한다.

1. AGENTS.md: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다.
2. ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다.
3. Code Review/CI: 문서와 자동 검증이 놓친 설계 품질, 운영 위험, 템플릿 일관성을 최종 확인한다.

에이전트는 AGENTS.md를 따라 작업해야 하며, 현업 수준의 스켈레톤 완성도는 반드시 자동 검증과 리뷰로 보강해야 한다.

모듈 책임

19개 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 의존성, focused test 명령은 .harness/project/modules.yaml이 SSOT다. 이 문서는 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는 .harness/project/modules.yaml의 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를 돌린다.
11. LLM Wiki branch-note와 필요한 파생 raw 문서를 갱신한다.
12. 완료 응답에는 변경 파일, 검증 결과, Wiki capture 결과를 포함한다.

테스트 전략

계층별 테스트 기준:

• 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 설정을 검증한다.

검증 원칙:

• 완료를 주장하기 전에 superpowers:verification-before-completion을 사용한다.
• 실행한 명령과 결과를 최종 응답에 적는다.
• 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다.

권장 절차:

cd src
python3 ../.harness/validators/resolve_task.py <task-overlay.json>
# resolved packet의 focused_commands를 실행
./gradlew test
./gradlew check    # check 가 verifyCleanArchitectureDependencies + verifyEnvKeys 2종을 전이 실행한다 (src/build.gradle)
./gradlew verifyCleanArchitectureDependencies
./gradlew verifyPublicPathSnapshot
./gradlew verifyEnvKeys

19개 leaf의 정확한 focused test 명령은 .harness/project/modules.yaml과 resolved task packet을 따른다. root 문서에 별도 명령 목록을 복제하지 않는다.

설정과 런타임

설정 규칙:

• 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로 바꾼다.
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. 전체 테스트를 실행한다.

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 실행
• 테스트 미실행 상태에서 "완료"라고 말하기

작업 보고 규칙

최종 응답에는 다음을 포함한다.

• 변경한 파일
• 핵심 변경 내용
• 실행한 검증 명령
• 실패하거나 실행하지 못한 검증
• LLM Wiki branch-note와 파생 문서 캡처 결과
• 남은 위험 또는 후속 작업

짧은 작업이라도 검증 여부는 생략하지 않는다.