Files
clean-architecture-backend-…/AGENTS.md
T
DongHyeonka 3c73fc333c docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).

- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
  일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
  테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
  계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
  src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
  src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
  docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
  .claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
  .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
  「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
  작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
  행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
  진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
  .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
  읽는다. 단언은 그대로다.

버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.

위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.

검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.

BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
2026-11-07 21:59:42 +09:00

3.5 KiB

AGENTS.md — 백엔드 템플릿의 정본

Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 src/gradle/libs.versions.toml, 기본 패키지 dev.caskeleton). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.

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/다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry src/config/architecture/modules.json이다. 문서는 leaf 개수를 적지 않는다.
  • 방향: app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core, 실행 모듈 → shared-contract. 개별 edge는 registry만 정한다.
  • 지역 규칙은 작업 파일과 가장 가까운 폴더의 AGENTS.md다(leaf, family, src/build-logic). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 .claude/rules/다.
  • 저장소 루트와 src/ 최상위에는 정해진 것만 둔다(허용 목록은 scripts/check-repo-layout.py). src/platforms/*는 계층이 아닌 들여온 제품, src/composition/*는 조립만 한다.
  • capability는 src/app-bootstrap/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의 범위·크기·완료 기준이 먼저다.

검증

  • leaf 하나: registry의 gradle_path로 ./gradlew <gradle-path>:check --console=plain(src/에서). 기억이나 폴더 이름으로 짐작하지 않는다.
  • 저장소 전체: ./gradlew architectureCheck, ./gradlew :app-bootstrap:architectureTest, verifyPublicPathSnapshot·:app-bootstrap:verifyEnvKeys(그 표면을 바꿨을 때). 게이트 고르기는 docs/work/reference/gates.md.
  • 문서·지침을 고쳤으면 python3 scripts/check-work-docs.py와 python3 scripts/check-docs.py.

일하는 방식

  • 커밋 정책은 human-only다. brief가 허용한 것만 자기 브랜치에 한다(docs/work/README.md 4절).
  • 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
  • 일을 나눌 때는 소유자가 열어 보고 멈출 수 있는 별도 세션에 맡긴다(docs/work/delegate.md). Gradle·Docker는 누가 돌려도 desktop에서다.