루트에는 리뷰 기준만 담은 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
116 lines
5.2 KiB
Python
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()
|