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:
+1
-1
@@ -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) 「실행 위치」대로 한다.
|
||||
|
||||
@@ -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`로 확인한다.
|
||||
|
||||
@@ -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별 테스트 수를 전후로 비교한다.
|
||||
|
||||
@@ -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,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` |
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
@@ -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으로 찾는다)
|
||||
|
||||
@@ -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`로 반론을 세운다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user