문서 현행화 (docs-sync)

문서 stale 은 자동 게이트에 걸리지 않는다. 링크 체커는 깨진 링크만 보고, 테스트 스위트는 문서를 읽지 않는다. 그래서 절차로 잡는다.

원칙

• 주장 단위로 검증한다. 문서를 "읽고 자연스러운지" 보는 게 아니라, 문장이 담은 검증 가능한 주장(경로·버전·수치·동작·기본값)을 뽑아 실제와 대조한다.
• 근거 없이 고치지 않는다. 파일:라인, 명령 출력, 공식문서 URL 중 하나가 있어야 한다. 확인 못 한 건 지우지 말고 "미검증"으로 명시한다 — 조용히 삭제하면 정보가 사라진다.
• 낙관적 서술 금지. 부분만 동작하면 "동작한다"고 쓰지 않는다. 되는 범위와 안 되는 범위를 나눠 쓴다.

절차

1. 변경 범위 추출

git log --oneline <last-doc-commit>..HEAD
git diff --stat <last-doc-commit>..HEAD

문서에 영향 주는 변경만 추린다 — CLI 플래그·기본값, 파일/디렉터리 경로, 생성 산출물, 버전, 임계값·수치, 게이트 동작, 지원 범위.

2. 문서의 검증 가능한 주장 수집

대상: README*, AGENTS.md, CLAUDE.md, 각 디렉터리 README.md, 스킬/에이전트 문서.

grep -rn '`[^`]*/`\|버전\|기본값\|default\|v[0-9]\+\.[0-9]' README*.md docs/ 2>/dev/null

특히 낡기 쉬운 것: 디렉터리 트리 블록(신규 산출물 누락), 버전 표기, "자동으로 ~한다" 류 동작 서술, 지원 매트릭스.

3. 주장별 대조

주장 유형	검증 방법
경로·파일 존재	ls / find — 실제 생성물 기준, 소스 트리 아님
CLI 플래그·기본값	<cmd> --help 실행. 문서 인용 금지, 출력이 근거
도구 버전	<cmd> --version 실측 + 실측 일자 병기
동작("자동 로드한다")	해당 도구 공식문서 URL. 없으면 "문서 근거 없음"으로 표기
수치·임계값	코드에서 grep 하거나 실제 산출물 측정(wc -c 등)
게이트 동작	실제로 실행해서 exit code 확인

4. 다국어·짝 파일 동시 갱신 (필수)

한쪽만 고치면 나머지가 stale 이 되는데 어떤 게이트에도 안 걸린다.

ls README*.md                       # 다국어 README 전량
ls presets/lang-en/ 2>/dev/null     # 언어 오버레이 존재 여부

• README 를 고쳤으면 존재하는 언어판 전부를 같은 커밋에서. 이 저장소 기준 README.md(영문) · README.ko.md · README.zh.md · README.ja.md 4종이다.
• .claude/** 베이스 파일을 고쳤으면 presets/lang-en/ 의 대응 파일도 같은 커밋에서.
• 번역이 아니라 같은 사실의 각 언어판 — 수치·버전·경로·표 구조는 동일하게 유지한다.
• 언어별로 원문이 달라 일괄 치환이 깨진다. 파일마다 grep -n 으로 교체 대상을 먼저 확인한다.

5. 게이트 실행

python3 .claude/scripts/knowledge_graph.py --check   # 깨진 링크 0 확인

문서만 고쳤어도 테스트 스위트를 한 번 돌린다 — 문서에 인용된 명령·경로가 테스트와 어긋나 있으면 여기서 드러난다.

6. 보고

정정한 주장을 이전 → 이후 + 근거 형태로 나열한다. "README 를 갱신했다" 같은 요약만 남기지 않는다. 확인 못 해 "미검증"으로 남긴 항목도 함께 보고한다.

완료 기준

• 문서의 모든 검증 가능한 주장에 근거가 있거나 "미검증" 표시가 있다
• 다국어·오버레이 짝 파일이 같은 커밋에 포함됐다
• 링크 체커 0 broken, 테스트 스위트 통과

Learned warnings

• 낡은 서술을 삭제로 처리하면 "왜 없어졌는지" 추적이 끊긴다 — 실측 일자와 함께 "미검증"으로 남기는 편이 낫다.
• 디렉터리 트리 블록이 가장 자주 낡는다. 신규 산출물이 추가된 커밋에서 트리를 안 고치면 링크 체커도 못 잡는다(링크가 아니라 코드블록 안 텍스트라서).