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