Files
clean-architecture-frontend…/scripts/tests/test_check_work_docs.py
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

129 lines
6.1 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_folder_rule_book_needs_its_import_beside_it_and_no_history(self) -> None:
guide = self.root / "src/adapters/AGENTS.md"
guide.parent.mkdir(parents=True)
guide.write_text("# AGENTS.md\n\n- 규칙\n", encoding="utf-8")
self.assertIn("src/adapters/CLAUDE.md: missing", self.run_checker().stderr)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
self.assertEqual(self.run_checker().returncode, 0)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n- 둘째 규칙\n", encoding="utf-8")
self.assertIn("must be exactly '@AGENTS.md'", self.run_checker().stderr)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
guide.write_text("# AGENTS.md\n\n- 1105/12-04처럼 고친다\n", encoding="utf-8")
self.assertIn("src/adapters/AGENTS.md:3:", 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()