docs(agents): 루트 AGENTS.md를 정본으로 두고 CLAUDE.md가 가져온다

루트에는 리뷰 기준만 담은 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
This commit is contained in:
DongHyeonka
2026-11-08 17:27:39 +09:00
parent 3524d6b00b
commit 6e8cc963ec
4 changed files with 484 additions and 24 deletions
+35
View File
@@ -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 <id>`로 만들고 `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`).
+8 -24
View File
@@ -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/<YYYY-MM-DD>-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절, 보고 형식은 소유자 전역 설정이다.
+326
View File
@@ -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"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])/[\w-]", re.ASCII)),
("review README named by its date (1105 README)",
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01]) (?:README|조치|리뷰)", re.ASCII)),
("review round folder name (round6)", re.compile(r"\bround\d+\b", re.ASCII)),
# A finding number written after the word for review or round: "리뷰 02-01", "review 12-03".
("finding number after a review or round word (리뷰 02-01)",
re.compile(r"(?:리뷰|라운드|(?<![A-Za-z])[Rr]eview)[^|()\n]{0,20}?(?<![\w./-])\d{2}-\d{2}(?![\w-])",
re.ASCII)),
# Finding numbers listed with no word in front: "(05-01, 04-01)". One bare NN-NN stays allowed,
# because a lone pair is often an ordinary range or chapter number.
("list of finding numbers (05-01, 04-01)",
re.compile(r"(?<![\w./:,-])\d{2}-\d{2}(?:, |·)\d{2}-\d{2}(?![\w-])", re.ASCII)),
# A count of rounds ("3라운드마다") is not a name for one past round.
("round number in Korean (4라운드, 라운드6)",
re.compile(r"(?<![\w.~-])\d{1,2} ?라운드(?! ?(?:동안|마다|씩|간))|라운드 ?\d{1,2}(?![\w.])", re.ASCII)),
("review README section number (리뷰 README 13절)", re.compile(r"리뷰 README \d", re.ASCII)),
# A decision named by its date ("owner decision 2026-11-06") is content plus a date, not a number.
("decision named by number only",
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
# The improvement manual's own numbers: decisions M-3, owner orders O-12, round defaults D-14, and
# the defect pattern catalogue P-43.
("old manual number (M-3, O-12, D-14, P-43)", re.compile(r"\b[MODP]-\d{1,2}\b", re.ASCII)),
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
("finding number with its chosen option (03-11 (b))",
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
]
LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)", re.ASCII)
def rel(path: Path) -> 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 or directory>...", 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())
+115
View File
@@ -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()