---
name: docs-sync
description: 코드·설정·프리셋 변경 뒤 문서를 현행화한다. "문서 현행화", "README 갱신", "문서 최신화" 요청 시, 그리고 동작·경로·버전·수치를 바꾼 PR 을 올리기 직전에 사용. 문서의 주장을 실제 코드·명령 출력·공식문서와 대조해 정정하고, 다국어 짝 파일을 함께 갱신한다.
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob, Edit, Write
---

# 문서 현행화 (docs-sync)

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

## 원칙

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

## 절차

### 1. 변경 범위 추출

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

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

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

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

```bash
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 이 되는데 **어떤 게이트에도 안 걸린다.**

```bash
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. 게이트 실행

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

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

### 6. 보고

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

## 완료 기준

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

## Learned warnings

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