diff --git a/docs/README.md b/docs/README.md index 82879364..f399bcfd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -195,7 +195,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | -| `link` | 살아 있는 문서의 상대 링크(`[글](경로)`)가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | +| `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | | `style` | 살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 | - 하나만 돌리기: `python3 scripts/check-docs.py --only head`. diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 6fa6446f..d0b5893c 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -69,13 +69,13 @@ - 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew :resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다. - 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다. -**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): +**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 그 범위 밖의 지침 문서(루트 `AGENTS.md`·`CLAUDE.md`, 지역 규칙 `src/**/AGENTS.md`, `.claude/` 아래 문서)의 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 본다. `src/**/CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): ```bash -python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/CLAUDE.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') +python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') ``` -`--links docs`만 돌리면 `src/**/README.md`·`src/**/CLAUDE.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). +`--links docs`만 돌리면 `src/**/README.md`·`src/**/AGENTS.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index 96c55053..32dceaad 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -19,7 +19,8 @@ things break that, and both are mechanical: map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only). 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. +"common mistakes" section stays short, that every folder rule book src/**/AGENTS.md has a CLAUDE.md +beside it that only imports it, and that relative links in the checked files resolve. This lives outside Gradle on purpose: the build does not parse documents. @@ -214,6 +215,21 @@ def module_guides() -> list[Path]: ) +def check_guide_pairs(errors: list[str]) -> None: + """Every folder rule book src/**/AGENTS.md has a CLAUDE.md beside it that only imports it, so Claude + Code reads the same book when it opens a file there. A CLAUDE.md that holds rules is a second book.""" + for guide in module_guides(): + if not guide.with_name("CLAUDE.md").is_file(): + errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'") + for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md") + if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)): + lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()] + if lines != [IMPORT_LINE]: + errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it") + if not entry.with_name("AGENTS.md").is_file(): + errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist") + + def check_claude_entry(errors: list[str]) -> None: """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() @@ -334,6 +350,7 @@ def main() -> int: if check_exists(errors): check_limits(errors, report) check_claude_entry(errors) + check_guide_pairs(errors) check_skeleton(errors) check_history(errors, report) check_links(errors, report) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py new file mode 100644 index 00000000..f4ff5e88 --- /dev/null +++ b/scripts/tests/test_check_work_docs.py @@ -0,0 +1,141 @@ +"""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_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()