feat(scripts): 작업 매뉴얼 검사와 리뷰 색인 대조 스크립트를 더한다
문제: 옛 개선 매뉴얼은 진입 경로가 717줄이었고 본문에 지난 리뷰 ID가 든 줄이 많아, 이력을 모르는 세션은 근거를 따라가지 못했다. 이것을 사람 눈으로만 지키면 다시 늘어난다. 리뷰 색인도 손으로 옮기다 발견 5건이 빠져 어떤 수정 묶음에도 배정되지 않은 적이 있다(원래 리뷰 124건이 색인에는 119건). 고른 방법: Gradle 밖 Python 스크립트 두 개를 둔다(2026-11-06 소유자 결정 D6: 이 repo는 문서를 파싱하는 Gradle 검사를 두지 않는다). - check-work-docs.py: 지도(CLAUDE.md)와 docs/work/의 분량 상한(지도 120, README 80, playbook 150, 진입 경로 350), playbook 9칸 뼈대, 「자주 하는 실수」 10줄, 본문 이력 ID 0(evidence.md와 reference/의 두 색인 문서는 제외), 상대 링크를 본다. --links, --history 모드로 다른 문서에도 쓴다. - check-review-index.py: 리뷰 폴더의 영역 문서 제목에 있는 발견 ID가 README 색인에 모두 있는지 본다. 범위(A~B)와 이어 쓰기(A·07)를 읽고, NN- 자리표시자를 잡는다. 정규식은 re.ASCII로 쓴다. Python의 \w·\b가 한글을 단어 문자로 봐서 "RR6-01-07과" 같은 표기를 놓쳤다. 버린 대안: document-contract Gradle lane(이 repo 원칙과 충돌), 검사 없이 cold-read 시험에서만 확인(매번 사람이 세야 한다). 위험·한계: check-work-docs.py가 보는 docs/work/는 다음 커밋에 들어온다. 이 커밋만으로는 "missing"으로 실패한다. 이력 ID 패턴은 이 repo가 쓴 형식만 안다 (MMDD/, RR<n>-, 묶음 이름, round<n>, 번호만 쓴 결정, 커밋 sha). 색인 검사는 "이름이 있나"만 보고 고쳤는지는 보지 않는다. 검증 - check-review-index.py docs/reviews/2026-11-01-maturity-review --index-heading "12. 발견 색인": 124/124, rc=0 - 같은 폴더를 사고 시점 34565130에서 꺼내 돌림: NN-10~NN-14 5건, rc=1 - check-review-index.py docs/reviews/2026-11-03-rereview: 157 중 135, rc=1 (README가 ID 대신 내용·건수로 적은 22건) - check-work-docs.py를 일부러 망가뜨린 사본 18가지에 돌림: 이력 ID 7형식, 분량 3종, 뼈대, 실수 줄 수, 깨진 링크, 빠진 파일은 rc=1, ID가 허용된 파일과 "결정 3개" 같은 개수 표현은 rc=0
This commit is contained in:
Executable
+269
@@ -0,0 +1,269 @@
|
||||
#!/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)),
|
||||
("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())
|
||||
Reference in New Issue
Block a user