先に要点
AIコーディングツールを触っていると、AGENTS.mdを読んで、CLAUDE.mdにルールを書く、copilot-instructions.mdを作る といった話が出てきます。
ここでいう .md ファイルは、単なるメモ帳ではありません。AIにプロジェクトの前提、作業ルール、確認手順を渡すためのコンテキスト置き場として使われます。
この記事では、2026年4月19日時点で OpenAI Codex、Claude Code、GitHub Copilot、Cursor の公式情報を確認しながら、AIツールで使うmdファイルとは何か、どのファイルに何を書くべきか、どこから危険になるかを実務目線で整理します。
AIが参照する前提情報そのものを先に押さえたい場合は、AIのコンテキストとは？プロンプト・会話履歴・RAGとの違いを整理 もつながります。
mdファイルとは何か
.md は、Markdown形式のテキストファイルです。
Markdownは、普通のテキストに少しだけ記法を足して、見出し、箇条書き、リンク、表、コードブロックを書きやすくする形式です。
たとえば、次のような内容を書けます。
# プロジェクト概要
このリポジトリは Laravel + MySQL のブログです。
## 作業ルール
- 記事を追加したら品質テストを実行する
- 本番反映前に公開URLを確認する
- ユーザーの依頼文をそのままタイトルに使わない
人間にも読みやすく、AIにも構造を伝えやすいので、AIコーディングツールの指示ファイルとして相性がいいです。
Word文書やPDFよりも差分管理しやすく、Gitでレビューしやすいのも大きな利点です。
AIツールでmdファイルが使われる理由
AIは毎回、何も知らない新人のような状態から作業を始めることがあります。
もちろん、開いているファイルや会話履歴は参照できますが、プロジェクト固有のルールを毎回チャットで説明するのは面倒です。
そこで、mdファイルに次のような情報を書いておきます。
- プロジェクトの概要
- 使っている技術スタック
- ビルド、テスト、デプロイのコマンド
- コーディング規約
- 触ってはいけないファイル
- 本番反映前の確認手順
- よくある失敗と回避策
- セキュリティ上の注意
AIツールがそのファイルを読むと、毎回の作業で同じ前提を渡しやすくなります。
これはAIのコンテキストを整える作業に近いです。AIに「何を作るか」だけでなく、「このプロジェクトではどう作るべきか」まで渡すための仕組みだと考えると分かりやすいです。
代表的なAI向けmdファイル
| ファイル | 主な対象ツール | 役割 |
|---|---|---|
| AGENTS.md | Codex、Copilot agentなど | AIエージェント向けのプロジェクト指示、作業ルール、検証手順を書く |
| CLAUDE.md | Claude Code | CLAUDE.mdとしてプロジェクトルール、開発手順、注意点を書く |
| .github/copilot-instructions.md | GitHub Copilot | リポジトリ全体に適用するCopilot向けカスタム指示を書く |
| .github/instructions/*.instructions.md | GitHub Copilot | 特定のパスやファイル種別に応じた指示を書く |
| .cursor/rules/*.mdc | Cursor | CursorのAgentやInline Editに適用するルールを書く。Markdownにメタデータを足した形式に近い |
| README.md | 人間、AI全般 | プロジェクト概要、セットアップ、使い方を書く。AIにも読ませやすい基本資料になる |
ここで大事なのは、すべてのAIツールが同じmdファイルを自動で読むわけではないことです。
たとえば、CodexではAGENTS.mdが重要になり、Claude CodeではCLAUDE.mdが重要になります。GitHub Copilotでは .github/copilot-instructions.md や .github/instructions/*.instructions.md が使われます。
AGENTS.mdとは
AGENTS.mdは、AIエージェントにプロジェクト固有の指示を渡すためのMarkdownファイルです。
OpenAIのCodex公式ドキュメントでは、Codexが作業前にAGENTS.mdを読み、グローバル指示とプロジェクト固有の指示を重ねて扱うと説明されています。
実務では、次のような内容を書くと効きます。
# Repository Instructions
## Project Overview
- Laravel + MySQL のブログです。
- 記事データは database/content/articles.php で管理します。
## Validation
- 記事を追加したら `php artisan test --filter=ContentQualityGuardTest` を実行します。
- 公開前に `php tools/audit_content_quality.php` を実行します。
## Safety
- ユーザーの既存変更を勝手に戻さないでください。
- 本番反映前に公開URLを確認してください。
AIにとってありがたいのは、抽象的な理念よりも、実際にどのコマンドを打つか、どのファイルを触るか、何をしてはいけないかです。
「品質に気をつける」より「このテストを実行する」の方が、AIは守りやすくなります。
CLAUDE.mdとは
CLAUDE.mdは、Claude Code向けの指示ファイルです。
Claude Codeの公式ドキュメントでは、CLAUDE.mdはプロジェクト、個人、組織単位の永続的な指示として使われ、セッション開始時に読み込まれると説明されています。
書く内容はAGENTS.mdとかなり似ています。
- プロジェクト構成
- よく使うコマンド
- コーディング規約
- テスト方針
- デプロイ手順
- Claudeが過去に間違えたこと
- 次回から毎回守ってほしい注意点
ただし、CLAUDE.mdは「強制設定」ではなく、あくまでAIに渡す文脈です。
公式ドキュメントでも、具体的で短く整理された指示ほど従いやすく、長すぎるファイルはコンテキストを消費して効きにくくなることが示されています。
Copilot instructionsとは
GitHub Copilotでは、リポジトリ全体の指示として .github/copilot-instructions.md を使えます。
GitHub公式ドキュメントでは、リポジトリ全体に効く指示、パスに応じた .instructions.md、AI agents向けのAGENTS.mdなどが整理されています。
Copilot向けには、たとえば次のような指示が向いています。
# Copilot Instructions
- PHPコードはLaravelの既存パターンに合わせてください。
- 新しい依存パッケージを追加する前に理由を説明してください。
- Featureテストがある処理を変更したら、関連テストも更新してください。
- Bladeテンプレートでは既存のCSSクラスを優先してください。
Pull Requestレビューやコード補完で使う場合、実装スタイルをそろえる効果があります。
一方で、長い設計書を丸ごと入れるより、Copilotが実際に迷う判断を短く書く方が効きやすいです。
Cursor rulesとは
Cursorでは、Project Rulesとして .cursor/rules 配下にルールファイルを置く使い方があります。
Cursor公式ドキュメントでは、Project Rulesはコードベース固有の知識、ワークフロー、スタイルやアーキテクチャ上の決定を記録するために使うものとして説明されています。
Cursorのルールは、単純な .md ではなく .mdc 形式で扱われることがあります。
.mdc はMarkdownにメタデータを足したような形式で、どのパスに適用するか、常に適用するか、といった制御を持たせられます。
たとえば、フロントエンドだけに効くルール、APIだけに効くルール、テストだけに効くルールを分けると、AIに渡す文脈を絞りやすくなります。
何を書くべきか
AI向けmdファイルに書くべきなのは、AIが毎回迷うところです。
| 書くとよいもの | 理由 |
|---|---|
| プロジェクト概要 | 何のアプリか分からないまま実装されるのを防ぐ |
| 主要ディレクトリ | AIが関係ない場所を探し回る時間を減らす |
| ビルド・テストコマンド | 変更後に何を確認すべきか明確になる |
| 禁止事項 | 勝手な依存追加、設定変更、データ削除などを防ぎやすい |
| 既存パターン | AIが新しい書き方を持ち込んでコードが散らかるのを防ぐ |
| 本番反映手順 | ローカル変更だけで終わる事故を減らす |
このブログでいえば、記事データの場所、用語集リンクのルール、品質チェック、本番反映手順をmdファイルに書いておくことで、AIが毎回同じ作業品質に近づきます。
これはバイブコーディングで勢いよく作る場合にも重要です。AIに任せるほど、最初に渡すルールの品質が結果に出ます。
書かない方がいいもの
逆に、AI向けmdファイルへ何でも書けばよいわけではありません。
特に秘密情報は絶対に避けます。
AIツールによってはファイル内容がモデルへの入力やログに含まれる可能性があるため、共有リポジトリに書く内容とローカルだけに置く内容は分けるべきです。
クライアント情報や機密情報をAIに入れてよいか迷う場合は、生成AIにクライアント情報を入力していい？契約・機密情報・ログ管理の考え方 も先に確認しておくと安全です。
よくある失敗
1. mdファイルを作っただけで安心する
AGENTS.mdやCLAUDE.mdを作っても、AIが常に完璧に従うわけではありません。
AI向けmdファイルはルールブックというより、強いヒントです。重要な作業では、チャットでも「AGENTS.mdを読んでから進めて」と明示した方が安全です。
2. 長くしすぎる
プロジェクトの歴史、議論、古い仕様、全部のコマンドを詰め込むと、AIが大事な指示を拾いにくくなります。
最初のmdファイルは、短く、具体的に、毎回必要なことだけに絞る方が効きます。
3. 古い内容を放置する
テストコマンドが変わったのに古いまま、デプロイ先が変わったのに古いまま、使っていないディレクトリ構成が残ったまま。
こうなると、AIは古いルールに従って失敗します。AIが間違えたときは、チャットで直すだけでなく、mdファイル側も直すのが大事です。
4. ツールごとの読み込み仕様を混同する
Claude Codeに読ませたいのにAGENTS.mdだけを置く、Copilotに読ませたいのにCLAUDE.mdだけを置く、Cursor向けなのに .cursor/rules ではない場所にルールを書く。
このように、ツールごとの読み込み場所を混同すると、書いたのに効いていない状態になります。
最初に作るならこの形で十分
初めてAI向けmdファイルを作るなら、いきなり完璧な運用ルールを作る必要はありません。
まずは次の形で十分です。
# AI Coding Instructions
## Project
- このリポジトリは〇〇を作るプロジェクトです。
- バックエンドは Laravel、DBは MySQL です。
## Important Files
- アプリコード: `app/`
- ルーティング: `routes/web.php`
- 画面: `resources/views/`
- テスト: `tests/`
## Commands
- テスト: `php artisan test`
- 静的解析: `composer lint`
- フロントビルド: `npm run build`
## Rules
- 既存の実装パターンを優先してください。
- 新しい依存関係を追加する前に理由を説明してください。
- 変更後は関連テストを実行してください。
- 秘密情報をコードやログに出さないでください。
この程度でも、何もない状態よりかなり安定します。
そのうえで、AIが同じ間違いをしたら、1行ずつルールを増やします。最初から巨大なマニュアルを作るより、実際の失敗から育てる方が続きます。
まとめ
AIツールで使うmdファイルは、AIにプロジェクトの前提や作業ルールを渡すための説明書です。
AGENTS.md、CLAUDE.md、copilot-instructions.md、Cursor rulesなど、名前や置き場所はツールによって違いますが、目的はかなり近いです。
重要なのは、AIに「何を作るか」だけでなく、「このプロジェクトではどう作るか」を渡すことです。
ビルド手順、テスト、禁止事項、既存パターン、本番反映手順を書いておくと、AIの作業は安定しやすくなります。
一方で、mdファイルは魔法の設定ではありません。
古いルール、長すぎる指示、秘密情報の混入は逆に危険です。AIが間違えたら、その場のチャットだけで直すのではなく、次回も効くようにmdファイルを育てる。これが、AIコーディングを実務で使いやすくする地味だけど強い運用です。
参考リンク
- OpenAI Developers: Custom instructions with AGENTS.md
- Claude Code Docs: How Claude remembers your project
- GitHub Docs: Adding repository custom instructions for GitHub Copilot
- Cursor Docs: Rules