앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 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절
3.6 KiB
3.6 KiB
AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 src/gradle/libs.versions.toml, 기본 패키지 dev.caskeleton). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.
HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
domain-core가 framework·transport·database·cloud 의존성을 가진다.- controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
- inbound DTO가
application-core나domain-core로 들어간다. - 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
- 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
- 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
- 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
지도
- Gradle 루트는
src/다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registrysrc/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.md4절). - 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(
docs/work/delegate.md).