diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..3169e26f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md — 프론트 템플릿의 정본 + +도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다. + +## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다 + +1. adapter 그룹 밖에서는 배럴(`src/adapters/*/index.ts`)로만 들어간다. 배럴이 공개 경계다. +2. adapter끼리 import하는 예외는 `.dependency-cruiser.json`의 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 만들지 않는다. 공용 로직은 `src/adapters/platform/`이나 `src/contracts/`에 둔다. +3. import 규칙의 정본은 `.dependency-cruiser.json`, 판정은 `check:architecture`다. dependency-cruiser CLI는 TypeScript 7을 못 읽어 쓰지 않는다. +4. 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다. +5. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말하지 않는다. + +## 지도 + +- 계층·import 방향과 최상위 `src/` 폴더의 역할은 `docs/architecture/layers.md`다. +- 새 기능은 `corepack pnpm create:feature `로 만들고 `docs/manual/` 순서로 채운다. +- 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다(설명 `docs/operations/ci-quality-gates.md`). +- adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다. +- 폴더를 가로지르는 규칙(테스트·문서·설정)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다. + +## 맡은 일 + +먼저 `docs/work/README.md`, 그다음 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링·성능 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 프로젝트 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다. + +## 검증 + +- 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다. +- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. +- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북). + +## 일하는 방식 + +- 커밋·push는 brief가 허용한 것만 자기 브랜치에 한다. main 병합·force push·PR 병합은 소유자가 한다. +- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다. +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`docs/work/delegate.md`). diff --git a/CLAUDE.md b/CLAUDE.md index 6c9a9ac2..5cc65596 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,26 +1,10 @@ -# CLAUDE.md +@AGENTS.md -## 리뷰 기준 (모든 리뷰에 적용) +## Claude Code에서만 -이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다. - -- 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다. -- 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 `미확인`이다. -- 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다. -- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다. -- 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다. - -### 이 repo의 리뷰 전제 - -- 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다. -- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. -- adapter끼리 import할 수 있는 예외는 `.dependency-cruiser.json`의 kernel 예외(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 제안하지 않는다. -- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다. - -### 전체 리뷰 절차 - -1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다. -2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`. -3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다. -4. 각 에이전트는 `docs/reviews/-maturity-review/NN-<영역>.md`에 결과를 쓴다. -5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. +- 권한·훅은 `.claude/settings.json`, 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. 편집 직후 훅은 노트북 정적 검사만 하고 알리기만 한다. +- 공통 훅·스킬(위험 명령 차단, 비밀 값 알림, 장부, `estimate`·`retro`·`techdebt`)은 플러그인 `harness@claude-harness`다. 비대화형(`claude -p`)은 자동 설치하지 않으니 이 폴더에서 한 번 돌린다: + `claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project` + `claude plugin install harness@claude-harness --scope project` +- 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트(읽기 전용)는 `.claude/agents/`다. +- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py new file mode 100755 index 00000000..5f6bb6f2 --- /dev/null +++ b/scripts/check-work-docs.py @@ -0,0 +1,326 @@ +#!/usr/bin/env python3 +"""Fail when the work manual stops being readable without history or grows past its size limits. + +The work manual is the root `AGENTS.md` (the map and the rules that must hold) plus `docs/work/`. A +Claude Code session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and +adds a few Claude-only lines. A session that has never seen this repository's history reads the map, +`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two +things break that, and both are mechanical: + +1. History IDs in the body. A sentence such as "fixed as in 1103/11-07" means nothing to a reader + who does not know that review. History belongs in `docs/work/evidence.md` and the two reference + files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The + same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md` + and the documents under `.claude/` (rules, skills, subagents). Review documents keep their IDs. +2. Length. Each entry file has a line limit and the entry path (map + root `CLAUDE.md` + README + + one playbook) has a total limit, so a session reads the whole path instead of skimming it. The + map limit is 40 lines (owner decision 2026-11-07: the root holds the rules, the map and the + router only). + +It also checks that every playbook keeps the shared nine-section skeleton, that the "common +mistakes" section stays short, that `CLAUDE.md` starts with the import, and that relative links in +the checked files resolve. The same layout and limits as the paired backend template's checker. + +Standard library only, so it runs on the laptop and in the edit hook (scripts/hooks/hooks.py, N2). +`verify:documentation` (FE-GATE-017) checks the paths, scripts and gate IDs these documents name. + + python3 scripts/check-work-docs.py + python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files + python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +MAP = REPO_ROOT / "AGENTS.md" +CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md" +IMPORT_LINE = "@AGENTS.md" +CLAUDE_FOLDERS = ("rules", "skills", "agents") +WORK = REPO_ROOT / "docs/work" +README = WORK / "README.md" + +PLAYBOOKS = [ + "new-feature.md", + "improve.md", + "research-design.md", + "docs-writing.md", + "operate.md", + "delegate.md", +] +REFERENCES = [ + "reference/gates.md", + "reference/review-criteria.md", + "reference/structure.md", + "reference/testing.md", + "reference/performance.md", + "reference/defect-patterns.md", + "reference/decisions.md", +] +EVIDENCE = "evidence.md" + +# Files that may name history, relative to docs/work/. Everything else must not. +HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"} + +MAP_LIMIT = 40 +CLAUDE_ENTRY_LIMIT = 15 +README_LIMIT = 80 +PLAYBOOK_LIMIT = 150 +ENTRY_PATH_LIMIT = 350 +MISTAKES_LIMIT = 10 + +SKELETON = [ + "1. 언제 쓰나", + "2. 받아야 할 것", + "3. 크기와 사고 순서", + "4. 절차", + "5. 완료 기준", + "6. 하지 말 것", + "7. 막혔을 때", + "8. 보고 형식", + "9. 자주 하는 실수", +] + +# Each pattern names a kind of history identifier. A match is a sentence that only a reader who +# knows the past can follow. re.ASCII keeps \b and \w to ASCII: Python counts Korean letters as +# word characters, so "1105/12-01과" would otherwise slip through. +HISTORY_PATTERNS = [ + ("review ID with a date prefix (MMDD/NN-MM)", + re.compile(r"(? str: + return path.relative_to(REPO_ROOT).as_posix() + + +def line_count(path: Path) -> int: + return len(path.read_text(encoding="utf-8").splitlines()) + + +def check_exists(errors: list[str]) -> bool: + expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE] + expected += [WORK / name for name in PLAYBOOKS + REFERENCES] + missing = [rel(path) for path in expected if not path.is_file()] + for name in missing: + errors.append(f"{name}: missing") + return not missing + + +def check_limits(errors: list[str], report: list[str]) -> None: + for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]: + lines = line_count(path) + report.append(f"{rel(path)}: {lines}/{limit}") + if lines > limit: + errors.append(f"{rel(path)}: {lines} lines, limit {limit}") + base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README) + for name in PLAYBOOKS: + path = WORK / name + lines = line_count(path) + entry = base + lines + report.append(f"{rel(path)}: {lines}/{PLAYBOOK_LIMIT}, entry path {entry}/{ENTRY_PATH_LIMIT}") + if lines > PLAYBOOK_LIMIT: + errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}") + if entry > ENTRY_PATH_LIMIT: + errors.append( + f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines," + f" limit {ENTRY_PATH_LIMIT}" + ) + + +def outside_code_blocks(lines: list[str]) -> list[str]: + """Blank out fenced code blocks, so an example such as a report template is not a section.""" + kept: list[str] = [] + fenced = False + for line in lines: + if line.lstrip().startswith("```"): + fenced = not fenced + kept.append("") + else: + kept.append("" if fenced else line) + return kept + + +def check_skeleton(errors: list[str]) -> None: + for name in PLAYBOOKS: + path = WORK / name + lines = outside_code_blocks(path.read_text(encoding="utf-8").splitlines()) + headings = [line[3:].strip() for line in lines if line.startswith("## ")] + if headings != SKELETON: + errors.append(f"{rel(path)}: sections must be exactly {SKELETON} in that order, found {headings}") + continue + start = lines.index("## " + SKELETON[-1]) + items = [line for line in lines[start + 1:] if re.match(r"^(?:[-*]|\d+\.) ", line)] + if len(items) > MISTAKES_LIMIT: + errors.append( + f"{rel(path)}: '{SKELETON[-1]}' has {len(items)} items, limit {MISTAKES_LIMIT}" + " (move one to a reference file or delete one)" + ) + + +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() + if not lines or lines[0].strip() != IMPORT_LINE: + errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'") + + +def claude_documents() -> list[Path]: + """The tracked Claude Code documents a session reads: path rules, skills, subagent definitions. + Only these folders: the rest of .claude/ is local state (worktrees, hook state, settings.local.json).""" + return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md")) + + +def history_checked_files() -> list[Path]: + files = [MAP, CLAUDE_ENTRY] + claude_documents() + for path in sorted(WORK.rglob("*.md")): + if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED: + files.append(path) + return files + + +def history_match(line: str, following: str) -> tuple[str, str] | None: + """The first history ID on this line, or one that a line break splits ("review\n1103/11-07").""" + for label, pattern in HISTORY_PATTERNS: + match = pattern.search(line) + if match: + return label, match.group(0) + if not following.strip(): + return None + joined = line.rstrip() + " " + following.strip() + for label, pattern in HISTORY_PATTERNS: + for match in pattern.finditer(joined): + if match.start() < len(line.rstrip()) < match.end(): + return label, match.group(0) + return None + + +def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]: + hits = [] + for path in files: + lines = path.read_text(encoding="utf-8").splitlines() + for number, line in enumerate(lines, start=1): + found = history_match(line, lines[number] if number < len(lines) else "") + if found: + hits.append((path, number, *found)) + return hits + + +def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]: + checked = 0 + broken = [] + for path in files: + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1): + for target in LINK.findall(line): + if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"): + continue + checked += 1 + if not (path.parent / target.split("#", 1)[0]).exists(): + broken.append((path, number, target)) + return checked, broken + + +def check_history(errors: list[str], report: list[str]) -> None: + hits = history_hits(history_checked_files()) + for path, number, label, text in hits: + errors.append( + f"{rel(path)}:{number}: {label} '{text}'" + " - write the content instead, and move the ID to docs/work/evidence.md" + ) + report.append(f"history ID lines in checked files: {len(hits)}") + + +def check_links(errors: list[str], report: list[str]) -> None: + checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents()) + for path, number, target in broken: + errors.append(f"{rel(path)}:{number}: broken relative link '{target}'") + report.append(f"relative links checked: {checked}") + + +def markdown_files(targets: list[str]) -> list[Path]: + files: list[Path] = [] + for target in targets: + path = (Path.cwd() / target).resolve() + files += sorted(path.rglob("*.md")) if path.is_dir() else [path] + return files + + +def links_only(targets: list[str]) -> int: + files = markdown_files(targets) + checked, broken = broken_links(files) + print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}") + for path, number, target in broken: + print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr) + return 1 if broken else 0 + + +def history_only(targets: list[str]) -> int: + files = markdown_files(targets) + hits = history_hits(files) + print(f"files: {len(files)}, lines with history IDs: {len(hits)}") + for path, number, label, text in hits: + print(f" {path}:{number}: {label} '{text}'", file=sys.stderr) + return 1 if hits else 0 + + +MODES = {"--links": links_only, "--history": history_only} + + +def main() -> int: + if sys.argv[1:2] and sys.argv[1] in MODES: + if len(sys.argv) < 3: + print(f"usage: check-work-docs.py {sys.argv[1]} ...", file=sys.stderr) + return 2 + return MODES[sys.argv[1]](sys.argv[2:]) + errors: list[str] = [] + report: list[str] = [] + if check_exists(errors): + check_limits(errors, report) + check_claude_entry(errors) + check_skeleton(errors) + check_history(errors, report) + check_links(errors, report) + for line in report: + print(line) + if errors: + print(f"\nFAILED: {len(errors)} problem(s)", file=sys.stderr) + for error in errors: + print(f" {error}", file=sys.stderr) + return 1 + print("\nOK") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py new file mode 100644 index 00000000..7173e77c --- /dev/null +++ b/scripts/tests/test_check_work_docs.py @@ -0,0 +1,115 @@ +"""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()