Files
clean-architecture-backend-…/AGENTS.md
T
DongHyeonka c611b06f03
pr / vulnerabilities (pull_request) Canceled after 0s
pr / done (pull_request) Canceled after 0s
pr / gradle (pull_request) Canceled after 8m18s
feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·
빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한,
동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그
문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게
합치는지도 정한 곳이 없다.

고른 방법(소유자 결정 2026-11-11 「W3 설계대로」):
- 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을
  만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 →
  검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이
  repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
  be-domain을 미리 싣고 lead 공통 양식으로 돌려준다.
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
  「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다).
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트
  AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와
  delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths·
  설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림,
  명단이 모든 전문가를 담음.
버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07
글이 반대하고, 설명이 모든 세션에 든다.

위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다.

검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는
조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
2026-11-11 23:19:44 +09:00

40 lines
4.4 KiB
Markdown

# AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다.
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
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. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
## 지도
- Gradle 루트는 저장소 루트다. `src/`에는 계층 코드만 있다(`domain/`·`application/`·`adapter/`·`bootstrap/`·`shared-contract/`). leaf 목록·폴더·Gradle path·허용 의존의 정본은 registry `gradle/modules.json`이다. Gradle path는 폴더와 다르다(`:app-bootstrap`은 `src/bootstrap/app`). 문서는 leaf 개수를 적지 않는다.
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/bootstrap/`은 조립 계층이다(조립 루트 `app`과 조립만 하는 `composition:*` leaf).
- capability는 `src/bootstrap/app/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
## 맡은 일
먼저 `docs/work/README.md`, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 서비스 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
## 검증
- 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다.
- leaf 하나: `scripts/verify.sh leaf <gradle-path>`. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다).
## 일하는 방식
- 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절).
- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(`docs/work/delegate.md`).
- 여러 분야에 걸친 일은 리드(메인 세션)가 분야 지식을 골라 새 눈 리뷰어에게 맡기고 합친다. 명단·경로표·넘김·충돌 규칙은 `docs/work/experts.md`다.