CLAUDE.md・AGENTS.mdの運用実践ガイド：書くだけで終わらせない更新と管理のコツ

CLAUDE.mdおよびAGENTS.mdとは、Claude CodeやCursor、OpenAI CodexをはじめとするAIコーディングツールに対して、自社独自の開発ルール、アーキテクチャ方針、セキュリティ規約を自動認識させるためのAI専用指示書（プロジェクト設定ファイル）です。プロンプトを毎回チャットに入力する手間を省き、AIエージェントによるコード生成の精度や安全性を飛躍的に高める「取扱説明書」として機能します。

しかし、多くの導入現場において「最初に一度作成したものの、それきり更新されず放置されている」という指示書の形骸化が深刻な課題となっています。ファイルをフォルダ内に配置する作業自体は数分で完了します。しかし、真の成果を出すために必要なのは「日々どのように書き足し、誰が更新し、どうセキュリティ事故を防ぐか」という持続可能な運用設計です。

本記事では、開発実務でのテクニックはもちろん、非エンジニアの経営者・事業責任者が押さえるべき点検ポイントまで含め、CLAUDE.mdとAGENTS.mdを自社の「生きた安全資産」として継続運用するための実践ノウハウを網羅的に解説します。

1. CLAUDE.md・AGENTS.mdとは？「作って終わり」に潜む落とし穴

AIを活用したソフトウェア開発や業務自動化が一般化した現在、AIに与える「コンテキスト（文脈・前提知識）」の質が成果物の出来栄えや安全性を左右します。その中核を担うのが、主にプロジェクトのルートディレクトリに配置するCLAUDE.mdやAGENTS.mdといった設定ファイルです（個人用やサブフォルダ用に置くこともできます）。

1-1. なぜプロンプトの毎回手動入力では失敗するのか

単発のチャット画面（ChatGPTやClaudeのWeb画面など）でそのつど指示を出している場合、現場では次のようなトラブルが頻繁に発生します。

• プロジェクト独自の規約無視：ディレクトリ構造、命名規則、許可されたライブラリを無視したコードが生成される
• 破壊的・危険な操作の無断実行：ファイルの一括削除、データベース変更、外部送信などの操作を人間への確認なしに実行してしまう
• 過去のトラブルの再発：自社で過去に起きたヒヤリハット（設定ミス等）が共有されず、同じ失敗を繰り返す
• 説明コストの増大：チャットのやり取りが切れるたびに、前提条件や社内ルールをゼロから説明し直す必要がある

あらかじめプロジェクト内にルール記述ファイルを配置しておけば、AIツールが作業開始時にこれらのドキュメントを自動読み込みし、前提条件を固定した状態で動作してくれます。

1-2. 最大の課題は「導入後の形骸化」

ファイルを配置する作業自体はコマンド1つ、数分で終わります。しかし、実際に導入した企業の現場へヒアリングを行うと、「最初に一度書いて、それきり誰も見ていない」というケースが後を絶ちません。

これは新入社員向けのマニュアルを入社日に配布して満足し、その後の業務改定や現場のルール変更がマニュアルに一切反映されていない状態と同じです。導入初期のルールのまま数か月が経過し、現在の開発実態とズレが生じているにもかかわらず誰も気づかない——この「形骸化」こそが、AI運用における最大の落とし穴です。

2. CLAUDE.mdとAGENTS.mdの違いと使い分け【比較表・図解】

どちらも「AI向けのプロジェクトルール記述ファイル」ですが、仕様の成り立ち、対象となるツールの範囲、および標準化の主体において明確な違いが存在します。

2-1. 仕様の背景と中立性

CLAUDE.md：Anthropic社が提供するAIコーディングツール「Claude Code」が作業開始時に自動で読み込む専用の設定ファイルです。

AGENTS.md：特定一社の独自仕様ではなく、複数のAIツールが共通して読み込めるオープンな業界標準ファイルです。2025年8月にOpenAIを中心とした複数の開発ツール企業によって公開され、同年12月にはLinux Foundation傘下の「Agentic AI Foundation（AAIF）」へ管理が移管されました。特定企業に依存しない中立な標準として策定されており、Cursor、OpenAI Codex、Gemini CLI、GitHub Copilotなど主要ツールで採用が広がっています。

2-2. 実務でのスマートな「一本化」運用手法

実務上の役割分担で迷った場合は、「AGENTS.mdは業界標準の説明書、CLAUDE.mdはClaude Code専用の追加メモ」と捉えると整理しやすくなります。なお、Claude Codeは現在、CLAUDE.mdが無ければAGENTS.mdを直接読み込みます。ただし初期設定では、CLAUDE.mdがある場合はそちらだけを読むため、Claude Code専用の指示も書きたいときは、次のようにCLAUDE.mdからAGENTS.mdを読み込ませる形が公式にも案内されています。

プロジェクトの基本規約や禁止事項など「どのAIツールを使っても変わらない内容」はすべてAGENTS.mdに集約します。そのうえで、CLAUDE.md側には以下のように「AGENTS.mdを読み込む」という指示だけを記載しておくことで、ルールの実質的な本体を1つに絞り込めます。

# CLAUDE.md

@AGENTS.md

## Claude Code専用設定
- Claude Code固有の作業手順（例：サブエージェントやSkillsの使い分け）

※コマンドの自動承認や禁止は、CLAUDE.mdではなく設定ファイル（settings.json）の許可設定で行います。CLAUDE.mdは強制力のある設定ではなく、AIが参考にする情報です。

この一本化構成をとっておくことで、将来的にエンジニアが別のAIツールを採用したり、チーム内で複数のツールが混在したりした場合でも、指示書の二重管理によるブレを防ぐことができます。

3. 何を書くべきか？書き方の鉄則と優先順位の付け方

ルールファイルを作成する際、最も重要なのは「何を書き、何を書かないか」の境界線を厳格に引くことです。情報を詰め込みすぎると人間も読まなくなり、AIも指示を守りきれなくなります。

3-1. 明記すべき「4つの必須要素」

ルールファイルに記載すべきなのは、「現場で毎回繰り返し説明しているルール」のみです。以下の4項目に絞り込んで記述します。

• プロジェクト特有の約束事：命名規則、ディレクトリ構成、採用を許可・禁止する技術スタック
• 実行前の確認が必須な操作の線引き：ファイル削除処理、外部へのデータ送信、公開設定、支払い・決済の発生する操作
• 過去に自社で起きたヒヤリハットの再発防止策：自社の失敗体験から得られた固有の注意事項
• 非エンジニア担当者や経営陣が重視する禁止事項：個人情報の扱い、セキュリティガバナンス上のルール

逆に、AIがソースコードを一読すれば自明な内容（標準的なライブラリの使い方やファイル構成から推測できる仕様）は書く必要がありません。「口頭やチャットで何度も修正指示を出している」と感じた項目だけを、そのつど追記していくのが健全な成長プロセスです。

3-2. ルールに優先順位をつける書き方

ルールの数が増えてくると「どれが一番重要か」の判別が難しくなり、AIが軽微な書式の指定を優先して重大な安全規制を後回しにしてしまうケースがあります。これを防ぐため、カテゴリ分けと番号による優先順位の明記を行います。

# ルール適用優先順位
※記載されているルール同士が矛盾した場合は、必ず数字が小さい（優先度が高い）カテゴリの指示に従うこと。

## 1. 認証情報およびセキュリティの取り扱い（最優先）
- APIキーやパスワードをコード内や本ファイル内に直接書き込んではならない。
- 外部へのデータ送信処理を行う前に、必ず人間に確認を取ること。

## 2. 破壊的変更・決済処理の確認
- データベースの削除（DROP/DELETE）や本番サーバーへの公開処理は、実行前に人間へ承認を求めること。

## 3. プロジェクト固有の技術選定と命名規則
- TypeScriptはStrictモードで使用し、any型の使用を禁止する。
- コンポーネント名はPascalCase（例: UserProfile.tsx）で統一すること。

## 4. 開発プロセスとコミットルール
- 各タスク完了前には、必ず npm run type-check を実行してエラーがないことを確認すること。

3-3. 階層構造を活用したルールの分離

フォルダごとに事情が異なる大きなプロジェクトでは、各フォルダの直下にその場所だけに適用される追加ルールを置く「階層構造」が効果的です。

パソコン全体で常に守ってほしい共通スタイルは個人環境側へ、特定プロジェクト固有のルールはプロジェクト直下へ、さらに厳格なセキュリティが必要なモジュールは専用フォルダ内へ置くことで、ルールが混同するトラブルを防ぎます。

4. ファイルの肥大化を防ぐテクニックと「長すぎる逆効果」の回避

CLAUDE.mdやAGENTS.mdは、AIが作業を始めるときに読み込まれ、その後のやり取りの間ずっと記憶枠に置かれ続ける文章です。ファイルが長くなればなるほどAIが一度に維持すべき指示の数が膨らみ、結果として重要なルールほど読み飛ばされやすくなる逆転現象が発生します。

4-1. 長すぎる指示書が引き起こす悪影響

• 重要ルールの希薄化：ルール数が増大すると、致命的な安全規制が軽微な記述の中に埋没する
• コンテキストの無駄遣い：やり取りのたびにAIの記憶枠（コンテキストウィンドウ）を無駄に消費する
• 指示の相反・不安定化：長文の中で過去の古い記述と新しい記述が矛盾し、AIの挙動がぶれる

4-2. スリムに保つための具体的処方箋

Claude Codeの公式ドキュメントでは、1ファイルあたり200行未満を目安とし、それより長いと記憶枠を多く使い、指示が守られにくくなると案内されています。増える一方で減らない状態が最も典型的な劣化パターンです。

詳細な仕様や長大な規約が存在する場合は、本文を別ファイルへ切り出し、メインのファイルからは参照指示を1行書くにとどめます。

# 詳しい技術仕様・ドキュメント参照

- データベース構造の詳細規約については docs/db-schema.md を参照すること。
- APIレスポンス形式の仕様については docs/api-guidelines.md を参照すること。
- 上記ファイルは、関連するタスクを実行する際のみ読み込むこと。

5. 更新をストップさせない体制と4つの運用ルール

更新が止まる最大の理由は、「誰が、いつ、どのように更新するか」の運用フローが決まっていないことです。放置を防ぐため、以下の4つの運用ルールを社内に導入してください。

運用ルール1：更新の窓口担当者を1人に絞る

ルールの更新責任者を1人（経営者本人、またはAI活用を主導するプロジェクト担当者）に指定します。責任の所在を明確にすることが形骸化防止の第一歩です。

運用ルール2：「2回目以降も必要」と思った瞬間にその場で追記

新しいルールをAIに指示した際、それが今後も繰り返し必要だと感じたら、その場でファイルに追記します。更新を「月末のまとめ作業」にしてしまうと、細かい気づきの多くは記録される前に忘れ去られます。

運用ルール3：ファイル更新自体を「AIにやらせる」

人間が手動でMarkdownファイルを編集するのが手間な場合は、作業中のAIエージェントに対して直接更新を指示します。

AIへの指示例：「今回のエラー対応で判明した注意点を、AGENTS.mdの再発防止セクションに1文で追記し、コミットしてください。」

運用ルール4：月1回の定期見直し（棚卸し）を実施する

月に一度など決まったタイミングで見直しの機会を設定します。新しく追加するだけでなく、「もう不要になった古い行がないか」を確認し、不要なルールを削除する「断捨離」を行います。

6. 実務でよくある5つの失敗パターンとトラブルシューティング

現場の運用で発生しやすい典型的な失敗事例と、その解決策をまとめました。

1. 放置による「形骸化」

現象：導入時のルールのまま数か月が経過し、実際のコード構造やライブラリ構成とズレが発生。AIが古い書き方のコードを出力し続ける。

対策：窓口担当者を決め、月1回の定期棚卸し日をカレンダーにセットする。

2. 肥大化による「重要ルールの埋没」

現象：ルールを削除せず足し続けた結果、300行を超える巨大ファイルとなり、本当に重要な禁止事項が無視される。

対策：メインファイルは100〜200行に抑え、詳細な仕様は docs/ フォルダ配下の別ファイルへ切り出す。

3. 秘密情報（APIキー・パスワード）の誤混入

現象：APIキーやパスワードをテスト用に記述してしまい、Git経由で外部やチーム全体へ秘密情報が漏洩する。

対策：設定ファイルはGitで共有される前提のため、認証情報は絶対に直書きせず「環境変数（.env）を参照すること」と明記する。

4. ルール同士の「矛盾」

現象：「慎重に確認を取る」と「承認されたタスクは最後まで一気に自動実行する」が同時に存在し、AIの挙動が不安定になる。

対策：ルール追加時に既存の文言とぶつかっていないかを確認し、冒頭に「数字が小さいルールを優先する」と優先度を明記する。

5. 記述が抽象的すぎて「行動に繋がらない」

現象：「コードをキレイに書く」「安全に作業する」といった定性的な心構えばかりが並び、AIが具体的な行動を選べない。

対策：「1関数の行数は50行以内」「ファイル削除時は確認ダイアログを出す」など、AIが明確に判定できる定量的なルールに書き直す。

7. 非エンジニア・経営者が確認すべき3つのチェックポイント

プログラミングコードが読めなくても、CLAUDE.mdやAGENTS.mdの中身は日本語のテキストとして記述できます。経営者や事業責任者が確認すべきなのは技術的な詳細ではなく、「事業を守るためのガードレールが正しく機能しているか」というビジネス管理の視点です。

技術的な設定・構成はエンジニアチームへ一任し、業務のガードレール（送信前の確認、決済操作の禁止、ヒヤリハットの記録）は経営者・責任者が直接確認する。ここを外部任せにせず経営目線で点検することが、形骸化を防ぐ最大の防壁になります。

文章の言い回しやMarkdownの書式の調整は、エンジニアに任せて問題ありません。経営者の役割は「どこまでの自動化を許容し、どこで人間の承認を必須とするか」という現場の温度感に基づく線引きを示すことです。

8. 今日から始める運用チェックリスト

自社のAIエージェント指示書を安全かつ効果的に運用するための5つの点検項目です。

• プロジェクトのフォルダ直下に AGENTS.md または CLAUDE.md が存在しているか
• 設定ファイルの内容を最後に見直した日付を覚えているか（2か月以上放置は要見直し）
• APIキーやパスワードなどの秘密情報が書かれていないか、目視で確認したか
• ルールが増えた際、優先順位（1、2、3…）が明記され矛盾がないか
• 複数のAIツールを併用している場合、共通ルールが AGENTS.md にまとまっているか

9. まとめ：ルールファイルを自社の安全な資産として育てる

ゼロから完璧な指示ファイルを作ろうとすると、作成作業自体が負担となり途中で挫折します。推奨されるのは「小さく始めて、実際の失敗から育てる」アプローチです。まずは5〜10行程度の「最低限の禁止事項」だけを書いたファイルからスタートし、日々の作業の中で「繰り返し指示したこと」や「ヒヤリとした出来事」に直面した瞬間に1行ずつ足していきます。

本記事のポイントおさらい

• AGENTS.mdを業界標準の基盤とし、CLAUDE.mdと連携させて運用を一元化する
• 繰り返し指導している注意点と自社のヒヤリハットのみをシンプルに記述する
• ルールには番号で優先順位をつけ、矛盾によるAIの判断のぶれを防ぐ
• 経営者自身が「業務上のガードレール」と「秘密情報の有無」を定期確認する

指示ファイルは一度書いて終わりの設計図ではなく、事業の実態に合わせて育てていく運用対象です。小さな更新を積み重ねる習慣こそが、AIガバナンスの本体です。使い続けるうちに、このファイルはAIへの指示書であると同時に「自社のトラブル防止策とノウハウが凝縮された貴重な安全資産」へと成長していきます。