Claude Code × ドキュメント as Code｜README・ADRをリポジトリで管理する運用
目次 クリックで開く
ソフトウェア開発において、コードと同じくらい重要なのがドキュメントです。しかし、多くの現場で「ドキュメントが最新のコードを反映していない」「なぜこの技術選定をしたのか、背景がわからない（ADRの不在）」といった問題、いわゆるドキュメントの形骸化が発生しています。これを解決する概念がDocs as Code（ドキュメントをコードとして扱う）ですが、手動での運用には限界がありました。
2025年以降、この課題に対する決定打となっているのが、Anthropic が提供する CLI 型コーディングエージェント「Claude Code」です。本記事では、Claude Code を主軸に据え、README や ADR（Architecture Decision Records）をリポジトリ内でいかに効率よく、かつ「腐らせずに」運用するかという実務フローを解説します。
Docs as Code の理想と現実を Claude Code が解決する
なぜ README と ADR は「腐る」のか
ドキュメントが更新されなくなる最大の理由は、「開発フローとドキュメント作成フローが分離していること」にあります。機能を実装し、テストを通し、デプロイする。この一連の流れの「外」にドキュメント作成がある限り、忙しいエンジニアにとってドキュメント更新は常に後回しにされます。
特に ADR（アーキテクチャ意思決定記録）は、決定の背景を記録する重要なものですが、後から書き起こすのは苦痛でしかありません。結果として、README には古いインストール手順が残り、ADR は最初の一件だけで止まることになります。
Claude Code がもたらす「ドキュメント更新の自動化」というパラダイム
Claude Code は、端末（ターミナル）上でリポジトリの全容を把握しながら、コードの変更と同時にドキュメントを修正できる AI エージェントです。単なるチャット AI と異なり、「リポジトリのファイルを読み、依存関係を理解し、実際にファイルを書き換える」能力を持っています。
例えば、あなたが新しい API エンドポイントを追加した際、Claude Code にこう命じるだけで済みます。「今の変更内容を反映して README.md を更新し、今回の技術選定の理由を 0005-use-redis-cache.md として ADR に追加して」。これだけで、コードとドキュメントの同期が完結します。
準備：Claude Code をリポジトリに導入する
インストールと認証のステップ
Claude Code は Node.js 環境で動作する CLI ツールです。以下の手順でセットアップを行います（詳細は Anthropic 公式ドキュメント を参照してください）。
- インストール:
npm install -g @anthropic-ai/claude-codeを実行。 - 認証:
claude authを実行し、Anthropic アカウントでログイン。 - 起動: リポジトリのルートディレクトリで
claudeコマンドを叩く。
これにより、Claude Code がリポジトリ内のファイルをスキャンし、編集可能な状態になります。
CLAUDE.md によるプロジェクト・ルールの定義
Claude Code を賢く使いこなすための鍵が、リポジトリのルートに配置する CLAUDE.md です。これは Claude Code 専用の「指示書」であり、以下のような項目を記述しておきます。
- ビルドコマンド（例：
npm run build） - テスト実行コマンド（例：
pytest） - コーディング規約（例：型定義を必須とする、ドキュメントは ADR 形式で残す等）
- ドキュメントの配置場所（例：
/docs/adr/*.md）
このファイルがあることで、Claude Code は「このプロジェクトではドキュメントをどう扱うべきか」を常に念頭に置いて動くようになります。
Claude Code によるドキュメント運用実務：README 編
既存コードを解析して「生きた README」を生成する
開発の初期段階や、長年放置されたプロジェクトで Claude Code を起動し、以下のプロンプトを入力してみてください。
「現在のディレクトリ構成と主要なソースコード、package.json を読み取って、プロジェクトの概要、セットアップ手順、主要な機能を網羅した README.md を生成、または既存のものを更新して。」
Claude Code は ls -R や cat 相当のスキルを駆使してリポジトリを探索し、実際のコードに基づいた正確なドキュメントを生成します。手動で書く際にありがちな「実は不要になった環境変数」などの記載漏れを、コードから逆引きして防ぐことができます。
開発フローと AGENTS.md によるドキュメント保守
さらに高度な運用として、AGENTS.md を活用します。ここには、Claude Code が「自律的なエージェント」として振る舞う際の役割を定義します。例えば、「あなたはドキュメントメンテナです。コードが変更された際、必ず README の整合性を確認し、修正が必要なら提案してください」といったロールを記述します。
これにより、機能実装の PR を作成する直前に claude "README を最新化して" と打つだけで、常にコードとドキュメントがペアで更新される習慣が定着します。
Claude Code によるドキュメント運用実務：ADR（技術決定記録）編
意思決定をその場で ADR に書き起こすワークフロー
ADR は、単に「何を作ったか」ではなく「なぜそれを選び、他を却下したか」を記録するものです。Claude Code を使えば、対話を通じて ADR を作成できます。
実務シーン：
開発者が Claude Code との対話で「データベースに MongoDB ではなく PostgreSQL を選ぼうと思う、理由は JSONB のクエリ性能が必要だから」と伝えます。その後、claude "今の議論を ADR として記録して。フォーマットは標準的な Markdown ADR で。" と指示します。
Claude Code は、会話の文脈からコンテクストを抽出し、docs/adr/0001-use-postgresql-for-jsonb.md のようなファイルを自動生成します。開発者は内容を確認して y を押すだけです。
過去の ADR との整合性チェック
プロジェクトが長くなると、「過去に決めたルールと矛盾する決定」をしてしまうことがあります。Claude Code はリポジトリ全体をインデックス化して読み取れるため、claude "今回の新しい認証フローの導入は、過去の ADR と矛盾していないか確認して" と質問することで、設計の整合性を保つことができます。
プルリクエスト（PR）運用と人間による承認フロー
Claude Code はファイルの編集だけでなく、ローカルでの実行や Git 操作もサポートしています。これを Docs as Code のフローに組み込むと、以下のような「準自動化」が実現します。
- 機能実装: 開発者が
claude "ユーザー登録機能を実装して"と指示。 - ドキュメント更新: 続けて
claude "関連する README と ADR を更新して"と指示。 - テスト確認:
claude "テストを実行して、通ることを確認して"。 - PR 作成:
claude "これらの変更を新ブランチ feat/user-registration にコミットし、PR を作成して"。
ここで重要なのは、Claude Code は「提案者」であり、人間が「承認者」であるという役割分担です。GitHub 上で PR を確認する際、コードの差分と一緒にドキュメントの差分が必ず含まれている状態を作れるため、レビューの質も向上します。
比較：従来のドキュメント管理 vs Claude Code 連携運用
ドキュメント管理の手法を比較すると、Claude Code を活用した Docs as Code の優位性が明確になります。
| 管理手法 | 更新のしやすさ | コードとの整合性 | 主なメリット | 主なデメリット |
|---|---|---|---|---|
| GitHub Wiki / Notion | 高（UIが容易） | 低（乖離しやすい） | 非エンジニアも編集可能 | Git の履歴と連動しない |
| 手動 Docs as Code | 中 | 中 | コードと同じ PR で管理可 | 更新の心理的ハードルが高い |
| Claude Code × Docs as Code | 最高（対話型） | 高（AIがスキャン） | 自動生成と同期が可能 | API コストが発生する |
ドキュメント種別 × Claude Code自動生成の設計方針 × 人間レビューポイント 早見表
前のセクションで「従来のドキュメント管理 vs Claude Code連携運用」の比較を示しましたが、実際のエンジニアリング組織では「README」「ADR（技術決定記録）」「API仕様書」「設計書」「変更履歴（CHANGELOG）」等の複数のドキュメント種別が存在します。それぞれの種別によって「Claude Codeが自動生成できる範囲」「人間が確認すべきポイント」「Git管理上の更新サイクル」が異なります。一律に「全部Claude Codeに任せる」設計にすると、APIの外部公開仕様等の精度が求められるドキュメントで問題が生じます。種別ごとの役割分担を整理することがDocs as Code運用の精度を上げる鍵です。
| ドキュメント種別 | Claude Code自動生成の設計方針 | 人間が必ず確認すべきレビューポイント | Git管理・更新サイクルの設計 |
|---|---|---|---|
| README （プロジェクト概要・セットアップ手順） |
CLAUDE.mdにプロジェクトの概要・技術スタック・セットアップコマンドを定義することで、Claude Codeが新規リポジトリ作成時にREADMEの初稿を自動生成できる。依存関係の変更（package.json・requirements.txt更新）をGit hookのトリガーにしてClaude CodeにREADMEの「インストール手順」セクションを自動更新させる設計が保守コストを下げる | ①セットアップ手順の実際の動作確認（コマンドが正しく実行できるか）②外部サービスのAPIキー・環境変数の記載有無（機密情報の漏洩チェック）③プロジェクトの目的・対象読者の表現が正確かどうか。「自動生成されたREADMEをそのままpushしない」ルールをチームに周知することが最重要 | 初回リポジトリ作成時に自動生成→マイルストーン（v1.0・v2.0等）のタイミングで人間がフル見直し→日常的な依存関係変更時は特定セクションのみ自動更新の3段階サイクルが管理コストと品質のバランスをとる実践的設計 |
| ADR（Architecture Decision Records） （技術決定の記録・根拠） |
ADRのフォーマット（Status/Context/Decision/Consequences）はCLAUDE.mdにテンプレートとして定義して、設計議論の結果をClaude Codeに渡すことで初稿を自動作成させる。「なぜこのアーキテクチャを選んだか」の文章化は議事録・Slackログ等を入力にClaude Codeに要約・整形させることで記録コストを大幅削減できる | ①Consequencesセクションの「トレードオフ・リスクの記述」が実態を反映しているか（Claude Codeは楽観的な記述になりがちなため修正が必要）②外部ライセンス・特許に関わる技術選定の記録（法務確認が必要な場合あり）③「誰が承認したか」の決定者情報が正確に記録されているか | ADRは「作成したら原則変更しない」のがベストプラクティス。既存ADRを覆す決定は新しいADRとして作成する運用ルールをCLAUDE.mdに記載することで、Claude Codeが既存ADRを誤って上書き更新しない設計にする。GitHubのdocs/adr/ディレクトリに連番で管理する標準構成を推奨 |
| API仕様書 （OpenAPI/Swagger・エンドポイント一覧） |
OpenAPI仕様書はコードファースト（実装からの自動生成）が最も精度が高い。Claude Codeにコントローラーコードとリクエスト・レスポンスのTypeScriptインターフェース（またはPydanticモデル等）を入力として与えることで、OpenAPI YAMLの初稿を自動生成させる。エンドポイントの追加・変更時にCI/CDパイプラインでClaude Codeによる仕様書更新をトリガーする設計が「コードと仕様書のズレ」を防ぐ | ①認証方式（OAuth2/APIKey/JWT等）の記述が実装と一致しているか②エラーレスポンスのHTTPステータスコードとメッセージが実装と一致しているか③外部公開APIの場合は「後方互換性を壊す変更」が仕様書に反映されているかの確認が最重要（外部利用者への影響が大きいため自動生成をそのまま公開しない） | 内部APIは毎PRでの自動更新・外部公開APIはリリースタグ時のみ更新するサイクルの違いをCIパイプラインで設計する。GitHub Pagesまたは社内ドキュメントサーバーへの自動デプロイまで自動化することで「最新仕様書を手動で公開し忘れる」問題をゼロにできる |
| CHANGELOG・リリースノート （変更履歴・バージョン管理） |
「git log –oneline」の出力をClaude Codeに渡すことでCHANGELOGの初稿を自動生成させる設計が標準パターン。Conventional Commits（feat:/fix:/chore:等のプレフィックス）でコミットメッセージを統一すると、Claude Codeがブレイキングチェンジ・新機能・バグ修正を正確に分類してCHANGELOGを生成できる精度が上がる | ①「ユーザーに影響するブレイキングチェンジ」が明確に記載されているか（自動生成では埋もれる場合がある）②バージョン番号がセマンティックバージョニング（SemVer）のルールに沿っているか③エンドユーザー向けリリースノートはテクニカルな記述から「ユーザーへのメリット」表現に書き換えが必要（Claude Codeの初稿はエンジニア視点になりやすい） | タグpush時にGitHub Actionsでgit logをClaude Codeに渡してCHANGELOGを自動生成・GitHub Releaseに投稿するまで自動化できる。CHANGELOG.mdのKeep a Changelogフォーマットを採用してCLAUDE.mdにフォーマット仕様を定義することで、生成されるCHANGELOGのフォーマット一貫性を保てる |
この表でClaude Codeを使ったDocs as Code運用の最重要設計が「ドキュメント種別ごとの自動化範囲と人間の確認ポイントを明示した運用規約の文書化」です。「何でもClaude Codeに任せる」でも「全部人間が書く」でもなく、種別ごとに「Claude Codeが初稿作成→人間が特定ポイントをレビュー→承認後にmainへマージ」のハイブリッドフローを確立することが、ドキュメントを「負債」から「資産」に変える実践的なDocs as Codeの設計です。CLAUDE.mdに上記の種別ごとの運用方針を記述しておくことで、チームメンバー全員が同じ理解でClaude Codeを活用できる環境を整備できます。
導入時の注意点とセキュリティ対策
意図しないファイルの読み込みを制限する
Claude Code は強力なため、リポジトリ内のあらゆるファイルを読み込もうとします。環境変数（.env）や顧客データが含まれる CSV など、AI に送信すべきでないデータがある場合は、必ず .gitignore や Claude Code の設定で制限をかける必要があります。
APIコスト管理とスケーラビリティ
Claude Code は Anthropic の Claude Sonnet 4.6 などの高性能モデルを使用するため、大規模なプロジェクトで頻繁に ls -R やファイル全件読み込みを行うと、API 使用料が増大します。
claude compact コマンド（履歴の要約）を適宜利用したり、特定のディレクトリ（例：claude "docs/ 以下だけを見て"）にコンテキストを絞って指示を出すのが、賢い運用術です。
よくある質問（Claude Code ドキュメント as Code README ADR Git管理）
Q. ドキュメント as Code（Docs as Code）とは何ですか？なぜGitで管理するのですか？
ドキュメント as Codeは、技術ドキュメント（README・設計書・ADR等）をソースコードと同じGitリポジトリ・MarkdownファイルでバージョンGit管理する手法です。Gitで管理する理由は①変更履歴の追跡：いつ誰が何を変更したかをgit logで確認できる②Pull Requestによるレビュー：コードレビューと同じプロセスでドキュメントの品質を担保③CI/CDとの統合：ドキュメントの自動ビルド・デプロイ（GitHub Pages・Docsifyなど）④コードと同期：コード変更時に関連ドキュメントも同じPRで更新するルールが作りやすい、の4点です。
Q. ADR（Architecture Decision Record）はどのように書きますか？
ADRの基本フォーマットは①タイトル：「ADR-001: 認証にJWTを採用する」のように番号+決定内容②ステータス：Proposed（提案）・Accepted（採用）・Deprecated（廃止）・Superseded（上書き）のいずれか③コンテキスト：なぜこの決定が必要になったか・背景の説明④決定内容：何を選んだか⑤根拠：なぜその選択をしたか・トレードオフの明示⑥結果：この決定によって何が変わるか・将来のリスク、の6セクションが基本です。`docs/adr/`ディレクトリにMarkdownファイルとして保存し、番号順に管理するのが一般的です。
Q. Claude CodeでREADMEやADRを自動生成・更新するには？
Claude CodeでのDocs as Code活用方法は①READMEの自動更新：`claude “src/ディレクトリのコードを読んでREADME.mdのAPI仕様セクションを更新して”`で最新コードからドキュメントを自動生成②ADRのドラフト作成：設計判断の背景をプロンプトで説明し「ADRフォーマットで草案を書いて」と依頼③変更検知とドキュメント更新の連動：CIでコード変更を検知した際にClaude Codeにドキュメント更新を依頼するスクリプトの自動化④CLAUDE.mdにドキュメントルールを記述：リポジトリ固有のドキュメント規約（命名・ディレクトリ構成・更新タイミング）をCLAUDE.mdに記載して毎回の指示を省略、の4パターンです。
まとめ：ドキュメントを「負債」から「資産」に変えるために
ドキュメント管理を成功させるコツは、ドキュメント作成を「特別なイベント」にしないことです。Claude Code を CLI 上のパートナーとして迎え入れることで、コードを書く、テストを走らせる、という日常の動作の中に「ドキュメントを更新する」という工程を自然に組み込めます。
README が常に正しく、ADR によって過去の経緯が透明化されているリポジトリは、新規参画者のオンボーディング速度を劇的に高めます。まずは CLAUDE.md を作成し、Claude Code にあなたのプロジェクトのルールを教え込むところから始めてみてください。それは、未来の自分やチームメンバーへの最も価値ある投資になるはずです。
Claude Code を使った Docs as Code 運用では、README や ADR をどのスコープで生成・更新するか、そしてAIに渡すリポジトリのファイル範囲と権限をどう絞るかがセキュリティの要になります。権限設計や操作ログの整備、PoCの進め方は Claude Code 導入支援 でもご相談いただけます。
生成AIの法人導入・セキュリティ設計のご相談
ChatGPTやClaudeなど生成AIのプラン選定・セキュアな全社導入・権限／ログ設計を、貴社の体制に合わせて整理します。すでに導入済みの環境について『この設計で問題ないか』を確認したい、という導入前後のセカンドオピニオンにも対応しています。
AI・業務自動化
ChatGPT・Claude APIを活用したAIエージェント開発、n8n・Difyによるワークフロー自動化で繰り返し業務を削減します。まずはどの業務をAI化できるか診断します。