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:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user