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
+38 -6
View File
@@ -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)
+1 -1
View File
@@ -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`은 막지 않는다.
+2 -1
View File
@@ -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/")
+13
View File
@@ -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)
+22
View File
@@ -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"
+2 -1
View File
@@ -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())