Claude Codeでドキュメントを「書く」から「維持する」へ——README・ADR・議事録・仕様書の完全自動化フロー

はじめに
生成：5種類のドキュメントをClaude Codeが作る
ドキュメント生成ルール
1. 議事録の自動生成（PM業務自動化）
同期維持：コード変更時にドキュメントを自動更新する
1. PostToolUse Hookでコミット時に更新
2. CI/CDパイプラインでのドキュメント更新
Docs Manager Agent：チーム全員が維持できる仕組み
ビフォーアフター
まとめ：今日からできること

はじめに

「READMEが3ヶ月前のままで、新メンバーがセットアップできない」——このセリフを言ったことのあるエンジニアは多いはずだ。

ドキュメントが古くなる原因は「書く時間がない」ではない。「ドキュメント作成と維持のワークフローが存在しない」ことにある。コードを変更するたびに手動でドキュメントを更新するフローは、どんなチームでも遅かれ早かれ機能しなくなる。

Claude Codeはドキュメントの生成だけでなく、コードの変更に連動した自動更新とチーム全員が使える仕組みへの展開まで担える。本記事では生成・同期維持・チーム展開の3段階で解説する。

生成：5種類のドキュメントをClaude Codeが作る

README.mdの自動生成

「このコードベースを読んで、以下を含むREADME.mdを生成して：
 - プロジェクト概要（1段落）
 - ローカル環境セットアップ手順
 - 環境変数一覧（.env.exampleから）
 - APIエンドポイント一覧
 - ディレクトリ構成の説明」

Claude Codeはコードベース全体を読んで実際のディレクトリ構成・依存関係・エンドポイントを把握した上でREADMEを生成する。「想像で書いたREADME」ではなく、コードから逆引きした正確な内容になる。

ADR（Architecture Decision Records）の自動生成

ADRは「なぜこのアーキテクチャ選択をしたか」を記録するドキュメントだ。書くべきだと分かっていても後回しになりやすい理由の一つは、「決断した直後なら覚えているのに、書くフォーマットが分からない」だ。

「今回の実装判断についてADRをdocs/adr/ADR-XXX-{タイトル}.mdとして生成して。
 以下の形式で：
 - Status（Accepted/Proposed）
 - Context（なぜこの決断が必要だったか）
 - Decision（何を決めたか）
 - Consequences（この決断の結果として何が変わるか）」

Claude Codeは実装したコードのコンテキストを持っているため、開発者がゼロから説明しなくてもコードから判断理由を抽出してADRに落とせる。「コードを書いたついでにADRも作る」が実現する。

FOR[yourname].md パターン：プロジェクト理解ドキュメント

CLAUDE.mdに以下を追記すると、新プロジェクト開始時に自動的に「人間が読むためのドキュメント」が生成される。

# CLAUDE.md

ドキュメント生成ルール
新しいプロジェクトで作業を開始したら、FORTEAM.mdを自動生成して：

技術アーキテクチャの説明（平易な言葉で）
コードベースの構造と各部分の接続関係
遭遇したバグと解決方法
将来的な落とし穴と回避方法
退屈な技術文書ではなく、読み物として魅力的に書くこと。

新メンバーのオンボーディングドキュメントとして機能する。「Claudeが理解した内容をそのまま人間向けに書き直す」という発想だ。

議事録の自動生成（PM業務自動化）

音声録音→文字起こし→構造化→Notionへの登録まで自動化した事例がある。

/transcribe-to-minutes スキル
録音ファイル（.m4a）
    ↓
Whisper API（ptransツール）で文字起こし
    ↓
Claude Codeが議事録形式に構造化
    ↓
Notion MCP ServerでNotionに自動登録

2ヶ月で16個のドキュメント関連スキルを構築し、MTG録音から5分以内に議事録が共有できる状態になったという実践報告がある（日本エンジニア実践報告）。

同期維持：コード変更時にドキュメントを自動更新する

生成だけでは「最初だけ正確なドキュメント」になってしまう。コードの変更に連動して更新される仕組みがあって初めて、ドキュメントは使えるものになる。

PostToolUse Hookでコミット時に更新

HooksはClaude Codeのツール実行前後に任意のシェルコマンドを自動実行する仕組みだ。詳しくはHooks・Skills・Scheduler自動化完全ガイドを参照してほしい。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git commit *)",
        "hooks": [
          {
            "type": "command",
            "command": "claude -p 'src/の変更内容を確認して、README.mdのAPIエンドポイント一覧を更新して。変更があった場合のみファイルを更新すること'"
          }
        ]
      }
    ]
  }
}

CI/CDパイプラインでのドキュメント更新

# .github/workflows/docs-sync.yml
name: Docs Sync
on:
  push:
    paths:
      - 'src/**/*.ts'
      - 'src/**/*.py'
jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Update API docs
        run: |
          claude -p "src/の変更内容を確認してdocs/api.mdを最新の状態に更新して" \
            --allowedTools "Read,Write,Glob"
      - name: Commit updated docs
        run: |
          git add docs/
          git commit -m "docs: auto-update API documentation" || exit 0
          git push

`src/**/*.ts` が変更された場合のみドキュメント更新が走る。「ドキュメントを更新し忘れた」という状況がなくなる。

Docs Manager Agent：チーム全員が維持できる仕組み

個人がドキュメントを更新する運用には限界がある。Docs Manager Agentにコードとドキュメントの整合性を自律的に維持させる設計に移ると、話が変わってくる。

エージェント定義

単純に「全ドキュメントを更新して」と指示すると、変更のないドキュメントまで書き直されてしまう。このエージェントの肝は「変更が必要なドキュメントだけを選択的に更新する」判断ロジックだ。

---
name: docs-manager
description: コードベースの変更を検知し、ドキュメントの整合性を自律的に維持する
tools: Read, Write, Glob, Grep, Bash
model: sonnet
---

あなたはドキュメントの整合性を維持するエージェントです。

呼び出されたら以下を実行します： 
 `git diff HEAD~1..HEAD` で直近のコード変更を把握する
 変更されたファイルのパスとdiffを分析し、影響するドキュメントを判断する：
 
   - src/api/ の変更 → docs/api.md の更新が必要    - package.json の変更 → README.mdのセットアップ手順確認が必要    - src/models/ の変更 → データ仕様書・スキーマドキュメントの確認が必要  影響するドキュメントのみを対象に更新する（全ドキュメントを再生成しない）
 更新前後のdiffを含むサマリーを出力する
 
 禁止事項：  コードから確認できない情報を推測で記載しない
 ドキュメントの構造・スタイルを変更しない（内容のみ更新）
 変更のないドキュメントを更新しない

doc-map.mdでコードとドキュメントを対応付ける

# doc-map.md（コードとドキュメントの対応表）


コードの変更パス 更新すべきドキュメント


src/api/ docs/api.md
src/models/ docs/schema.md
package.json README.md（セットアップ手順）
.env.example README.md（環境変数一覧）

コードの変更パス	更新すべきドキュメント
src/api/	docs/api.md
src/models/	docs/schema.md
package.json	README.md（セットアップ手順）
.env.example	README.md（環境変数一覧）

新メンバーはこの表を見るだけで「どのコードを変えたらどのドキュメントを更新すべきか」が分かる。エージェントはこの表をガイドに自律的に更新対象を選択する。

Skillにまとめてチームに展開する

.claude/skills/docs-sync/
├── SKILL.md              # /docs-sync コマンドの定義
└── reference/
    ├── doc-map.md        # コードパスとドキュメントの対応表
    └── templates/        # ADR・API docsのテンプレート

プロジェクトリポジトリにチェックインすることで、全員が同じコマンドでドキュメントを最新化できる。

ビフォーアフター

Before（ドキュメント放置）

実装完了 → 「READMEも更新しなきゃ…」（後回し）→ 3ヶ月後「このREADMEの通りにやっても動かない」→ 新メンバーが自力でセットアップ方法を調査 → 「なぜこのアーキテクチャにしたか誰も知らない」

After（docs-manager agent + CI同期）

実装完了 → git commitのHookが自動でdocs-managerを起動 → コードの変更内容を確認してドキュメントを更新 → PRにドキュメント更新が自動で含まれる → 常に最新のREADME・APIドキュメントが維持される → 新メンバーが5分でセットアップ完了、ADRで「なぜこのアーキテクチャか」がすぐ分かる

まとめ：今日からできること

今すぐ（5分）: 現在のプロジェクトで「READMEを読んでセットアップ手順を最新化して」とClaude Codeに依頼する
今日中: CLAUDE.mdに「コミット時にAPIドキュメントを更新する」ルールを追記する
今週: docs-managerサブエージェントのYAMLを作成し、週1回のドキュメント棚卸しを自動化する
チーム展開: docs-sync Skillをプロジェクトリポジトリにチェックインして、チーム全員が同じドキュメント管理の仕組みを使える状態にする

「ドキュメントを書く時間がない」という問題は、「書く作業をなくす仕組み」を作ることで解決する。最初の一歩はREADMEの更新依頼だけで十分だ。