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:
@@ -7,12 +7,7 @@ paths:
|
||||
|
||||
# adapter와 import 규칙을 고칠 때
|
||||
|
||||
정본은 `.dependency-cruiser.json`(규칙), `docs/architecture/layers.md`(설명), `docs/work/reference/structure.md`(바꿀 때 같이 고칠 것)다. 판정은 `check:architecture`(FE-GATE-010)다.
|
||||
규칙의 정본은 `src/adapters/AGENTS.md`(그 폴더의 지역 규칙)와 `.dependency-cruiser.json`이다. 이 파일은 다시 쓰지 않고 가리킨다.
|
||||
|
||||
- 그룹 밖에서는 그 그룹의 `index.ts`(배럴)로만 들어간다. 배럴 밖으로 공개 표면을 늘리지 않는다. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs`).
|
||||
- adapter끼리 import하는 예외는 kernel 셋뿐이다: `src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`. 새 공유 프리미티브는 `src/adapters/platform/`에 넣는다. 새 파일 단위 예외를 만들거나 제안하지 않는다.
|
||||
- adapter는 presentation·bootstrap을 import하지 않는다. 관측 vendor SDK는 adapter 뒤에만 둔다.
|
||||
- adapter 파일을 더하거나 옮기거나 지우면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`check:adapter-inventory`).
|
||||
- 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절).
|
||||
- 편집 훅(N3)은 편집한 파일의 import를 이 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 게이트만 본다.
|
||||
- 실패 분류는 status와 code를 함께 보고, 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나만 쓴다. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다.
|
||||
- import 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절).
|
||||
- 편집 훅(N3)은 편집한 파일의 import를 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 `check:architecture`만 본다.
|
||||
|
||||
@@ -7,11 +7,4 @@ paths:
|
||||
|
||||
# 기능 폴더를 고칠 때
|
||||
|
||||
정본은 `docs/manual/`(만드는 순서와 판단 기준)과 `docs/work/new-feature.md`(크기·완료 기준)다. 새 기능은 스킬 `new-feature`로 시작한다.
|
||||
|
||||
- 뼈대는 `corepack pnpm create:feature <id>`로 만든다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다.
|
||||
- 기능끼리, context끼리 import하지 않는다. 기능의 계층(domain → application → adapters·presentation)은 `.dependency-cruiser.json`의 `feature-*` 규칙을 따른다. 기능 밖 adapter는 기능의 `adapters/`나 `src/features/feature-adapter-contribution.ts`로만 닿는다.
|
||||
- 기능 폴더 밖 파일을 생성 명령 밖에서 고쳐야 하면 거기서 멈춘다(`docs/manual/03-outside-feature-folder.md`). 크기가 큼이다.
|
||||
- 기능 테스트는 `tests/features/<id>/`에 둔다. 기능과 함께 지워진다.
|
||||
- 기능을 더하거나 지우면 초기 JS 기록과 기능 모양 기록이 바뀐다. 생성 명령 출력 `Next:`의 명령으로 다시 쓴다. 예산을 넘으면 올리기 전에 멈추고 묻는다.
|
||||
- 결과 불명 쓰기와 재전송은 `docs/manual/02-decision-tables.md` 3·4절 기준이다.
|
||||
규칙의 정본은 `src/features/AGENTS.md`·`src/contexts/AGENTS.md`(지역 규칙), 절차는 `docs/work/new-feature.md`와 `docs/manual/`이다. 새 기능은 스킬 `new-feature`로 시작한다. 이 파일은 다시 쓰지 않고 가리킨다.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md — 프론트 템플릿의 정본
|
||||
|
||||
도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다.
|
||||
도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 방향과 문제 정의는 `docs/vision.md`·`docs/problem-statement.md`(소유자가 채우는 빈 양식)다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다.
|
||||
|
||||
## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
- 새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다.
|
||||
- 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다(설명 `docs/operations/ci-quality-gates.md`).
|
||||
- adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다.
|
||||
- 폴더를 가로지르는 규칙(테스트·문서·설정)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다.
|
||||
- 지역 규칙은 작업 파일과 가장 가까운 `src/<계층>/AGENTS.md`다. 폴더를 가로지르는 규칙(테스트·문서·게이트 기준)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다.
|
||||
|
||||
## 맡은 일
|
||||
|
||||
|
||||
@@ -149,6 +149,8 @@
|
||||
| 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
|
||||
| 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
|
||||
| 141 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) |
|
||||
| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
|
||||
| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
|
||||
|
||||
합계: **141/141**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
|
||||
|
||||
|
||||
+3
-3
@@ -29,7 +29,7 @@
|
||||
|
||||
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
|
||||
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「미검증」 절. 정한 것은 다시 묻지 않는다.
|
||||
3. 바뀌는 경계를 찾는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다.
|
||||
3. 바뀌는 경계를 찾고 가장 가까운 `src/<계층>/AGENTS.md`를 읽는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다.
|
||||
4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절).
|
||||
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
|
||||
6. 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 [operate.md](operate.md) 「실행 위치」대로 `scripts/verify.sh`로 한다.
|
||||
@@ -70,6 +70,6 @@
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`) 200줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
|
||||
- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
@@ -10,16 +10,18 @@ things break that, and both are mechanical:
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1103/11-07" means nothing to a reader
|
||||
who does not know that review. History belongs in `docs/work/evidence.md` and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The
|
||||
same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md`
|
||||
and the documents under `.claude/` (rules, skills, subagents). Review documents keep their IDs.
|
||||
same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md`,
|
||||
every folder rule book `src/**/AGENTS.md` and the documents under `.claude/` (rules, skills,
|
||||
subagents). Review documents keep their IDs.
|
||||
2. Length. Each entry file has a line limit and the entry path (map + root `CLAUDE.md` + README +
|
||||
one playbook) has a total limit, so a session reads the whole path instead of skimming it. The
|
||||
map limit is 40 lines (owner decision 2026-11-07: the root holds the rules, the map and the
|
||||
router only).
|
||||
|
||||
It also checks that every playbook keeps the shared nine-section skeleton, that the "common
|
||||
mistakes" section stays short, that `CLAUDE.md` starts with the import, and that relative links in
|
||||
the checked files resolve. The same layout and limits as the paired backend template's checker.
|
||||
mistakes" section stays short, that `CLAUDE.md` starts with the import, that every folder rule book
|
||||
`src/**/AGENTS.md` has a `CLAUDE.md` beside it that only imports it (so Claude Code reads the same
|
||||
book) and stays under 200 lines, and that relative links in the checked files resolve. The same layout and limits as the paired backend template's checker.
|
||||
|
||||
Standard library only, so it runs on the laptop and in the edit hook (scripts/hooks/hooks.py, N2).
|
||||
`verify:documentation` (FE-GATE-017) checks the paths, scripts and gate IDs these documents name.
|
||||
@@ -71,6 +73,9 @@ README_LIMIT = 80
|
||||
PLAYBOOK_LIMIT = 150
|
||||
ENTRY_PATH_LIMIT = 350
|
||||
MISTAKES_LIMIT = 10
|
||||
# A folder rule book is read whole whenever a file in that folder is opened (Claude Code: under 200).
|
||||
MODULE_GUIDE_LIMIT = 200
|
||||
SKIPPED_PARTS = {"node_modules", ".generated", "dist"}
|
||||
|
||||
SKELETON = [
|
||||
"1. 언제 쓰나",
|
||||
@@ -196,6 +201,31 @@ def check_claude_entry(errors: list[str]) -> None:
|
||||
errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'")
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/AGENTS.md, the local rule book of a layer folder."""
|
||||
return sorted(path for path in (REPO_ROOT / "src").rglob("AGENTS.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts))
|
||||
|
||||
|
||||
def check_guides(errors: list[str], report: list[str]) -> None:
|
||||
longest = 0
|
||||
for guide in module_guides():
|
||||
lines = line_count(guide)
|
||||
longest = max(longest, lines)
|
||||
if lines > MODULE_GUIDE_LIMIT:
|
||||
errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}")
|
||||
if not guide.with_name("CLAUDE.md").is_file():
|
||||
errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'")
|
||||
for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)):
|
||||
lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
if lines != [IMPORT_LINE]:
|
||||
errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it")
|
||||
if not entry.with_name("AGENTS.md").is_file():
|
||||
errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist")
|
||||
report.append(f"src/**/AGENTS.md: {len(module_guides())} files, longest {longest}/{MODULE_GUIDE_LIMIT}")
|
||||
|
||||
|
||||
def claude_documents() -> list[Path]:
|
||||
"""The tracked Claude Code documents a session reads: path rules, skills, subagent definitions.
|
||||
Only these folders: the rest of .claude/ is local state (worktrees, hook state, settings.local.json)."""
|
||||
@@ -203,7 +233,7 @@ def claude_documents() -> list[Path]:
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP, CLAUDE_ENTRY] + claude_documents()
|
||||
files = [MAP, CLAUDE_ENTRY] + claude_documents() + module_guides()
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
@@ -262,7 +292,8 @@ def check_history(errors: list[str], report: list[str]) -> None:
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents())
|
||||
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents()
|
||||
+ module_guides())
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
@@ -308,6 +339,7 @@ def main() -> int:
|
||||
if check_exists(errors):
|
||||
check_limits(errors, report)
|
||||
check_claude_entry(errors)
|
||||
check_guides(errors, report)
|
||||
check_skeleton(errors)
|
||||
check_history(errors, report)
|
||||
check_links(errors, report)
|
||||
|
||||
@@ -26,7 +26,7 @@ Bash 직후 ──> post-bash ──> desktop에서 pnpm·게이트를 돌
|
||||
| N5 | Stop | 이 세션에서 desktop만 확인할 수 있는 파일(아래 밖의 모든 파일)을 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 편집 전까지 한 번 |
|
||||
|
||||
- N5가 "desktop 실행"으로 치는 것: `ssh <desktop 호스트> …`로 pnpm·`ci:gate`·`verify.sh`·vitest·playwright·`node scripts/…`를 돌린 명령, 또는 `scripts/verify.sh`를 `docs`·`hooks` 밖 단계로(`--on here` 없이) 돌린 명령.
|
||||
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
|
||||
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`, `src/**/AGENTS.md`·`CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
|
||||
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.json`이다(git이 무시한다).
|
||||
- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.*.local`·`.env.<mode>` 읽기·쓰기를 막는다. `.env.example`은 막지 않는다.
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ DOC_TIMEOUT = 20
|
||||
|
||||
# --- N5: an edit that only the desktop can check, until a desktop run --------------------------------------
|
||||
# Laptop-checkable on their own: the hooks and their tests, the work-manual checker, the ledger, Claude
|
||||
# settings and CLAUDE.md. Everything else is checked by gates that need pnpm.
|
||||
# settings, CLAUDE.md and the folder rule books under src/ (scripts/check-work-docs.py checks them). Everything else is checked by gates that need pnpm.
|
||||
LAPTOP_ONLY = (
|
||||
re.compile(r"^\.claude/"),
|
||||
re.compile(r"^scripts/hooks/"),
|
||||
@@ -79,6 +79,7 @@ LAPTOP_ONLY = (
|
||||
re.compile(r"^scripts/check-work-docs\.py$"),
|
||||
re.compile(r"^docs/ledger/"),
|
||||
re.compile(r"^CLAUDE\.md$"),
|
||||
re.compile(r"^src/(?:.+/)?(?:AGENTS|CLAUDE)\.md$"),
|
||||
)
|
||||
DESKTOP_HOST = re.compile(r"desktop")
|
||||
DESKTOP_WORK = re.compile(r"\b(?:pnpm|ci:gate|verify\.sh|vitest|playwright)\b|\bnode\s+scripts/")
|
||||
|
||||
@@ -106,6 +106,19 @@ class BrokenCopyTest(unittest.TestCase):
|
||||
self.append("docs/work/README.md", "\n[x](missing.md)\n")
|
||||
self.assertIn("broken relative link 'missing.md'", self.run_checker().stderr)
|
||||
|
||||
def test_a_folder_rule_book_needs_its_import_beside_it_and_no_history(self) -> None:
|
||||
guide = self.root / "src/adapters/AGENTS.md"
|
||||
guide.parent.mkdir(parents=True)
|
||||
guide.write_text("# AGENTS.md\n\n- 규칙\n", encoding="utf-8")
|
||||
self.assertIn("src/adapters/CLAUDE.md: missing", self.run_checker().stderr)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
|
||||
self.assertEqual(self.run_checker().returncode, 0)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n- 둘째 규칙\n", encoding="utf-8")
|
||||
self.assertIn("must be exactly '@AGENTS.md'", self.run_checker().stderr)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
|
||||
guide.write_text("# AGENTS.md\n\n- 1105/12-04처럼 고친다\n", encoding="utf-8")
|
||||
self.assertIn("src/adapters/AGENTS.md:3:", self.run_checker().stderr)
|
||||
|
||||
def test_a_missing_reference_fails(self) -> None:
|
||||
(self.root / "docs/work/reference/testing.md").unlink()
|
||||
self.assertIn("docs/work/reference/testing.md: missing", self.run_checker().stderr)
|
||||
|
||||
@@ -57,6 +57,28 @@ class RootInstructionsTest(unittest.TestCase):
|
||||
self.assertNotIn("서브에이전트를 병렬로", text, path)
|
||||
|
||||
|
||||
class LayerGuideTest(unittest.TestCase):
|
||||
"""Every top-level src/ folder has its rule book, readable by any agent, and Claude Code imports it."""
|
||||
|
||||
def test_every_layer_folder_has_a_rule_book_and_the_import_beside_it(self) -> None:
|
||||
folders = sorted(path for path in (REPO / "src").iterdir() if path.is_dir() and not path.name.startswith("."))
|
||||
self.assertTrue(folders)
|
||||
for folder in folders:
|
||||
guide = folder / "AGENTS.md"
|
||||
self.assertTrue(guide.is_file(), f"{folder.name}: no AGENTS.md")
|
||||
self.assertTrue(guide.read_text(encoding="utf-8").startswith(f"# AGENTS.md — `src/{folder.name}`"))
|
||||
self.assertEqual((folder / "CLAUDE.md").read_text(encoding="utf-8"), "@AGENTS.md\n", folder.name)
|
||||
|
||||
def test_path_rules_point_at_the_folder_books_instead_of_copying_them(self) -> None:
|
||||
for rule, book in (("adapters", "src/adapters/AGENTS.md"), ("features", "src/features/AGENTS.md")):
|
||||
self.assertIn(f"`{book}`", (CLAUDE / "rules" / f"{rule}.md").read_text(encoding="utf-8"))
|
||||
|
||||
def test_the_owner_forms_exist_and_the_map_points_at_them(self) -> None:
|
||||
for form in ("docs/vision.md", "docs/problem-statement.md"):
|
||||
self.assertIn("(채울 것", (REPO / form).read_text(encoding="utf-8"), form)
|
||||
self.assertIn(f"`{form}`", (REPO / "AGENTS.md").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
class SubagentTest(unittest.TestCase):
|
||||
AGENTS = CLAUDE / "agents"
|
||||
|
||||
|
||||
@@ -245,7 +245,8 @@ class TurnEndNudgeTest(RepositoryTestCase):
|
||||
|
||||
def test_files_the_laptop_checks_do_not_need_the_desktop(self) -> None:
|
||||
for path in (".claude/rules/x.md", "scripts/hooks/hooks.py", "scripts/tests/test_x.py", "CLAUDE.md",
|
||||
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py"):
|
||||
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py", "src/adapters/AGENTS.md",
|
||||
"src/features/CLAUDE.md"):
|
||||
self.repo.write(path, "x\n")
|
||||
run_event("post-edit", self.repo.payload(path))
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -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`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
Reference in New Issue
Block a user