Files
clean-architecture-frontend…/scripts/check-work-docs.py
T
DongHyeonka f117a5af41 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건 통과.
2026-11-08 22:57:03 +09:00

359 lines
15 KiB
Python
Executable File

#!/usr/bin/env python3
"""Fail when the work manual stops being readable without history or grows past its size limits.
The work manual is the root `AGENTS.md` (the map and the rules that must hold) plus `docs/work/`. A
Claude Code session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and
adds a few Claude-only lines. A session that has never seen this repository's history reads the map,
`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two
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`,
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, 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.
python3 scripts/check-work-docs.py
python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files
python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
MAP = REPO_ROOT / "AGENTS.md"
CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md"
IMPORT_LINE = "@AGENTS.md"
CLAUDE_FOLDERS = ("rules", "skills", "agents")
WORK = REPO_ROOT / "docs/work"
README = WORK / "README.md"
PLAYBOOKS = [
"new-feature.md",
"improve.md",
"research-design.md",
"docs-writing.md",
"operate.md",
"delegate.md",
]
REFERENCES = [
"reference/gates.md",
"reference/review-criteria.md",
"reference/structure.md",
"reference/testing.md",
"reference/performance.md",
"reference/defect-patterns.md",
"reference/decisions.md",
]
EVIDENCE = "evidence.md"
# Files that may name history, relative to docs/work/. Everything else must not.
HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"}
MAP_LIMIT = 40
CLAUDE_ENTRY_LIMIT = 15
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. 언제 쓰나",
"2. 받아야 할 것",
"3. 크기와 사고 순서",
"4. 절차",
"5. 완료 기준",
"6. 하지 말 것",
"7. 막혔을 때",
"8. 보고 형식",
"9. 자주 하는 실수",
]
# Each pattern names a kind of history identifier. A match is a sentence that only a reader who
# knows the past can follow. re.ASCII keeps \b and \w to ASCII: Python counts Korean letters as
# word characters, so "1105/12-01과" would otherwise slip through.
HISTORY_PATTERNS = [
("review ID with a date prefix (MMDD/NN-MM)",
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])/[\w-]", re.ASCII)),
("review README named by its date (1105 README)",
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01]) (?:README|조치|리뷰)", re.ASCII)),
("review round folder name (round6)", re.compile(r"\bround\d+\b", re.ASCII)),
# A finding number written after the word for review or round: "리뷰 02-01", "review 12-03".
("finding number after a review or round word (리뷰 02-01)",
re.compile(r"(?:리뷰|라운드|(?<![A-Za-z])[Rr]eview)[^|()\n]{0,20}?(?<![\w./-])\d{2}-\d{2}(?![\w-])",
re.ASCII)),
# Finding numbers listed with no word in front: "(05-01, 04-01)". One bare NN-NN stays allowed,
# because a lone pair is often an ordinary range or chapter number.
("list of finding numbers (05-01, 04-01)",
re.compile(r"(?<![\w./:,-])\d{2}-\d{2}(?:, |·)\d{2}-\d{2}(?![\w-])", re.ASCII)),
# A count of rounds ("3라운드마다") is not a name for one past round.
("round number in Korean (4라운드, 라운드6)",
re.compile(r"(?<![\w.~-])\d{1,2} ?라운드(?! ?(?:동안|마다|씩|간))|라운드 ?\d{1,2}(?![\w.])", re.ASCII)),
("review README section number (리뷰 README 13절)", re.compile(r"리뷰 README \d", re.ASCII)),
# A decision named by its date ("owner decision 2026-11-06") is content plus a date, not a number.
("decision named by number only",
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
# The improvement manual's own numbers: decisions M-3, owner orders O-12, round defaults D-14, and
# the defect pattern catalogue P-43.
("old manual number (M-3, O-12, D-14, P-43)", re.compile(r"\b[MODP]-\d{1,2}\b", re.ASCII)),
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
("finding number with its chosen option (03-11 (b))",
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
]
LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)", re.ASCII)
def rel(path: Path) -> str:
return path.relative_to(REPO_ROOT).as_posix()
def line_count(path: Path) -> int:
return len(path.read_text(encoding="utf-8").splitlines())
def check_exists(errors: list[str]) -> bool:
expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE]
expected += [WORK / name for name in PLAYBOOKS + REFERENCES]
missing = [rel(path) for path in expected if not path.is_file()]
for name in missing:
errors.append(f"{name}: missing")
return not missing
def check_limits(errors: list[str], report: list[str]) -> None:
for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]:
lines = line_count(path)
report.append(f"{rel(path)}: {lines}/{limit}")
if lines > limit:
errors.append(f"{rel(path)}: {lines} lines, limit {limit}")
base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README)
for name in PLAYBOOKS:
path = WORK / name
lines = line_count(path)
entry = base + lines
report.append(f"{rel(path)}: {lines}/{PLAYBOOK_LIMIT}, entry path {entry}/{ENTRY_PATH_LIMIT}")
if lines > PLAYBOOK_LIMIT:
errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}")
if entry > ENTRY_PATH_LIMIT:
errors.append(
f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
f" limit {ENTRY_PATH_LIMIT}"
)
def outside_code_blocks(lines: list[str]) -> list[str]:
"""Blank out fenced code blocks, so an example such as a report template is not a section."""
kept: list[str] = []
fenced = False
for line in lines:
if line.lstrip().startswith("```"):
fenced = not fenced
kept.append("")
else:
kept.append("" if fenced else line)
return kept
def check_skeleton(errors: list[str]) -> None:
for name in PLAYBOOKS:
path = WORK / name
lines = outside_code_blocks(path.read_text(encoding="utf-8").splitlines())
headings = [line[3:].strip() for line in lines if line.startswith("## ")]
if headings != SKELETON:
errors.append(f"{rel(path)}: sections must be exactly {SKELETON} in that order, found {headings}")
continue
start = lines.index("## " + SKELETON[-1])
items = [line for line in lines[start + 1:] if re.match(r"^(?:[-*]|\d+\.) ", line)]
if len(items) > MISTAKES_LIMIT:
errors.append(
f"{rel(path)}: '{SKELETON[-1]}' has {len(items)} items, limit {MISTAKES_LIMIT}"
" (move one to a reference file or delete one)"
)
def check_claude_entry(errors: list[str]) -> None:
"""The root CLAUDE.md starts with the import, so a Claude Code session reads the map."""
lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines()
if not lines or lines[0].strip() != IMPORT_LINE:
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)."""
return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md"))
def history_checked_files() -> list[Path]:
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)
return files
def history_match(line: str, following: str) -> tuple[str, str] | None:
"""The first history ID on this line, or one that a line break splits ("review\n1103/11-07")."""
for label, pattern in HISTORY_PATTERNS:
match = pattern.search(line)
if match:
return label, match.group(0)
if not following.strip():
return None
joined = line.rstrip() + " " + following.strip()
for label, pattern in HISTORY_PATTERNS:
for match in pattern.finditer(joined):
if match.start() < len(line.rstrip()) < match.end():
return label, match.group(0)
return None
def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
hits = []
for path in files:
lines = path.read_text(encoding="utf-8").splitlines()
for number, line in enumerate(lines, start=1):
found = history_match(line, lines[number] if number < len(lines) else "")
if found:
hits.append((path, number, *found))
return hits
def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]:
checked = 0
broken = []
for path in files:
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
for target in LINK.findall(line):
if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"):
continue
checked += 1
if not (path.parent / target.split("#", 1)[0]).exists():
broken.append((path, number, target))
return checked, broken
def check_history(errors: list[str], report: list[str]) -> None:
hits = history_hits(history_checked_files())
for path, number, label, text in hits:
errors.append(
f"{rel(path)}:{number}: {label} '{text}'"
" - write the content instead, and move the ID to docs/work/evidence.md"
)
report.append(f"history ID lines in checked files: {len(hits)}")
def check_links(errors: list[str], report: list[str]) -> None:
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}")
def markdown_files(targets: list[str]) -> list[Path]:
files: list[Path] = []
for target in targets:
path = (Path.cwd() / target).resolve()
files += sorted(path.rglob("*.md")) if path.is_dir() else [path]
return files
def links_only(targets: list[str]) -> int:
files = markdown_files(targets)
checked, broken = broken_links(files)
print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}")
for path, number, target in broken:
print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr)
return 1 if broken else 0
def history_only(targets: list[str]) -> int:
files = markdown_files(targets)
hits = history_hits(files)
print(f"files: {len(files)}, lines with history IDs: {len(hits)}")
for path, number, label, text in hits:
print(f" {path}:{number}: {label} '{text}'", file=sys.stderr)
return 1 if hits else 0
MODES = {"--links": links_only, "--history": history_only}
def main() -> int:
if sys.argv[1:2] and sys.argv[1] in MODES:
if len(sys.argv) < 3:
print(f"usage: check-work-docs.py {sys.argv[1]} <file or directory>...", file=sys.stderr)
return 2
return MODES[sys.argv[1]](sys.argv[2:])
errors: list[str] = []
report: list[str] = []
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)
for line in report:
print(line)
if errors:
print(f"\nFAILED: {len(errors)} problem(s)", file=sys.stderr)
for error in errors:
print(f" {error}", file=sys.stderr)
return 1
print("\nOK")
return 0
if __name__ == "__main__":
sys.exit(main())