AGENTS.md・CLAUDE.md の書き方｜チームでブレないルール（真似できる例）

更新：2026年4月16日

目次クリックで開く

AIによるコード生成や自動リサーチが日常化する中、エンジニアが直面する新たな課題が「AIへのコンテキスト共有」です。どれほど高性能なモデル（Claude 3.5 Sonnet 等）を使用しても、プロジェクト固有のディレクトリ構成や独自のコーディング規約、ビジネスロジックの暗黙知をAIが把握していなければ、出力されるコードは「一般的すぎて使い物にならない」ものになってしまいます。

この問題を解決するために登場したのが、AGENTS.md や CLAUDE.md といった、AIエージェント専用の設定ファイルです。これらをリポジトリのルート直下に配置することで、AIがプロジェクトの全体像を即座に理解し、チームのルールを遵守した自律的な行動が可能になります。

本記事では、IT実務者の視点から、これらのファイルの具体的な書き方、構成案、そしてチームでブレない運用を実現するためのテンプレートを詳しく解説します。

1. AGENTS.md / CLAUDE.md とは？AI時代に必須となる「外部脳の仕様書」

1.1 AIエージェントにプロジェクトの「正解」を教える仕組み

AGENTS.md や CLAUDE.md は、いわば「AIのためのREADME」です。従来の README.md が人間に向けたセットアップ手順やプロジェクトの概要を記述するものであるのに対し、これらのファイルは AI（Large Language Model / AI Agents）がコードベースを探索する際のガイドラインとして機能します。

具体的には、以下のような役割を果たします。

コンテキストの即時同期：新しいAIチャットやエージェントを立ち上げた際、過去のやり取りを説明することなく、プロジェクトの全容を理解させる。
ルールの強制：使用すべきライブラリのバージョン、命名規則、テストの書き方などをAIに遵守させる。
ハルシネーション（誤情報）の抑制：存在しないディレクトリや古いAPIの使用を未然に防ぐ。

1.2 主な対応ツール（Claude, Cursor, GitHub Copilot）の現状

現在、これらのファイルを自動的、あるいは優先的に読み込むツールが増えています。

Claude Code / Claude Desktop：CLAUDE.md を標準的な設定ファイルとして推奨しています（公式ドキュメント参照）。
Cursor：.cursorrules が有名ですが、汎用的な AGENTS.md を参照させる動きも加速しています。
Windsurf (Codeium)：プロジェクト全体のコンテキストを読み取る際、ルートディレクトリの .md ファイルを重要なリソースとして扱います。

2. AGENTS.md と CLAUDE.md の違いと使い分け

これら二つのファイルは目的が似ていますが、その背景と標準化の度合いに違いがあります。プロジェクトの性質に応じて使い分ける、あるいは併用するのが一般的です。

項目	CLAUDE.md	AGENTS.md
提唱・由来	Anthropic (Claude Code)	オープンなコミュニティ / 各種エージェントツール
主な対象	Claude シリーズのエージェント	汎用AIエージェント全般 (GitHub Copilot, AutoGPT等)
記述内容	ビルド・テスト手順、特定のClaude向け命令	プロジェクト構造、思想、コーディング詳細規約
推奨配置	リポジトリのルート直下	リポジトリのルート直下

2.1 CLAUDE.md：Claude Code や Desktop 版に特化した標準

Anthropic社が提供する CLIツール「Claude Code」では、CLAUDE.md を読み取ることで、プロジェクト固有のコマンド（テスト実行、ビルド、リンター等）を自動的に学習します。これにより、ユーザーが「テストを走らせて」と言うだけで、プロジェクトに最適な npm test や pytest を選択して実行できるようになります。

2.2 AGENTS.md：汎用的なAIエージェント向けガイド

一方で AGENTS.md は、より人間が読みやすく、かつ多種多様なAIツールに「このプロジェクトの憲法」を伝えるための汎用ファイルです。特定のツールに依存せず、AIがプロジェクトに参画した際の情報源として機能します。

2.3 どちらを優先すべきか？（結論：ハイブリッド運用）

実務においては、両方を併用する「ハイブリッド運用」を推奨します。CLAUDE.md には「動作（コマンド）に関する指示」を、AGENTS.md には「設計思想や規約に関する指示」を記述し、相互に参照させる形が最も効率的です。

こうしたAIへのコンテキスト指示の重要性は、開発領域に留まりません。例えば、業務フロー全体の自動化を検討する場合も、システム間の「正しい繋がり」を定義しておくことが成功の鍵となります。
Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドで解説されているような、ノーコードツールとデータの連携においても、AIに「どのデータが正解か」を教え込むプロセスは共通の重要課題です。

3. 【実践】AGENTS.md・CLAUDE.md に書くべき必須項目 5 選

AIエージェントが「自走」するために必要な情報は、以下の5つのセクションに集約されます。これらを網羅することで、指示のブレを最小限に抑えることができます。

3.1 プロジェクトの全体像と技術スタック（Tech Stack）

まず、プロジェクトが何を目指しているのか、どの技術を採用しているのかを明文化します。

目的：ECサイトのバックエンド、データ分析基盤、社内用ダッシュボードなど。
主要技術：Next.js (App Router), Go (Gin), PostgreSQL, Prisma, Tailwind CSS など。
ライブラリ選定方針：外部ライブラリは極力使わず標準機能を使う、あるいは特定のUIコンポーネントライブラリを優先するなど。

3.3 ディレクトリ構成の定義（Directory Structure）

AIが最も迷いやすいのが「新しいファイルを作る場所」です。

例：ロジックは /services に、型定義は /types に、APIハンドラは /api に配置する。

このツリー構造をテキスト形式で AGENTS.md に記述しておくだけで、AIによる誤った配置が劇的に減少します。

3.3 コーディング規約とデザインパターン（Coding Standards）

チーム独自のスタイルをAIに叩き込みます。

変数命名は camelCase か snake_case か。
関数は const 宣言のアロー関数か、function キーワードか。
エラーハンドリングの共通クラスはあるか。
非同期処理は async/await を徹底するか。

3.4 ワークフローとデプロイ手順（Workflows）

特に CLAUDE.md で重要な項目です。AIが実行すべきコマンドを定義します。

Build: npm run build
Test: npm test -- --watchAll=false
Lint: npm run lint

3.5 絶対に守るべき禁止事項（Critical Constraints）

「これをやったらNG」という制約を明示します。これが最もハルシネーション対策に有効です。

「廃止予定の legacy/ 配下のモジュールは絶対にインポートしないこと」
「パスワードや個人情報をログに出力しないこと」
「any 型の使用を禁止する。必ずインターフェースを定義すること」

このような厳格なルール定義は、SaaS間のデータ連携における「バリデーション」に似ています。例えば、会計システムと他ツールの連携では、データの整合性を保つための厳密なルールが必要です。詳細は楽楽精算×freee会計の「CSV手作業」を滅ぼす。経理の完全自動化とアーキテクチャを参考にしてください。AIもまた、適切な「入力（ルール）」があって初めて「正しい出力」を返します。

4. すぐに使える「チーム用テンプレート」と具体例

以下は、実際に実務で使用できる AGENTS.md のテンプレートです。これをベースに、プロジェクトの状況に合わせてカスタマイズしてください。


AGENTS.md - プロジェクト開発ガイドライン
1. プロジェクト概要

名称: Project-Alpha

目的: 顧客行動分析用マイクロサービス

主要スタック: Node.js 20+, TypeScript, dbt, BigQuery

2. ディレクトリ構成

/src/handlers: APIエントリーポイント

/src/services: ビジネスロジック（純粋関数を推奨）

/src/models: スキーマ定義

/tests: Vitestによるテストコード

3. コーディング規約

命名: 変数/関数は camelCase。クラス/型は PascalCase。

非同期: Promiseチェーンではなく、必ず try-catch と async/await を使用。

コメント: JSDoc形式で全ての公開関数に記述。

4. AIへの特別な指示

新しい関数を作成する際は、必ず対応するテストファイルを tests/ 内に作成してください。

既存のファイルを修正する場合、既存の import スタイルを崩さないでください。

パフォーマンス向上のため、ループ処理よりも map, filter, reduce を優先してください。

5. 禁止事項

process.env を各ファイルで直接参照しない。必ず src/config.ts を経由すること。

ライブラリの追加を提案する場合は、まず標準モジュールで代用できないか検討すること。

4.2 AIが迷わないための「良い書き方」と「悪い書き方」

AIへの指示は、具体的かつ断定的である必要があります。

悪い例：「なるべく綺麗に書いてください」 → 抽象的すぎてAI独自の「綺麗」が適用されます。
良い例：「SOLID原則に基づき、1つの関数は20行以内、循環複雑度は5以下を維持してください」 → 数値指標があるため、AIが自己検品しやすくなります。

5. 実務での運用・更新フローとセキュリティ

5.1 CI/CDと連動したドキュメント同期の考え方

AGENTS.md が古くなると、AIは「嘘をつく」ようになります。これを防ぐためには、README.md を更新するのと同様の感覚で、プルリクエスト時に AI 関連ドキュメントの更新有無をチェックする項目を設けるべきです。

また、大規模なシステム改修の際には、まず AGENTS.md の設計思想セクションを更新し、それをAIに読み込ませてから実装案を出させるという「ドキュメント駆動」のAI開発フローが非常に効果的です。

5.2 セキュリティ：環境変数と認証情報の隠蔽

AIエージェントにプロジェクトを理解させる際、最も注意すべきはセキュリティです。

.gitignoreの遵守：AGENTS.md 自体はリポジトリにコミットされます。絶対にAPIキー、DBパスワード、秘密鍵を記述しないでください。
データのマスキング：AIにログ解析をさせる場合でも、顧客の個人情報（メールアドレス、電話番号等）が含まれないよう、ファイル内で「データの秘匿化ルール」を明文化しておきます。

セキュリティリスクの管理は、SaaS導入時におけるアカウント管理とも共通します。退職者が発生した際のアカウント削除漏れなどは、技術的な対策だけでなく運用フローでの解決が求められます。SaaS増えすぎ問題と退職者のアカウント削除漏れを防ぐ。Entra ID・Okta・ジョーシスを活用した自動化アーキテクチャで語られているような自動化の思想は、AIドキュメントの鮮度管理にも応用可能です。

5.3 手順通りにいかない場合のエラー対処

AIが CLAUDE.md や AGENTS.md を無視して回答を続ける場合、以下の点を確認してください。

ファイルの配置場所：必ずルートディレクトリに置いていますか？サブディレクトリ（docs/ 内など）にあると、ツールによっては無視される場合があります。
ファイルサイズ：あまりにも長大な（数万文字の）指示を書くと、重要なルールが「埋もれる」ことがあります。簡潔に箇条書きでまとめるのがコツです。
トークン制限：コンテキストウィンドウが狭い古いモデルを使用している場合、ファイルの内容を読み飛ばすことがあります。最新の Claude 3.5 Sonnet 等の使用を前提としてください。

6. まとめ：AIとの協調を前提とした開発アーキテクチャの構築

AGENTS.md や CLAUDE.md の作成は、単なる「AIへのメモ書き」ではありません。それは、チームが持つ設計思想、技術選定の意図、そして運用の規律を言語化するプロセスそのものです。

これらが整備されたプロジェクトでは、AIは単なる「コード書き」から、「仕様を理解し、ルールを遵守し、ミスを指摘してくれる頼もしいペアプログラマー」へと進化します。人による指示出しのコストを下げ、開発速度を最大化するためにも、まずは最小構成の CLAUDE.md から導入してみることを強く推奨します。

AIの活用範囲を広げ、マーケティングや顧客獲得の領域まで最適化したい場合は、広告×AIの真価を引き出す。CAPIとBigQueryで構築する「自動最適化」データアーキテクチャのような、より高度なデータ活用基盤の検討も有効です。開発からマーケティングまで、AIが正しく判断できる「コンテキスト」を用意すること。それが、これからのIT実務者に求められる最重要スキルの一つです。

7. 導入後の形骸化を防ぐ「運用チェックリスト」

ファイルを配置した直後はAIの精度が向上しますが、開発が進むにつれてコードベースとドキュメントの乖離（ドキュメントの腐敗）が発生します。チームで運用を定着させるために、以下のチェックポイントを定期的に確認してください。

コマンドの動作確認：CLAUDE.md に記述したテストやビルドのコマンドが、依存ライブラリのアップデート後も正しく動作するか。
ディレクトリ構造の同期：リファクタリングでフォルダ構成を変更した際、AGENTS.md の構造定義も修正されているか。
「AIの癖」のフィードバック：AIが特定の誤りを繰り返す場合、それを「禁止事項」セクションに即座にフィードバックしているか。

特に大規模な開発では、個々のファイルに指示を分散させず、プロジェクトの「真実のソース」をどこに置くかを明確にする必要があります。これは、モダンデータスタックを用いたデータ基盤構築において、dbtなどでメタデータを一元管理する思想と共通しています。

8. ツール別・設定ファイルの責務分解（比較表）

利用するIDEやエージェントによって、最適なファイル名や記述すべき内容が異なります。チーム内で「どのファイルに何を書くか」の合意形成に役立ててください。

ファイル名	主な用途・強み	記述すべき内容の例
CLAUDE.md	Claude Code連携、CLI操作の自動化	`make test` などの実行コマンド、型チェック、ビルド手順
.cursorrules	Cursorのチャット・Compose機能の最適化	エディタ内でのコード生成スタイル、優先するUIコンポーネント
AGENTS.md	汎用エージェントへのコンテキスト共有	ビジネスドメインの知識、システム全体のアーキテクチャ図（テキスト）
.github/copilot-instructions.md	GitHub Copilot Extensions用	リポジトリ固有のコーディングパターン、レビュー時の観点

9. 参考リソースと公式ドキュメント

これらの設定ファイルは仕様が日々アップデートされています。最新のベストプラクティスについては、以下の公式リソースを適宜参照してください。

Claude Code Official Documentation (Anthropic)：CLAUDE.mdの仕様詳細が記載されています。
Cursor Documentation：.cursorrulesなどのカスタムルールに関するガイド。

また、AIへのコンテキスト共有を「社内全体のデータ活用」という広い視点で見れば、SFAやCRMとのデータ連携設計も無視できません。SFA・CRM・MA・Webの全体設計図を理解しておくことで、AIエージェントに「どのビジネスデータを、どの規約で扱うべきか」をより深く指示できるようになります。

ご相談・お問い合わせ

本記事の内容を自社の状況に当てはめたい場合や、導入・運用の設計を一緒に整理したい場合は、当社までお気軽にご相談ください。担当より折り返しご連絡いたします。

お問い合わせフォームへ

aurant technologies 編集

上場企業からスタートアップまで、数多くのデータ分析基盤構築・AI導入プロジェクトを主導。単なる技術提供にとどまらず、MA/CRM（Salesforce, Hubspot, kintone, LINE）導入によるマーケティング最適化やバックオフィス業務の自動化など、常に「事業数値（売上・利益）」に直結する改善実績多数。

← ブログ一覧へ戻る

← 前の記事

No Image