docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
rc=0(3건)
This commit is contained in:
+51
-11
@@ -8,6 +8,9 @@ to finish the job from those alone. Two things break that, and both are mechanic
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" 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 rule book `AGENTS.md` and
|
||||
every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
|
||||
total limit, so a session reads the whole path instead of skimming it.
|
||||
|
||||
@@ -32,6 +35,7 @@ from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MAP = REPO_ROOT / "CLAUDE.md"
|
||||
RULE_BOOK = REPO_ROOT / "AGENTS.md"
|
||||
WORK = REPO_ROOT / "docs/work"
|
||||
README = WORK / "README.md"
|
||||
|
||||
@@ -100,10 +104,21 @@ HISTORY_PATTERNS = [
|
||||
("round number in Korean (1라운드, 라운드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+|[①-⑳])(?!\s*(?:개|건|가지|번째))|owner decision \d+", re.ASCII)),
|
||||
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
|
||||
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
|
||||
("old manual decision number (M-3)", re.compile(r"\bM-\d+\b", re.ASCII)),
|
||||
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
|
||||
# Module code reviews before 2026-11 numbered findings per module: MSG-023, BOOT-006, GQL-012.
|
||||
("module review finding (MSG-023, BOOT-006)",
|
||||
re.compile(r"(?<![\w-])(?:BOOT|MSG|JPA|MNG|GQL|NTF)-\d{3}\b", re.ASCII)),
|
||||
# The 2026-09-24 reviews and their follow-up named findings S6-#10a, X2-P1-5, S5-lead-4.
|
||||
("review follow-up finding (S6-#10a, X2-P1-5)",
|
||||
re.compile(r"\b[SX]\d-(?:#\d+|P\d-\d+|lead-\d+)", re.ASCII)),
|
||||
("finding number with its chosen option (03-11 (b))",
|
||||
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
|
||||
("review README section (review README §15)", re.compile(r"review README §", 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)),
|
||||
]
|
||||
|
||||
@@ -119,7 +134,7 @@ def line_count(path: Path) -> int:
|
||||
|
||||
|
||||
def check_exists(errors: list[str]) -> bool:
|
||||
expected = [MAP, README, WORK / EVIDENCE]
|
||||
expected = [MAP, RULE_BOOK, 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:
|
||||
@@ -180,23 +195,48 @@ def check_skeleton(errors: list[str]) -> None:
|
||||
)
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output."""
|
||||
skipped = {"build", ".gradle", "node_modules"}
|
||||
return sorted(
|
||||
path
|
||||
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
)
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP]
|
||||
files = [MAP, RULE_BOOK]
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
return files
|
||||
return files + module_guides()
|
||||
|
||||
|
||||
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\n2026-11-01 07-10")."""
|
||||
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:
|
||||
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
match = pattern.search(line)
|
||||
if match:
|
||||
hits.append((path, number, label, match.group(0)))
|
||||
break
|
||||
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
|
||||
|
||||
|
||||
@@ -225,7 +265,7 @@ def check_history(errors: list[str], report: list[str]) -> None:
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP] + sorted(WORK.rglob("*.md")))
|
||||
checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md")))
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
|
||||
Reference in New Issue
Block a user