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:
@@ -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`).
|
||||
@@ -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절, 보고 형식은 소유자 전역 설정이다.
|
||||
|
||||
Executable
+326
@@ -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())
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user