Files
clean-architecture-backend-…/scripts/tests/test_check_work_docs.py
T
DongHyeonka 7140f27948 docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).

- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
  규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
  지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
  지킬 규칙 몇 줄을 남겼다.
  - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
    멱등성(KEYED) → 337줄에서 190줄.
  - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
    TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
    194줄.
  - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
  TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
  찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
  AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
  가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
  자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
  코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
  맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
  `lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
  PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.

위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.

검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.

BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
2026-11-07 22:33:08 +09:00

150 lines
6.8 KiB
Python

"""scripts/check-work-docs.py의 시험. 고장 낸 지침 배치에서 실패하고, 맞는 배치에서 통과하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import tempfile
import unittest
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_work_docs", SCRIPTS / "check-work-docs.py")
check_work_docs = importlib.util.module_from_spec(_spec)
sys.modules["check_work_docs"] = check_work_docs
_spec.loader.exec_module(check_work_docs)
PLAYBOOK = "".join(f"## {heading}\n\n- 한 줄.\n\n" for heading in check_work_docs.SKELETON)
class Repository:
"""A throwaway repository with the smallest work manual the checker accepts."""
def __init__(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.root = Path(self._directory.name)
self.write("AGENTS.md", "# 정본\n\n- 지도 한 줄.\n")
self.write("CLAUDE.md", "@AGENTS.md\n\n- Claude 전용 한 줄.\n")
self.write("docs/work/README.md", "# 작업 매뉴얼\n")
self.write("docs/work/evidence.md", "# 근거\n\n`1101/05-18`은 여기에 둔다.\n")
for name in check_work_docs.PLAYBOOKS:
self.write(f"docs/work/{name}", f"# {name}\n\n{PLAYBOOK}")
for name in check_work_docs.REFERENCES:
self.write(f"docs/work/{name}", "# 참고\n")
self.write("src/app/AGENTS.md", "# app\n\n- 지역 규칙.\n")
self.write("src/app/CLAUDE.md", "@AGENTS.md\n")
self.saved = {name: getattr(check_work_docs, name) for name in ("REPO_ROOT", "MAP", "CLAUDE_ENTRY", "WORK", "README")}
check_work_docs.REPO_ROOT = self.root
check_work_docs.MAP = self.root / "AGENTS.md"
check_work_docs.CLAUDE_ENTRY = self.root / "CLAUDE.md"
check_work_docs.WORK = self.root / "docs/work"
check_work_docs.README = check_work_docs.WORK / "README.md"
def write(self, path: str, text: str) -> None:
target = self.root / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text, encoding="utf-8")
def run(self) -> tuple[int, str]:
out, err = io.StringIO(), io.StringIO()
argv = sys.argv
sys.argv = ["check-work-docs.py"]
try:
with redirect_stdout(out), redirect_stderr(err):
code = check_work_docs.main()
finally:
sys.argv = argv
return code, err.getvalue()
def close(self) -> None:
for name, value in self.saved.items():
setattr(check_work_docs, name, value)
self._directory.cleanup()
class CheckWorkDocsTest(unittest.TestCase):
def setUp(self) -> None:
self.repo = Repository()
self.addCleanup(self.repo.close)
def assertFailsWith(self, fragment: str) -> None:
code, err = self.repo.run()
self.assertEqual(code, 1, err)
self.assertIn(fragment, err)
def test_the_smallest_valid_manual_passes(self) -> None:
self.assertEqual(self.repo.run(), (0, ""))
def test_a_map_over_forty_lines_fails(self) -> None:
self.repo.write("AGENTS.md", "# 정본\n" + "- 줄.\n" * 40)
self.assertFailsWith("AGENTS.md: 41 lines, limit 40")
def test_a_claude_entry_over_ten_lines_fails(self) -> None:
self.repo.write("CLAUDE.md", "@AGENTS.md\n" + "- 줄.\n" * 10)
self.assertFailsWith("CLAUDE.md: 11 lines, limit 10")
def test_a_claude_entry_that_does_not_import_the_map_fails(self) -> None:
self.repo.write("CLAUDE.md", "# 지도\n\n@AGENTS.md\n")
self.assertFailsWith("CLAUDE.md: the first line must be '@AGENTS.md'")
def test_the_entry_path_counts_the_map_the_claude_entry_the_readme_and_one_playbook(self) -> None:
# Each file's own limit keeps the sum under ENTRY_PATH_LIMIT today, so lower it to see the sum.
lines = sum(len((self.repo.root / name).read_text(encoding="utf-8").splitlines())
for name in ("AGENTS.md", "CLAUDE.md", "docs/work/README.md", "docs/work/improve.md"))
original = check_work_docs.ENTRY_PATH_LIMIT
check_work_docs.ENTRY_PATH_LIMIT = lines - 1
self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original)
self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines")
def test_a_folder_rule_book_over_two_hundred_lines_fails(self) -> None:
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 200)
self.assertFailsWith("src/app/AGENTS.md: 201 lines, limit 200")
def test_a_folder_rule_book_of_two_hundred_lines_passes(self) -> None:
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 199)
self.assertEqual(self.repo.run(), (0, ""))
def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None:
self.repo.write("src/web/AGENTS.md", "# web\n")
self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'")
def test_a_folder_claude_file_that_holds_rules_fails(self) -> None:
self.repo.write("src/app/CLAUDE.md", "@AGENTS.md\n\n- 여기에도 규칙을 쓴다.\n")
self.assertFailsWith("src/app/CLAUDE.md: must be exactly '@AGENTS.md'")
def test_a_folder_claude_file_without_a_rule_book_fails(self) -> None:
self.repo.write("src/old/CLAUDE.md", "@AGENTS.md\n")
self.assertFailsWith("src/old/CLAUDE.md: imports src/old/AGENTS.md, which does not exist")
def test_build_output_is_not_a_folder_rule_book(self) -> None:
self.repo.write("src/app/build/tmp/AGENTS.md", "# 복사본\n")
self.assertEqual(self.repo.run()[0], 0)
def test_a_history_id_in_a_folder_rule_book_fails(self) -> None:
self.repo.write("src/app/AGENTS.md", "# app\n\n- 리뷰 05-18에서 정했다.\n")
self.assertFailsWith("src/app/AGENTS.md:3")
def test_a_history_id_in_a_claude_rule_skill_or_agent_fails(self) -> None:
for path in (".claude/rules/x.md", ".claude/skills/x/SKILL.md", ".claude/agents/x.md"):
with self.subTest(path=path):
self.repo.write(path, "# 규칙\n\n- RR-03-03에서 고쳤다.\n")
self.assertFailsWith(f"{path}:3")
(self.repo.root / path).unlink()
def test_local_claude_state_is_not_checked(self) -> None:
self.repo.write(".claude/worktrees/other/AGENTS.md", "# 다른 worktree\n\n- 리뷰 05-18.\n")
self.assertEqual(self.repo.run()[0], 0)
def test_a_broken_link_in_a_folder_rule_book_fails(self) -> None:
self.repo.write("src/app/AGENTS.md", "# app\n\n[설계](README.md)\n")
self.assertFailsWith("src/app/AGENTS.md:3: broken relative link 'README.md'")
if __name__ == "__main__":
unittest.main()