docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
This commit is contained in:
+1
-1
@@ -74,6 +74,6 @@
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 폴더 지역 규칙(`src/**/AGENTS.md`) 200줄(넘으면 표·근거를 그 leaf README로), 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
## 4. 절차
|
||||
|
||||
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
4. 뼈대를 만든다: `scripts/new-feature.sh <FeatureName>`(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」).
|
||||
5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
|
||||
|
||||
@@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
|
||||
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
|
||||
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
|
||||
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
|
||||
- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
|
||||
@@ -213,7 +213,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
|
||||
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
|
||||
- [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표와 `TemplatePackageOwnership`
|
||||
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
|
||||
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
|
||||
- [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행
|
||||
|
||||
Reference in New Issue
Block a user