docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다

계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
This commit is contained in:
DongHyeonka
2026-11-08 22:57:03 +09:00
parent 93e3c7b1a6
commit f117a5af41
29 changed files with 248 additions and 30 deletions
+18
View File
@@ -0,0 +1,18 @@
# AGENTS.md — `src/adapters` (재사용 capability runtime)
application 포트를 구현하는 HTTP, 인증, 저장소, query cache, telemetry, worker 등이다. 그룹마다 `src/adapters/<그룹>/index.ts`(배럴)가 공개 경계다.
## 지킬 것
- 그룹 밖에서는 배럴로만 들어온다. 2단계 `index.ts`는 공개 배럴이 아니다(예외 `storage/indexeddb`, `storage/opfs`).
- 다른 adapter 그룹을 import하지 않는다(`adapters-do-not-know-other-concrete-adapters`). 예외는 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이고 새 파일 단위 예외를 만들지 않는다. 새 공유 프리미티브는 `src/adapters/platform/`에 둔다.
- presentation·bootstrap을 import하지 않는다(`adapters-do-not-know-presentation`). 일반 worker는 네트워크·자격 증명 adapter를 모른다. Service Worker 입구는 페이지 코드가 아니다.
- 실패 분류는 status와 code를 함께 본다. 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:adapter-inventory`(FE-GATE-010 안): 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(이 파일도 거기 행이 있다)
- `check:browser-file-storage-boundaries`·`check:realtime-boundaries`(FE-GATE-010 안)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`, `tests/contract`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+16
View File
@@ -0,0 +1,16 @@
# AGENTS.md — `src/application` (일반 유스케이스와 포트)
유스케이스, 포트, 정책, view-model이 있다. 구체 runtime을 모른다.
## 지킬 것
- presentation·adapters·bootstrap·React·TanStack을 import하지 않는다(`application-does-not-know-concrete-runtime`).
- 포트는 추가만 한다. 시그니처를 깨야 하면 결정을 받고 BREAKING으로 커밋한다.
- 결과 불명 쓰기의 재전송 판정은 한 곳에 둔다(`docs/manual/02-decision-tables.md` 3·4절).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `test:unit`(FE-GATE-005)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`, 포트 소비자 계약은 `tests/contract`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+15
View File
@@ -0,0 +1,15 @@
# AGENTS.md — `src/apps` (배포 단위)
앱마다 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다.
## 지킬 것
- adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`). 조립은 `src/bootstrap`이 한다.
- 선언은 작은 리터럴 머리다. `scripts/generate-product-feature-index.ts`가 읽어 `src/.generated/`를 만든다. 선언 모양을 바꾸면 그 생성기와 함께 고친다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:scale:pr`(FE-GATE-005 안): 앱·context 예산
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/bootstrap` (조립 뿌리)
런타임 설정을 읽고, 구체 adapter를 만들어 application 포트에 끼우고, React를 붙이는 곳이다. 구체 adapter를 조립하는 곳은 여기 하나다.
## 지킬 것
- 업무 규칙을 두지 않는다. 판정·정책은 `src/application`·`src/platform`·기능 폴더에 둔다.
- 선택하지 않은 realtime·web-push runtime을 조립하지 않는다(`unselected-realtime-runtime-is-not-composed`). 기능 runtime은 `src/features/loaded-feature-runtimes.ts`만 불러온다(`boot-does-not-load-every-feature-runtime`).
- 제품마다 다른 조립은 제품 소유 파일 `src/bootstrap/product-composition.ts`에 둔다. 템플릿 소유 파일을 고쳐야 하면 결함이다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `build`(FE-GATE-011), `check:bundle`(FE-GATE-012): 초기 JS·파일 수 예산
- 런타임 설정 키를 바꾸면 루트 `README.md` 런타임 변수 표와 `verify:documentation`
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`(조립된 경계), `tests/e2e`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+16
View File
@@ -0,0 +1,16 @@
# AGENTS.md — `src/contexts` (bounded context)
context마다 `context-module.ts`가 앱, 라우트 뿌리, 기능 예산을 선언한다. 생성 명령 `create:feature`가 새 context를 만든다.
## 지킬 것
- context끼리 import하지 않는다(`contexts-do-not-import-other-contexts`). adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`).
- context 폴더를 손으로 만들거나 경계를 바꾸는 일은 크기가 큼이다(`docs/work/new-feature.md` 3절).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:scale:pr`(FE-GATE-005 안): 기능 예산
- FE-GATE-020: 기능을 더하고 지운 사본
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
## 지킬 것
- application·features·presentation·bootstrap을 import하지 않는다(`contracts-do-not-know-application`, `contracts-do-not-know-presentation-or-bootstrap`). zod는 여기의 `zod.ts`로만 들어간다.
- 레지스트리 행은 원본(스키마, descriptor)에서 뽑는다. 손으로 다시 적으면 대조 테스트를 같이 둔다.
- 제품마다 다른 계약은 제품 소유 파일 `src/contracts/product-contracts.ts`에 둔다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+19
View File
@@ -0,0 +1,19 @@
# AGENTS.md — `src/features` (지울 수 있는 기능)
기능 하나는 `src/features/<id>/{domain,application,contracts,adapters,presentation}`이고 기능 폴더째 지울 수 있다. 이 폴더 바로 아래의 `*.ts`는 설치된 기능 목록(카탈로그)이다.
새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다(스킬 `new-feature`).
## 지킬 것
- 기능끼리 import하지 않는다(`features-do-not-import-other-features`). 공용이 필요하면 `src/contracts/`나 kernel로 옮기는 일을 따로 묻는다.
- 기능 안 방향: domain은 framework·runtime을 모르고, application은 adapter·presentation을 모르고, presentation은 바깥 adapter를 모르고, adapters는 presentation을 모른다(`feature-*` 규칙 넷).
- 기능 밖 adapter는 기능의 `adapters/`나 `feature-adapter-contribution.ts`로만 닿는다(`feature-and-app-roots-do-not-reach-adapters`). presentation은 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
- 기능 테스트는 `tests/features/<id>/`에 둔다. 플랫폼 테스트를 기능에 묶지 않는다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- FE-GATE-020: 생성한 기능을 더하고 지운 사본, 기능 제거는 `test:sample-removal -- --feature=<id>`
- 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)은 생성 출력 `Next:`의 명령으로 다시 쓴다
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/features/<id>/`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+15
View File
@@ -0,0 +1,15 @@
# AGENTS.md — `src/platform` (제품과 무관한 프리미티브)
예산, 실행 문맥, 회복력, telemetry 파이프라인, 오류 봉투, 릴리스 일관성처럼 어느 폴더든 쓰는 것이다. adapter kernel(`src/adapters/platform/`)과는 다른 폴더다.
## 지킬 것
- features·contexts·apps·adapters·bootstrap·presentation·application을 import하지 않는다(`platform-kernel-is-product-neutral`, 예외 `platform/routing/`).
- 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 상수 `true` 판정을 두지 않는다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `test:unit`(FE-GATE-005)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/presentation` (일반 UI와 들어오는 adapter)
라우트, 레이아웃, 디자인 시스템, 페이지, provider가 있다. 제품 기능이 아닌 일반 UI다.
## 지킬 것
- adapter·bootstrap을 import하지 않는다(`presentation-does-not-know-adapters`, 예외 `presentation/adapters/query`). 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
- 페이지 템플릿은 레이아웃만 가진다(`page-templates-own-layout-only`). 설치된 제품 기능은 정해진 파일만 조립한다(`generic-presentation-does-not-compose-the-product`). apps·contexts를 import하지 않는다(라우터 하나 예외).
- 디자인 시스템은 `src/presentation/design-system/index.ts`로만 들어간다. 토큰 밖 색·간격을 쓰지 않는다(`docs/styling/design-tokens.md`).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:design-system`·`check:i18n`(FE-GATE-010 안)
- `test:component`(FE-GATE-006), e2e·접근성(FE-GATE-008·009), 시각 골든(`tests/visual/`)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/component`, `tests/e2e`, `tests/visual`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md