Files
clean-architecture-backend-…/scripts/check-work-docs.py
T
DongHyeonka b7d1310459 fix(scripts): 이력 검사가 앞말 없는 번호 목록·리뷰 영역·묶음 번호를 잡는다
문제: check-work-docs.py --history는 리뷰·라운드 낱말 바로 뒤의 NN-NN만
발견 번호로 본다. 그래서 앞말 없이 나열한 "(05-01, 04-01, 06-01)",
"리뷰 01 영역 5.2절", "sample P30 결정"을 놓친다. 2026-11-07 docs/manual
이력 걷어내기에서 검사가 찾은 16줄을 고친 뒤 docs-writing.md 9절대로
grep으로 다시 읽으니 이 꼴 3줄이 더 있었다.

고른 방법: 패턴 셋을 더한다.
- 쉼표+공백이나 가운뎃점으로 이은 NN-NN 둘 이상. 콜론 뒤 줄 범위
  ("Foo.java:10-12,20-24")와 공백 없는 쉼표 범위는 잡지 않는다
- "리뷰 NN 영역", "NN 영역 N.N절"
- 2026-09-25 리뷰 후속 묶음 번호 P10~P49와 "W3-P30" 꼴
버린 대안:
- 홀로 선 NN-NN 하나까지 잡기. 장 번호·범위 같은 보통 숫자가 걸린다
- P 뒤 두 자리를 모두 잡기. P95·P99 같은 백분위수가 걸린다

위험·한계: 검사는 여전히 아는 꼴만 잡는다. P1~P9 묶음 번호는 우선순위
P0~P3과 겹쳐 잡지 않는다. 문서가 자기 목록에 P10~P49 번호를 붙이면
이력이 아니어도 잡는다(docs/study/graphql-walkthrough.ko.md의 할 일
번호 P10·P11). 지금 검사 대상인 docs/work 본문과 docs/manual에는 그런
줄이 없다. 이 커밋만 있으면 --history docs/manual이 19줄, rc=1이다.
다음 커밋이 그 19줄을 걷어낸다. 기본 모드(docs/work 본문, 루트
CLAUDE.md)는 0줄 그대로다.

검증(desktop worktree, 다음 커밋까지 얹은 트리 8ff82a67과 같은 스크립트):
- 기준 커밋 73d39212의 docs/manual: 옛 스크립트 16줄, 새 스크립트 19줄.
  더 잡은 3줄은 03-placement.md:40·:54, 05-idempotency.md:93이다
- 오탐 시험 14줄: 보통 문장 8줄(p95·P99, 콜론 뒤 줄 범위, 날짜 쌍,
  홀로 선 번호, 장 번호)은 안 잡고 이력 6줄은 잡았다
- 노트북에서 docs/reviews 밖 *.md에 새 패턴을 돌려 걸린 65줄을 읽었다.
  위 할 일 번호 4줄 말고는 모두 실제 이력 번호였다
- 기본 모드 rc=0, 본문 이력 0줄
2026-11-07 00:24:58 +09:00

288 lines
11 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 `CLAUDE.md` (the map) plus `docs/work/`. 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 1101/05-01" 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`).
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
total limit, so a session reads the whole path instead of skimming it.
It also checks that every playbook keeps the shared nine-section skeleton, that the
"common mistakes" section stays short, and that relative links in the checked files resolve.
This lives outside Gradle on purpose: the build does not parse documents.
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
The --links form is for machines without lychee (the link checker the pull-request workflow runs).
The --history form applies the same history-ID patterns to documents outside docs/work/.
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
MAP = REPO_ROOT / "CLAUDE.md"
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/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 = 120
README_LIMIT = 80
PLAYBOOK_LIMIT = 150
ENTRY_PATH_LIMIT = 350
MISTAKES_LIMIT = 10
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 "RR6-01-07과" would otherwise slip through.
HISTORY_PATTERNS = [
("review ID with a date prefix (MMDD/...)",
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])/[\w-]", re.ASCII)),
("review round prefix (RR-, RR2-, ...)", re.compile(r"\bRR\d*-", re.ASCII)),
("fix bundle name (r2-05a, r9-a, r10-03)", re.compile(r"\br\d{1,2}-(?:\d{2}[a-z]?|[A-Za-z])\b", 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, with no folder date in front:
# "리뷰 02-01", "1라운드 06-01", "리뷰 README 13.2, 09-02", "review 2026-11-01 05-15". The number
# must stand alone, so a date such as 2026-11-01 is not a finding number by itself.
("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, 06-01)", "01-01·07-09". One
# bare NN-NN stays allowed, because a lone pair is often an ordinary range or chapter number.
# Line ranges after a colon ("Foo.java:10-12,20-24") are not findings.
("list of finding numbers (05-01, 04-01)",
re.compile(r"(?<![\w./:,-])\d{2}-\d{2}(?:, |·)\d{2}-\d{2}(?![\w-])", re.ASCII)),
("review area number (리뷰 01 영역, 01 영역 5.2절)",
re.compile(r"리뷰 ?\d{2} ?영역|(?<![\w.])\d{2} ?영역 \d+(?:\.\d+)*절", re.ASCII)),
# Review-followup fix bundles ran from P1 to P34. P50 and above are left to percentiles (P95).
("review-followup fix bundle (P30, W3-P30)", re.compile(r"\b(?:W\d-)?P[1-4]\d\b", re.ASCII)),
("round number in Korean (1라운드, 라운드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)),
("decision named by number only",
re.compile(r"결정 ?(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))|owner decision \d+", re.ASCII)),
("old manual decision number (M-3)", re.compile(r"\bM-\d+\b", re.ASCII)),
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", 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, 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), (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(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 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 history_checked_files() -> list[Path]:
files = [MAP]
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_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
hits = []
for path in files:
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
for label, pattern in HISTORY_PATTERNS:
match = pattern.search(line)
if match:
hits.append((path, number, label, match.group(0)))
break
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] + sorted(WORK.rglob("*.md")))
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_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())