문서 lint
배포 배치 직전에 한 번 돌린다. 구조 검사(pnpm docs:validate)가 잡지 못하는 것만 본다.
가장 강한 모델로 실행한다. 규칙을 찾는 능력과 규칙을 따르는 능력은 별개다.
읽는 범위
전체를 읽지 않는다. 넓게 읽으면 방해 문서가 늘어 정확도가 떨어진다.
- 이번 배포에 걸린 코드 경로를
pnpm docs:related <경로…>로 넣어 라우팅된 문서를 얻는다. - 그 문서가 링크한 ADR과 그 영역의 active 계획서.
pnpm docs:validate가 검증일 90일 초과로 경고한 영구 문서.docs/findings.md의 열린 항목.
보는 것
- 문서와 코드의 불일치를 양방향으로. 코드에 있는데 문서에 없는 것(누락)과 문서에 있는데 코드에 없는 것(환각)을 따로 본다. 한쪽만 보면 절반을 놓친다.
- ADR 모순 후보. 같은 영역의 Accepted ADR 둘이 반대 결론인데 대체 관계가 없는 경우.
pnpm docs:links <ADR>로 대체 사슬을 확인한다. - 코드와 중복된 값 표. 코드에서 읽어 낼 수 있는 값이나 목록을 문서가 베껴 두었는가.
- 90일 넘은 보류 계획서. 접을지 재개할지를 묻는 항목으로 올린다.
- 14일 넘은 Proposed ADR. 판정이 밀려 있다.
- 가이드에 섞인 경험 기록. 「해 봤더니 안 됐다」류는
docs/flows/로 가야 한다. docs/operations/current-state.md의 만료된 행. 확인일이 오래된 줄은 성공이 아니라 미확인이다.
산출
docs/findings.md 에 항목을 더한다. 한 항목은 다섯 줄이다.
- 발견 2026-09-04 · docs/policies/xxx.md
주장: (문서가 뭐라고 하는지)
근거: (코드 경로나 ADR 번호)
제안: (무엇을 하면 되는지)
범위: (이번 배포에서 고칠지, 미룰지)
고치지 않는다. 해결은 그 일을 하는 PR 이 하고, 그 PR 이 항목을 지운다.
읽은 영구 문서의 검증일 을 오늘로 갱신한다. 실제로 코드와 대조한 문서만 갱신한다. 대조하지
않은 문서에 오늘 날짜를 찍으면 최신이라는 거짓 신호가 된다.
예산
찾은 것 셋 중 하나는 오탐이라고 보고 시작한다. LLM 단독 불일치 탐지의 정밀도는 0.6 안팎이다. 확신이 서지 않으면 항목에 그렇게 적는다.
보고서 첫 줄에 «열린 findings 수와 가장 오래된 항목의 나이» 를 적는다.
규칙을 더하고 뺄 때
이 목록에 항목을 더하려면 그 항목이 잡은 실제 사례를 대야 한다. 근거 없는 항목은 넣지 않는다.
같은 실패가 12개월 없고 pnpm docs:harness-eval 에서 도움이 되지 않으면 뺀다.