docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다

leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).

- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
  CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
  src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
  AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
  지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
  CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
  기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
  때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
  AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
  check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
  workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.

위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.

검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.

BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
This commit is contained in:
DongHyeonka
2026-11-07 21:58:12 +09:00
parent b3f63be655
commit 08f932123a
102 changed files with 3107 additions and 2986 deletions
+1 -1
View File
@@ -200,4 +200,4 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
+1 -1
View File
@@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스
빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다.
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다.
H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
+1 -1
View File
@@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에
| 입력 | 규칙 | 어디서 막나 |
| --- | --- | --- |
| 이름 | PascalCase, 영숫자 | 스크립트 |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
+2 -2
View File
@@ -50,7 +50,7 @@
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`.
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`.
## 2단계 — application-core: 유스케이스와 포트
@@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md`
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md`
「Allowed transactional shapes」.
### 판단: 무엇을 반환하나
+1 -1
View File
@@ -55,7 +55,7 @@
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md`
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md`
「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
+1 -1
View File
@@ -16,7 +16,7 @@
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
```
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
## 판단: 이 쓰기를 KEYED로 만드나
+1 -1
View File
@@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
`docs/messaging/delivery-guarantees.md`.
## 순서
+2 -2
View File
@@ -5,8 +5,8 @@
## 배치·이름
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다.
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다.
## domain
+2 -2
View File
@@ -42,8 +42,8 @@
| --- | --- |
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) |
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 |
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 |
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
+1 -1
View File
@@ -27,7 +27,7 @@
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다.
## 브로커 등급
+1 -1
View File
@@ -3,7 +3,7 @@
파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden").
(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden").
전체 흐름:
+14
View File
@@ -0,0 +1,14 @@
# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스)
- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부
- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」
## 1. 누가 읽나
이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다.
## 2. 바뀐 것과 할 일
| # | 바뀐 것 | 서비스가 할 일 |
| --- | --- | --- |
| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src/<leaf>/CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) |
+1 -1
View File
@@ -31,7 +31,7 @@
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다.
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다.
4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다.
+2 -2
View File
@@ -4,7 +4,7 @@
## 1. 언제 쓰나
- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
- 이것은 아니다.
- 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절)
- 설계서·ADR → [research-design.md](research-design.md)
@@ -28,7 +28,7 @@
## 4. 절차
1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
+1 -1
View File
@@ -69,7 +69,7 @@
### 4.3 리팩터링, 성능, 구조, 테스트 구조
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다.
- 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다.
- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다.
+1 -1
View File
@@ -29,7 +29,7 @@
## 4. 절차
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다.
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다.
3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 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 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
+2 -2
View File
@@ -2,7 +2,7 @@
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
## 패턴
@@ -121,7 +121,7 @@
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) |
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) |
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
## 패턴을 더하는 법
+5 -5
View File
@@ -101,7 +101,7 @@
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
@@ -123,9 +123,9 @@
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
@@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
@@ -212,7 +212,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
+1 -1
View File
@@ -26,7 +26,7 @@
- `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」
- `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서)
- `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안"
- 가장 가까운 `src/**/CLAUDE.md`와 모듈 README
- 가장 가까운 `src/**/AGENTS.md`와 모듈 README
- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다.