# Doc Sync

> 変更を終えて PR を出す前や、「ドキュメントを更新」「README が古くないか確認」「実装とドキュメントの乖離をチェック」等と言われたとき。変更差分から影響しうるドキュメント（README / docs/ / CLAUDE.md / .env.example 等）を洗い出し、実装との食い違いを点検して直す。

- Skill: `turntuptechnologies-ai/doc-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add turntuptechnologies-ai/doc-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/turntuptechnologies-ai/doc-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: turntuptechnologies-ai (https://skillmd.com/u/turntuptechnologies-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/turntuptechnologies-ai/doc-sync

---


# ドキュメント乖離チェック（doc-sync）

コード変更にドキュメントが追従できているかを点検し、ズレを直す。CLAUDE.md 規約の「チーム解散前チェック（ドキュメントの乖離/不足）」を手順化したもの。

## 手順

1. **変更内容を把握する** — `git diff <base>...HEAD --stat` と中身で、何が変わったかを掴む（追加/削除/改名されたファイル・関数・コマンド・依存・設定）。

2. **影響しうるドキュメントを特定する** — 下表の対応で当たりを付ける。

   | 変更の種類 | 追従すべきドキュメント |
   |---|---|
   | scripts / コマンド / Makefile・タスクの追加・変更 | README の使い方、CLAUDE.md の「言語・ツール」「コマンド体系」 |
   | 依存の追加・削除（package.json / pyproject 等） | README/CLAUDE.md の Stack・前提条件 |
   | 環境変数・設定キーの追加・変更 | `.env.example`、`config.example.*`、設定ドキュメント |
   | ディレクトリ・モジュールの追加・改名 | README の Layout、`docs/ARCHITECTURE.md`、CLAUDE.md の構成 |
   | CLI フラグ・サブコマンド・API エンドポイントの変更 | 使い方/リファレンス、`docs/` の該当ガイド |
   | 新機能・挙動変更 | README の概要・機能、関連 `docs/`、（あれば）CHANGELOG |
   | デプロイ手順・インフラの変更 | `docs/DEPLOY.md` 等 |

3. **乖離を点検する** — 特定したドキュメントを実際に開き、記載が現在の実装と一致するか確認する。古い手順・存在しないコマンド・消えたファイルへの参照・未記載の新機能を探す。

4. **対応する**
   - **軽微なズレ**（コマンド名・パス・1〜2行の追記）→ その場で最小差分で直す。
   - **大きな欠落**（新ガイドが必要・章ごと不足）→ 内容を Issue 化し、本筋の PR とは分けて対応する。
   - 直した内容は PR 本文の「変更点」に含める。

## 結果の報告フォーマット

必ずこの表の形で報告する（点検したが乖離なしのファイルも行として残す）:

```markdown
| 点検したドキュメント | 乖離 | 対応 |
|---|---|---|
| README.md（使い方） | `pnpm check` が scripts に無い | 修正済み（→ `pnpm lint`） |
| CLAUDE.md（コマンド体系） | なし | — |
| .env.example | 新設定 `RETENTION_DAYS` 未記載 | 修正済み |
| docs/DEPLOY.md | 手順の章ごと更新が必要 | Issue #NN 化 |
```

乖離ゼロの場合も「点検したファイル一覧＋乖離なし」を表で報告する。

## ルール・コツ

- **文体・言語・見出しの粒度はリポジトリの既存ドキュメントに合わせる。** 新しい流儀を持ち込まない。
- **実装を正とする。** ドキュメントに書いてあっても、コードと違えばコードに合わせて直す（仕様自体の誤りが疑われる場合は確認する）。
- 推測で書かない。確認できないコマンド・値は実際に実行/参照して裏を取る。
- README を新規に整える/構成から作り直すなら `write-readme` Skill を使う。
- `.env.example` は実値を書かない（→ no-secrets ルール）。
- このチェックは品質ゲートの一部。コードの lint/test は `pre-pr-checks`、PR 作成は `create-pr` と組み合わせる。

## 完了条件

以下を全て満たしたら完了。**満たせない項目があれば、黙って省略せず理由を報告する。**

- [ ] `git diff` で変更内容を実際に確認した（推測で判断していない）
- [ ] 対応表に基づき、影響しうるドキュメントを**実際に開いて**点検した（点検したファイル一覧を報告）
- [ ] 乖離の有無を明示的に報告した（**ゼロならゼロと報告**する）
- [ ] 軽微なズレは最小差分で修正、大きな欠落は Issue 化した
- [ ] 修正時、文体・言語はそのリポジトリの既存ドキュメントに合わせた

## 補足

- 社名・内部 URL・認証情報などの固有情報をドキュメントに足さない。