AI コーディングのプロジェクトルール：AGENTS.md、CLAUDE.md、Cursor Rules、Specs
AGENTS.md、CLAUDE.md、Cursor Rules、MCP、specs、検証ゲートがどのように責任を分担するかを学び、エージェントを役立てつつリリースの主導権は渡さない方法。
AI コーディングツールは、リポジトリが どのように作業を進めるべきか を説明しているときにうまく振る舞います。その指針は AGENTS.md、CLAUDE.md、Cursor Rules、MCP 設定、specs、検証ゲートといった形で現れます。
これらのファイルは指示であり契約です。人間によるレビューや green build の代わりにはなりません。
直接的な回答
| アーティファクト | 主な役割 |
|---|---|
AGENTS.md / CLAUDE.md / Cursor Rules | プロジェクトの規約、境界、推奨コマンドをエージェントに伝える |
| Specs / タスクブリーフ | その変更にとっての「完了」の定義を示す |
| MCP / ツール設定 | エージェントが呼び出せる外部ツールを制御する |
| 検証ゲート | テスト、ビルド、lint、レビューチェックリストで変更を証明する |
短く、強制力のあるルールを使ってください。誰も更新しない長文のエッセイは、無視されるノイズになります。
非技術者のビルダーは、まず コントロールを失わない Vibe Coding を読んでください。リリース前の確認には ワークフローチェックリスト を使ってください。
このガイドが役立つ場面
- エージェントが誤ったフォルダを編集し続けたり、勝手に新しいパターンを作り出したりしている。
- チーム内で、どの指示ファイルが権威を持つのか意見が分かれている。
- 無制限なネットワークやリポジトリの権限を渡さずに MCP を有効化したい。
- 「エージェントへの指針」と「マージ要件」の間に明確な線を引きたい。
関連するプラグインとスキルは AI Coding プラグインディレクトリ で確認できます。
指示ファイル：境界であり、魔法ではない
AGENTS.md
一般的には リポジトリレベルのエージェント向けブリーフ として使われます。スタック、構成、実行必須のコマンド、禁止事項、より詳しいドキュメントへのリンクなどです。
良いコンテンツ
- パッケージマネージャーと必要な Node/Java/Python のバージョン
- テストと lint の実行方法
- エージェントが手を出すべきでないフォルダ
- PR やコミットの命名方法
悪いコンテンツ
- プロダクトのマーケティング文をコピペしただけの内容
- シークレットや本番 URL
- 誰も保守していない矛盾したルール
CLAUDE.md
多くの場合、Claude 向けのプロジェクト指針として使われます。AGENTS.md と同じように、最新で、具体的で、短く保ってください。両方が存在する場合は、共有ルールについてどちらが優先されるかを明示するか、意図的に同期させてください。
Cursor Rules
Cursor Rules は通常、エディタ/エージェントスコープ の指示です（プロジェクトルールまたはユーザールール）。次のような用途に使います。
- コーディングスタイルとフレームワークの規約
- 「完了と主張する前に必ず X を実行する」
- 追加の注意が必要なパス（認証、決済、マイグレーション）
チームメイトが見られない個人のユーザールールだけに、重要なセキュリティ方針を隠してはいけません。
Specs とタスクの分割
Specs は 何を 作り、どう受け入れるかに答えます。ルールは、作業中にエージェントが どう 振る舞うべきかに答えます。
有用なミニ spec には次が含まれます。
- ユーザーに見える成果
- 対象外の範囲
- 変更が及びそうなファイルや領域
- テストまたは手動確認の手順
- リスクがある場合のロールバックの注記
spec がないエージェントはスコープを勝手に作り出します。spec がない人間は、事後に議論することになります。
MCP とツールアクセス
MCP（および類似のツールブリッジ）は、エージェントに外部システムを呼び出させます。これは強力であると同時に危険です。
ツールを有効化する前に
- まず読み取り専用アクセスを優先する
- 可能な限りホストとコマンドをアローリストで制限する
- git にコミットされる MCP 設定に、本番のシークレットを絶対に貼らない
- 重要な変更については、どのツールが実行されたかをログに残す
MCP の設定は 能力の制御 であり、プロダクトドキュメントではありません。
検証ゲート
ルールは「テストを実行して」と言えます。ゲートは 証拠を要求します。
npm test/npm run build（あるいはスタックに応じた同等コマンド）- 該当する場合の lint と型チェック
- シークレットや予期しないファイル変更差分のレビュー
- AI コードレビュー や ship checklist のようなチェックリスト
AI コーディングエージェントの検証ゲート も参照してください。
green なゲートがなければ「完了」ではありません。
実践的な導入順序
- コマンドと禁止領域を記した 1 ページの
AGENTS.md（またはそれに相当するもの）を書く。 - ツール固有の追加事項に限って Cursor Rules /
CLAUDE.mdを追加する。重複した「ルール戦争」は避ける。 - 非自明なタスクには短い spec を必須にする。
- MCP ツールは狭い範囲で有効化する。
- マージをエージェントの自信ではなく検証ゲートに依存させる。
限界
- ファイル名やプロダクト機能は進化します。Cursor、Claude Code、Codex など、最新のドキュメントで必ず確認してください。
- ルールは、曖昧なプロダクトのオーナーシップを解決できません。
- 長すぎるルール集は読み飛ばされます。すべてを貼り付けるより、更新され続ける文書へのリンクを優先してください。
FAQ
すべての種類のファイルが必要か？
いいえ。まず 1 つの権威あるブリーフと、実際のタスクのための specs から始めてください。プロダクトが必要とする場合にのみ、ツール固有のファイルを追加します。
シークレットはどこに置くべきか？
環境設定とシークレット管理サービスに置いてください。ルールファイル、プロンプト、コミットされる MCP 設定には置きません。