qwreey
40a5daf694
사용자 제기 — doc-check.py가 정규식으로 결정론적 판정을 하는데 표기가 흔들리면 문제가 커지니, 정규식을 늘리기보다 "예상 가능 범위"를 컨벤션으로 좁히는 게 싸지 않냐. 실측해보니 날짜 표기는 이미 100% 균일해서 고칠 게 없었고(강제 장치 없이), 드리프트는 절 인용 쪽이었다 — WARN 86건 중 78건(91%)이 절 참조 불일치. 핵심은 그 78건이 코퍼스가 지저분한 게 아니라 **검사기가 못 읽는 것**이었다는 점이다. 이 코퍼스는 `**볼드**` 줄을 하위 절로 쓰는데 headings()가 `#`만 봤다. ## 동작 변화 (문서 정정으로만 보이지만 게이트가 바뀐다) - 절 참조 불일치가 **WARN → ERROR**. 이제 절 인용 오류가 커밋을 막는다. - 절 인식이 `#` 헤딩 + `**볼드**` 절로 확장. 단 볼드는 **빈 줄 다음이나 리스트 항목 머리**만 인정 — 문단이 줄바꿈되며 우연히 줄머리에 걸린 강조를 절로 오인하던 걸 커밋 전 감사가 잡아 조였다. - 인용 길이 상한 60→160자. 60자를 넘으면 매칭 자체가 안 걸려 검사에서 **조용히** 빠져나갔음(위양성보다 나쁜 구멍). - 비교를 공백 무시로(줄바꿈 인용 대응), 선두 장식·상태/날짜 태그 정규화, `initreq/` 대상 인용은 절 검사 면제(읽기 전용 외부 원본). ## 규약 `conventions.md`에 "문서 표기 규약" 절 신설 — 절 인용 규약(의역 금지, 헤딩은 부분문자열/볼드는 앞부분일치, 태그로 닫히는 볼드 캐비엇, blockquote 함정), 세션은 산문 서수 말고 파일 ID로 지칭. 날짜 마커 라벨 어휘 닫기는 사용자 판단 으로 기각(기계 검사 대상이 아니라 읽는 쪽 판단 재료). ## 결과 절 참조 불일치 78 → 0. 36건은 검사기 수정으로 사라졌고(애초에 위양성), 42건은 인용을 실제 절 제목으로 손으로 고쳤다. 마지막 15건은 서브에이전트 3개에 병렬 위임해 추적 — **설계 서술이 유실된 건은 0건**, 대부분 코드 주석·본문 산문· 주제명처럼 애초에 절이 아닌 걸 절로 인용해온 것이었다. 부수로 드러나 같이 고친 것: onchange-plan이 9차 분할 때 일부러 안 옮긴 절을 잘못된 파일로 가리키던 것, brand-plan이 이미 이행된 정정을 "정정 대상"이라 부르던 것, ROADMAP의 blockquote가 인용 줄바꿈 때문에 깨져 있던 것, pre-implementation-audit의 해소된 항목이 "아직 안 고침" 절에 남아 있던 것 (사용자 결정으로 "이미 고침"으로 이동). 커밋 전 감사 4라운드(에이전트 8개)를 돌렸고, 발견 추이는 2→2→1→0이다. 매 라운드 발견이 "직전 라운드 수정이 만든 새 결함"이었던 게 특징 — 규약을 세우는 커밋이 그 규약의 첫 위반자가 된다는 걸 실측으로 확인했다. 상세는 .claude/session/2026-08-16-03-doc-check-section-convention.md. 부수: __pycache__를 .gitignore에 추가하고 추적 해제(32e9db0에 실수로 딸려 들어가 있었음). quad-doc-auditor에 작업 트리를 바꾸는 git 명령 금지 규약 추가 — 감사자가 git stash를 걸어 메인 세션 스테이지가 반복적으로 풀렸다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zk7XHkSfiBfdPLZUQHdZf
3.1 KiB
| name | description | metadata | ||
|---|---|---|---|---|
| feedback-self-referential-counts | 문서가 자기 자신의 줄 수/개수를 본문에 하드코딩하면 그 문서를 쓴 커밋 시점부터 이미 틀려 있는 경우가 실제로 반복됨 — 감사 시 최우선으로 확인할 것 |
|
quad .claude/ 코퍼스에서 어떤 문서가 자기 자신의 줄 수나 자기 자신이
포함된 색인의 항목 개수를 본문에 숫자로 적어두면(예: "CLAUDE.md는
39줄짜리 진입점", "session-summary.md는 1231줄", "세션별 요약 91개"),
이런 숫자는 그 문서를 커밋한 바로 그 시점부터 이미 틀려 있는 경우가
실제로 확인됨(2026-08-16 CLAUDE.md 4분할 커밋 8aeec76에서: 커밋 당시
CLAUDE.md 실제 43줄인데 "39줄"이라 적고, session-summary.md 실제 1276줄인데
"1231줄"이라 적고, session/ 실제 92개인데 "91개"라 적음 — 전부 3곳 이상에
중복 서술돼 있었음).
Why: 이런 숫자를 계산하는 시점(사람이 헤더 문구를 쓰는 시점)과 그
숫자가 설명하는 파일이 최종 커밋되는 시점 사이에 다른 편집(체크리스트
항목 추가, 배너 삽입 등)이 끼어들기 쉬움 — 자기 자신을 설명하는 숫자는
구조적으로 닭-달걀 문제라 사람이 아무리 조심해도 어긋난다.
conventions.md의 "개수·목록·상태는 소스를 하나만 둘 것" 원칙이 일반적으로는
"여러 문서에 같은 값을 반복 적지 말 것"을 말하지만, 이 변형(자기 자신을
설명하는 숫자)은 그 원칙조차 지켜도(값이 파일들 사이에 일치해도) 실제
파일 상태와는 다를 수 있다는 게 요점 — 일치 여부가 아니라 애초에
하드코딩하지 말아야 함.
How to apply: 감사 라운드에서 "이 문서가 N줄이다"/"이 폴더에 N개
있다" 류 서술을 보면, wc -l/ls | wc -l 등으로 실측 대조를 최우선
순위로 돌릴 것 — doc-check.py는 이 클래스를 못 잡음(정규식이 숫자
드리프트를 모름). 발견 시 fix 제안은 "숫자를 최신값으로 갱신"이 아니라
**"숫자 자체를 서술에서 빼고 정성적 표현으로 대체"**할 것 — 갱신은
다음 편집에서 또 깨짐(같은 실수의 재발), 삭제만이 구조적으로 안전.
변형(2026-08-16 재확인): 자기 자신이 아니라 다른(계속 자라는)
폴더를 가리키는 카운트도 같은 클래스임 — 예:
audit/luau-test-first-run-2026-08-13.md가 "재실측 전문(스파이크 44개):
audit/type-recursion-issue/"라고 적어둔 것. 같은 라운드에 다른 5곳
(typing-limits.md/README.md/STATUS.md/REPORT.md 자기 자신 등)에서
이 "44개"를 정확히 이 이유로 지웠는데 이 파일 하나만 놓쳤고, 실제 폴더는
그새 48개로 자라 있었음(ls spikes/ | wc -l로 확인). 감사 시 절차:
같은 라운드 diff에서 특정 하드코드 숫자를 여러 곳에서 지운 패턴을 보면,
그 숫자 문자열로 코퍼스 전체를 다시 grep해서 빠진 인스턴스가 없는지
확인할 것(archive/에 남은 동일 숫자는 스코프 밖이니 제외).