開発初期はきちんと書いた README.md や設計書が、気づけば現状と全然違う内容になっている。これはおそらく主要な開発者が経験する問題です。

原因はシンプルで、コードを変更するたびにドキュメントも更新する、という二重作業が続かないからです。機能追加でコードを書くのは楽しい。でも終わった後にドキュメントを開いて更新するのは、どうしても後回しになります。

Claude Codeを使った開発では、この問題をスラッシュコマンドで自動化することができます。

    アプローチの選択肢

    ドキュメント自動更新の方法は複数あります。代表的なものを挙げると：

    • GitHub Actions + Claude CodeなPRをトリガーにドキュメントを更新するCI/CDフロー
    • git hookなコミット前後に自動で処理を走らせる
    • 専用ツール（doc-tracer等）なコードとドキュメントの依存関係をグラフで管理
    • Claude Codeのカスタムスラッシュコマンドな手動で呼び出すシンプルな方式

    GitHub ActionsはCI/CDの整備が前提になるため、個人開発・クライアント案件には過剰です。
    git hookは設定ミスで開発フローが詰まるリスクがあります。
    doc-tracerのような専用ツールは全ドキュメントにメタデータを埋め込む準備コストが高い。

    個人開発・小〜中規模プロジェクトに最も現実的なのが、Claude Codeのカスタムスラッシュコマンドです。設定ファイル1つ、追加のツールなし、今すぐ使い始められます。

    カスタムスラッシュコマンドとは

    Claude Codeでは .claude/skills/ ディレクトリにサブディレクトリと SKILL.md を置くことで、独自のスラッシュコマンドを定義できます。

    Claude Code v2.1.89以降は、カスタムコマンドの保存場所が変更されました。

    バージョン 保存場所
    〜v2.1.88 .claude/commands/docs-sync.md
    v2.1.89〜 .claude/skills/docs-sync/SKILL.md 
    プロジェクト/
└── .claude/
    └── skills/
        └── docs-sync/
            └── SKILL.md   ← これを作る

    このファイルに書いた内容が、/docs-sync というコマンドとしてClaude Codeで使えるようになります。

    全プロジェクトで使いたい場合は ~/.claude/skills/docs-sync/SKILL.md に置くことで、どのプロジェクトからでも使えます。

    docs-sync.md の実装

    以下が実際に使用しているコマンドです。

    ---
description: git差分を検出してdocsを自動更新
---

## 実行手順

### 1. 変更内容の確認

git diff origin/main...HEAD

### 2. ドキュメントの更新

変更内容を分析して、以下を必要に応じて更新すること：

- @docs/01_requirements.md    # 機能追加・削除があった場合
- @docs/02_architecture.md    # ファイル構成・モジュール構造が変わった場合
- @docs/04_database.md        # DBスキーマ・テーブル定義が変わった場合
- @docs/05_api.md             # APIエンドポイントが追加・変更された場合
- @docs/06_errors.md          # 新しいエラーパターンが追加された場合
- @docs/10_tasks.md           # 完了タスクに ✅ を付けるのみ（削除・追加は行わない）
- @README.md                  # セットアップ・使い方が変わった場合

**更新ルール：**
- 既存の構造・見出しは維持する
- 変更履歴セクションがあれば日付と変更内容を追記する
- 削除された機能の記述は削除する（打ち消し線にしない）
- 以下のファイルは絶対に変更しない：
  - docs/03_development-workflow.md
  - docs/07_setup.md
  - docs/08_design.md
  - docs/09_frameworks-guide.md

### 3. 出力形式

✅ ドキュメント同期完了

更新ファイル:
- docs/xx.md: [何を更新したか]

変更なし:
- docs/xx.md（変更対象なし）

    ポイント：更新対象と除外対象を明示する

    主要なドキュメントを自動更新させるのは危険です。ドキュメントの性質によって分類が必要になります。

    種別 対象例 方針
    コード連動型 要件定義、アーキテクチャ、API設計、DB設計 自動更新対象
    方針・仕様型 開発フロー、デザインシステム、フレームワーク 除外（自動書き換え不可）
    タスク管理型 ロードマップ、タスク一覧 完了マークのみ許可など制限付き

    特に「デザインシステム」「フレームワーク指定」のようなドキュメントは、Claudeに自由に更新させると意図しない変更が入ります。除外リストに明示しておくのが重要です。

    開発フローへの組み込み方

    このコマンドは、既存のタスクテンプレートのRecord & Commitフェーズに1行追加するだけで自然に使えます。

    **Task X.X.4: Record & Commit（記録・コミット）**

**ドキュメント同期**：
- /docs-sync   ← 追加

**開発日誌**：
- /devlog Task X.X: [機能名]

**ドキュメント更新**：
- @logs/CHANGELOG.md
- @logs/ERRORLOG.md
- @logs/PATTERNS.md

    コード実装が完了したら /docs-sync を呼んでドキュメントを同期し、その後でコミット・ログ記録という流れになります。

    精度を上げるコツ：ルールを育てる

    最初から完璧な出力は得られません。実際に動かしてみると：

    • 更新してほしくない場所が変更された
    • 特定のセクションが漏れた
    • 書き方がこれまでのドキュメントと合わない

    といったことが出てきます。このとき、チャットで指示を重ねるのではなく、docs-sync.md のルールセクションに追記するのが正しいアプローチです。

    例えば：

    **更新ルール（追記）：**
- `## 更新履歴` セクションは必ず末尾に置く
- バージョン番号は変更しない
- コードサンプルのコメントは日本語で統一する

    このルールファイル自体がプロジェクトの「ドキュメント更新仕様書」になっていきます。CLAUDE.mdと同様に、使いながら育てていく設計です。

    まとめ

    Claude Codeのカスタムスラッシュコマンドを使ったドキュメント自動同期の要点をまとめます。

    • ~/.claude/skills/docs-sync/SKILL.md を作るだけで使い始められる
    • git diff origin/main...HEAD で差分を取り、関連ドキュメントを更新させる
    • 方針・仕様系のドキュメントは除外リストに明示する
    • Record & Commitフェーズに /docs-sync を1行追加して習慣化する
    • 出力精度はルールを追記して育てる

    大規模なCI/CD整備や専用ツールの導入なしに、今すぐ試せる現実的なアプローチです。
    ドキュメントが常に最新であることは、Claudeへの指示精度を高めることにも直結するため、開発効率全体の底上げになります。

    関連記事

    Vibe Codingのワークフロー 実行編1 - Claude Code 開発指示の基本

    Vibe Codingのワークフロー 実行編1 - Claude Code 開発指示の基本 準備編で作成した設計書をもとに、Claude Code で効率的に開発を進めるための実践的なコツをまとめました。Explore → Plan → Code → Commit の4段階的アプローチを中心とした、ベストプラクティスです。1. 段階タスク開発アプロー...  続きを読む

    Claude CodeにSlash Commandsで、開発日誌を書いてもらう方法

    Claude CodeにSlash Commandsで、開発日誌を書いてもらう方法 Claude CodeのSlash Commandsを使って、開発の判断理由や試行錯誤の過程を含む詳細な開発日誌を自動生成する方法を解説。設定ファイルのテンプレートと実際の出力例も公開。  続きを読む