Files
clean-architecture-frontend…/scripts/tests/test_check_work_docs.py
T
DongHyeonka 6e8cc963ec docs(agents): 루트 AGENTS.md를 정본으로 두고 CLAUDE.md가 가져온다
루트에는 리뷰 기준만 담은 CLAUDE.md(26줄)가 있었다. 꼭 지킬 경계 규칙,
지도, 검증 진입점, 맡은 일 라우터가 없었고, "서브에이전트를 병렬로"는
소유자 결정(2026-11-07)과 맞지 않았다.

AGENTS.md(35줄)에 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 · 검증 ·
일하는 방식을 둔다. CLAUDE.md는 @AGENTS.md와 Claude 전용 줄(10줄)이다:
settings·훅, 하네스 플러그인과 비대화형 설치 두 명령, 규칙·스킬·
서브에이전트 위치, 리뷰 기준이 옮겨 간 곳, 소유자 환경. 리뷰 기준과
전체 리뷰 절차는 docs/work/reference/review-criteria.md와
docs/work/improve.md 4.1절로 옮겼다.

scripts/check-work-docs.py는 백엔드 검사기를 옮긴 것이다: 지도 40줄,
CLAUDE.md 15줄, README 80줄, playbook 150줄, 진입 경로 350줄, 9절 뼈대,
진입 문서의 이력 ID 0, 상대 링크. 이력 패턴에 이 repo의 꼴(1105 README,
P-43·O-12·D-14)을 더했다. 표준 라이브러리만 써서 노트북에서 돈다.

버린 대안: CLAUDE.md만 두기(다른 에이전트가 못 읽는다), 심볼릭 링크
(Claude 전용 줄을 둘 수 없다).

위험·한계: 지도 40줄은 자료와 백엔드에 맞춘 값이다. brief 상한 80보다
좁다.

검증: python3 scripts/check-work-docs.py rc=0,
python3 -m unittest scripts/tests/test_check_work_docs.py 통과.

Refs: design-docs harness/01-harness-design.md 4.3절·13절 Q1·Q2
2026-11-08 17:27:39 +09:00

116 lines
5.2 KiB
Python

"""scripts/check-work-docs.py의 시험. 이 repo의 작업 매뉴얼이 통과하고, 고장 낸 사본이 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
REPO = SCRIPTS.parent
CHECKER = SCRIPTS / "check-work-docs.py"
_spec = importlib.util.spec_from_file_location("check_work_docs", CHECKER)
check = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(check)
def history(line: str) -> tuple[str, str] | None:
return check.history_match(line, "")
class HistoryPatternTest(unittest.TestCase):
def test_this_repository_history_ids_are_caught(self) -> None:
for line in ("1103/11-07처럼 고쳤다", "1105 README 11.4절", "1103 조치의 고침", "결함 패턴 P-43",
"0925 라운드 D-14", "소유자 O-12", "4라운드 리뷰", "결정 D8을 따른다", "리뷰 12-03에서",
"(05-01, 04-01)", "커밋 ad3a071f"):
with self.subTest(line=line):
self.assertIsNotNone(history(line))
def test_ordinary_sentences_are_not_history(self) -> None:
for line in ("FE-GATE-013은 desktop에서 실패한다", "소유자 결정 2026-11-05", "P1과 P0~P3", "M0~M4, E0~E4",
"결정 대기로 남긴다", "Node 24.14.0", "결함 패턴 G13", "세 라운드를 더", "3라운드마다",
"`MMDD/NN-MM` 꼴", "초기 JS 206,848 B", "a11y·e2e", "9~15분"):
with self.subTest(line=line):
self.assertIsNone(history(line))
class RepositoryManualTest(unittest.TestCase):
def test_the_manual_in_this_repository_passes(self) -> None:
result = subprocess.run([sys.executable, str(CHECKER)], capture_output=True, text=True, timeout=30)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
class BrokenCopyTest(unittest.TestCase):
"""A copy of the manual with one thing broken at a time; the checker in the copy must fail on it."""
def setUp(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.addCleanup(self._directory.cleanup)
self.root = Path(self._directory.name)
for path in ("AGENTS.md", "CLAUDE.md", "docs/work", ".claude/rules", ".claude/skills", ".claude/agents"):
source = REPO / path
target = self.root / path
if not source.exists():
continue
if source.is_dir():
shutil.copytree(source, target)
else:
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy(source, target)
(self.root / "scripts").mkdir()
shutil.copy(CHECKER, self.root / "scripts/check-work-docs.py")
def run_checker(self) -> subprocess.CompletedProcess:
return subprocess.run([sys.executable, str(self.root / "scripts/check-work-docs.py")], capture_output=True,
text=True, timeout=30)
def append(self, path: str, text: str) -> None:
with (self.root / path).open("a", encoding="utf-8") as handle:
handle.write(text)
def test_the_copy_passes_before_it_is_broken(self) -> None:
self.assertEqual(self.run_checker().returncode, 0)
def test_a_long_map_fails(self) -> None:
self.append("AGENTS.md", "\n" * 10)
self.assertIn("AGENTS.md: ", self.run_checker().stderr)
def test_claude_md_must_start_with_the_import(self) -> None:
text = (self.root / "CLAUDE.md").read_text(encoding="utf-8")
(self.root / "CLAUDE.md").write_text("# CLAUDE.md\n" + text, encoding="utf-8")
self.assertIn("the first line must be '@AGENTS.md'", self.run_checker().stderr)
def test_a_history_id_in_a_playbook_or_rule_fails_but_not_in_the_evidence(self) -> None:
self.append("docs/work/evidence.md", "\n1103/11-07\n")
self.assertEqual(self.run_checker().returncode, 0)
for path in ("docs/work/improve.md", ".claude/rules/tests.md", "docs/work/reference/gates.md"):
with self.subTest(path=path):
original = (self.root / path).read_text(encoding="utf-8")
self.append(path, "\n고친 방법은 1105/12-04와 같다.\n")
self.assertIn(f"{path}:", self.run_checker().stderr)
(self.root / path).write_text(original, encoding="utf-8")
def test_a_playbook_without_the_skeleton_fails(self) -> None:
path = self.root / "docs/work/operate.md"
path.write_text(path.read_text(encoding="utf-8").replace("## 6. 하지 말 것", "## 6. 금지"), encoding="utf-8")
self.assertIn("sections must be exactly", self.run_checker().stderr)
def test_a_broken_relative_link_fails(self) -> None:
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_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)
if __name__ == "__main__":
unittest.main()