株式会社renue
renueについて
renueは、AIで業務を実装する会社です
AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。
AI前提の情報設計——ドキュメント戦略の根本転換
人間向けのREADMEだけでは、AIエージェントが必要とする作業上の指示を見つけにくい場合があります。「どこに何があるか」「どのルールに従うか」「どう実装を変更するか」を整理しつつ、プロジェクトの理念、貢献ガイドライン、ライセンス情報も、作業に関係する内容は参照できるようにします。READMEを一律に不要とせず、指示書で補います（AGENTS.md：READMEを補う位置づけ）。
本記事の2026年版の方針は、ドキュメントを「人間とAI両方が読むもの」として設計することです。本記事では、CLAUDE.md・AGENTS.md・READMEの使い分けと、ドキュメント負債を防ぐ運用設計を解説します。
3種類のドキュメントの使い分け
| ファイル | 読者 | 目的 | 内容 |
|---|---|---|---|
| README.md | 主に人間（新規参画者）。AIも必要に応じて参照 | プロジェクトの全体理解 | 目的、セットアップ手順、アーキテクチャ概要 |
| CLAUDE.md | Claude Code | プロジェクト固有のルール・制約 | コーディング規約、デプロイ制約、セキュリティルール |
| AGENTS.md | AGENTS.mdに対応するエージェント | Markdownによる作業指示の共有 | ファイル構成、ビルド手順、テスト方法 |
READMEとCLAUDE.mdの決定的な違い
READMEは概要やセットアップなど、参加者がプロジェクトを理解する入口です。CLAUDE.mdには、Claude Codeが各セッションで参照すべきプロジェクト固有の規約やコマンド、判断の前提を整理します。コードから明らかな説明の重複を抑え、必要な情報へ案内します（Claude Code：指示書に入れる内容）。
README.md（人間向け）: 「このプロジェクトはNext.js 15とFastAPIで構築されています。 インストール手順: npm install → npm run dev」 CLAUDE.md（AI向け）: 「コミットメッセージは日本語で書く。 .envファイルは絶対に読み取らない。 デプロイはdevelopment/stagingのみ。productionは禁止。 テストは必ずyarn test:e2eで実行する」
AIは「Next.jsプロジェクトである」ことはpackage.jsonを読めば自力で判断できます。一方、「コミットメッセージは日本語」「本番デプロイ禁止」といった運用ルールは、CLAUDE.mdなど、確実に参照する指示や設定で明示します。上記は記述例であり、指示書だけでアクセスや実行を強制的に防げるわけではありません。機密ファイルや本番環境の保護は実際の権限制御にも反映します。
CLAUDE.mdの配置戦略
3層の配置
以下は代表的な配置例です。Claude Codeには組織管理の指示や個人用の追加ファイルなどもあります。作業ディレクトリとその親の指示は起動時に、配下の指示はそのディレクトリのファイルを読むときに読み込まれます。競合する指示は整理してください（公式の配置と読込規則）。
| 配置場所 | 適用範囲 | 内容例 |
|---|---|---|
~/.claude/CLAUDE.md | そのユーザーの全プロジェクト共通 | 個人の作業スタイル、共通ルール |
./CLAUDE.md（プロジェクトルート） | チーム共有 | プロジェクト固有のルール、技術制約 |
./packages/api/CLAUDE.md | サブディレクトリ | モノレポの各パッケージ固有ルール |
AGENTS.mdの設計——エージェント向けのMarkdown指示書
AGENTS.mdは2025年8月に公開された、「AIエージェントのためのREADME」と説明されるオープンな形式です。複数製品で利用できますが、全てのエージェントが同じ方法で自動読込するわけではありません（Linux Foundationの発表、AGENTS.md公式サイト）。
Codexは起動時に所定の順序でAGENTS.md等を探索し、CursorはルートやサブディレクトリのAGENTS.mdを利用します。Claude CodeではCLAUDE.mdから@AGENTS.mdを読み込む方法があります。Aiderでは指示ファイルを--readや設定ファイルのreadで指定できます。実際の読込対象を各製品で確認してください（Codex、Cursor、Claude Code、Aider）。
AGENTS.mdに書くべきこと
- 最小限の要件：ビルドコマンド、テストコマンド、lint設定
- カスタムツール：プロジェクト固有のスクリプトやコマンド
- 固有のツーリング選択：「RuffでなくBlackを使う」等の判断
AGENTS.mdで重複を抑えること
- AIがコードから容易に把握できる情報の長い転載（ファイル構成、依存関係）。迷いやすい入口や固有の前提は残す
- 一般的なベストプラクティスの網羅的な説明。プロジェクトで守る必要のある基準や例外は明示する
- 人間向け説明文の全文転載。理念・貢献ガイド・ライセンス等で作業に関わる条件は、要点や参照先を示す
手書きと自動生成のどちらがよいかは、指示の内容、対象タスク、モデル、評価条件によって異なります。作成方法だけで性能を決めつけず、生成した指示も人が確認し、実際の作業で不要な説明や誤ったルールが混ざっていないか検証します。
ドキュメント負債を防ぐ5つのルール
ルール1：コード変更時にドキュメントも更新する
CLAUDE.mdやAGENTS.mdはコードと同じリポジトリで管理し、コード変更PRにドキュメント更新を含めます。
ルール2：ドキュメントの「オーナー」を決める
ドキュメントの更新責任者を明確にします。「全員の責任」は「誰の責任でもない」のと同じです。
ルール3：CIでドキュメントの整合性をチェック
「CLAUDE.mdに記載されたデプロイ先環境が、実際のCI/CD設定と一致しているか」等をCIで自動検証します。
ルール4：四半期ごとにドキュメントレビュー
3ヶ月ごとにCLAUDE.mdの内容が現状と合っているか確認します。古い制約が残っていないか、新しいルールが追加されていないかをチェックします。
ルール5：不要になったドキュメントは削除する
「いつか使うかも」で残されたドキュメントはノイズです。AIのコンテキストを汚し、人間を混乱させます。
AIエージェントが「選ぶ」ドキュメント
AIエージェントにSaaSボイラープレートやライブラリの調査を依頼する場合は、ドキュメントの質も評価項目に含める運用を提案します。CLAUDE.mdやAGENTS.mdの有無だけで選ぶのではなく、手順の再現性、更新状況、制約やライセンス、用途への適合を確認します。指示書を整備すれば必ず選ばれるという意味ではありません。
まとめ：ドキュメント戦略チェックリスト
| 項目 | チェック |
|---|---|
| README.md | 人間の新規参画者向けにプロジェクト概要・セットアップ手順が書かれているか |
| CLAUDE.md | AIが自力で発見できない固有ルール（コミット規約/デプロイ制約/セキュリティ）が書かれているか |
| AGENTS.md | 対応エージェントが読めるMarkdown指示（ビルド/テスト/lint）が書かれ、製品別の読込方法を確認したか |
| 配置 | 3層（ホーム/プロジェクトルート/サブディレクトリ）で適切に配置されているか |
| 更新 | コード変更時にドキュメントも同時に更新するルールがあるか |
| オーナー | ドキュメントの更新責任者が明確か |
| CI | ドキュメントの整合性をCIで自動チェックしているか |
| レビュー | 四半期ごとにドキュメントの棚卸しをしているか |
ドキュメントは「書く義務」ではなく「チームの生産性を上げる武器」です。人間を主な読者とするREADME、Claude Code向けのCLAUDE.md、対応エージェントで共有するAGENTS.md——この3層を整備し、ドキュメント負債を防ぐ仕組みを構築してください。
あわせて読みたい
- 5Sとは｜整理・整頓・清掃・清潔・しつけの意味・目的・進め方を解説
- AIリードスコアリング実装ガイド【2026年版】— 4要素スコアリング×テリトリー管理×ステータス倍率の本番アーキテクチャ
- AIカスタマーサポート完全ガイド【2026年版】— RAG・チャットボット・有人連携の実装パターンとツール比較
関連記事
AI開発のご相談はrenueまで。
