Files
clean-architecture-backend-…/AGENTS.md
T
DongHyeonka 7dc5725fe7 docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.

- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
  messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
  messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
  고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
  쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
  라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
  composite build(Gradle 루트가 src/라 ../../messaging-library), registry
  라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
  법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
  review-criteria, defect-patterns, gates, capability-status, manual 07,
  build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
  env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
  라이브러리 문장으로 바꿨다.

위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).

검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.

BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.

Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
2026-11-08 17:11:33 +09:00

3.6 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). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(docs/work/reference/related-repos.md). 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 명령을 하지 않는다.
  • 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(docs/work/delegate.md).