クイックサマリー: AIコーディングエディタ Windsurf が、エージェント向け指示ファイルのオープン標準「AGENTS.md」に対応しました。プロジェクト内の任意のフォルダに AGENTS.md を置くだけで、AIエージェント Cascade がその階層以下にスコープを絞った指示として自動で読み込みます。Codex CLI や Cursor など複数の AI コーディングツールで使われている形式のため、ツールをまたいだ指示ファイルの共通化にも役立つアップデートです。
「Windsurf 用の .windsurfrules、Claude Code 用の CLAUDE.md、Codex 用の AGENTS.md……」と、AIツールごとに指示ファイルを別々にメンテナンスすることに消耗していませんか？ ツールを乗り換えるたびにルールを書き直すのは、地味ながら確実に開発の負担になる課題です。
Windsurf の AGENTS.md 対応は、この課題を軽減する一歩です。オープン標準の形式をそのまま読み込めるため、他ツールと指示ファイルを共通化しやすくなります。
この記事でわかること:
- Windsurf の AGENTS.md 対応の概要と、対応バージョンの目安
- フォルダ階層ごとに指示を出し分ける「スコープ化」の仕組みと動作確認の手順
- 既存の Windsurf Rules（.windsurf/rules/）との使い分け基準
- Claude Code・Codex CLI など他ツールとの指示ファイル共通化の考え方
なお AGENTS.md はオープン標準の仕様であり、Windsurf 本体はクローズドソースの商用エディタ（無料プランあり）です。料金の詳細は公式サイトで確認してください。
WindsurfのAGENTS.md対応とは
Windsurf は、AIエージェント「Cascade」を搭載したAIコーディングエディタです。2025年10月22日のアップデートで、プロジェクト内に置いた AGENTS.md（または agents.md）ファイルを Cascade が自動で読み込むようになりました。
公式ドキュメントによると、Cascade は編集中のファイルの位置から、ワークスペースのルート（Gitリポジトリの場合はリポジトリルート）まで親フォルダを遡りながら AGENTS.md を探して読み込みます。つまり特別な有効化操作は不要で、ファイルを置くだけで機能します。
agents.md はもともと OpenAI の Codex などで採用されてきたオープン標準の形式で、Cursor や GitHub Copilot Coding Agent など対応ツールが広がっています。Windsurf の対応により、「AIエージェントへのプロジェクト指示は AGENTS.md に書く」という流れがまた一歩進んだと考えられます。
スコープ化された指示の仕組み
Windsurf の AGENTS.md の最大の特徴は、配置場所によって適用範囲（スコープ）が変わることです。
フォルダ構造と適用範囲の例
project/
├── AGENTS.md # プロジェクト全体に適用
├── src/
│ ├── AGENTS.md # src配下のみに適用
│ └── components/
│ └── AGENTS.md # components配下のみに適用
└── tests/
└── AGENTS.md # tests配下のみに適用このとき project/src/components/ 配下のファイルを編集する場合、ルート・src・components の3階層すべての AGENTS.md が同時に適用されます。子フォルダの指示が親を「上書き」するのではなく、祖先フォルダの指示が積み重なるイメージです。
実際の動作検証レポート
この挙動は解説記事「WindsurfでAGENTS.mdが使えるようになっていました。」（Zenn）で実際に検証されています。同記事では、各階層の AGENTS.md に「新規ファイル作成時に特定の文字列（HelloWorld_Root / HelloWorld_Src / HelloWorld_Components 等）を追記する」という指示を書き、components 配下で Cascade にファイルを作らせたところ、ルート・src・components の3つの文字列がすべて含まれるファイルが生成されたと報告されています。tests 配下でも同様に期待どおり動作したとのことで、スコープ化が仕様どおり機能していることが確認できます。
設定手順と動作確認
手順1: バージョンの確認
AGENTS.md 対応は 2025年10月22日のアップデートで追加されました。それ以前のビルドを使い続けている場合は、まず Windsurf 本体を最新版にアップデートしてください。
手順2: AGENTS.md を配置する
プロジェクトルート（またはスコープを絞りたいフォルダ）に AGENTS.md を作成します。フォーマットはフロントマター不要のプレーンな Markdown です。
# Project Root Agent Instructions
プロジェクト全体に適用される指示です。
- TypeScript は strict モードを前提にコードを書く
- コミットメッセージは Conventional Commits 形式にする手順3: 動作確認
前述の検証レポートと同じ方法が手軽です。AGENTS.md に「新規ファイル作成時に特定の文字列を追記する」といった検証用の指示を一時的に書き、Cascade にファイル作成を指示して、出力にその文字列が含まれるかを確認します。確認できたら検証用の指示は削除してください。
公式ドキュメントのベストプラクティス
Windsurf公式ドキュメントでは、次の4点が推奨されています。
- 配置ディレクトリの目的に関係する指示だけを書く（スコープが絞られるため）
- 箇条書き・見出し・コードブロックで構造化し、Cascade が従いやすくする
- 曖昧なガイドラインではなく具体的な例・明示的な指示を書く
- 親フォルダの AGENTS.md と指示を重複させない（祖先の指示も同時に適用されるため冗長になる）
実際の開発フローでの活用例
スコープ化を活かすと、職種やチーム構成に応じた指示の出し分けができます。
- フロントエンド開発チーム:
src/components/AGENTS.mdに「コンポーネントは PascalCase」「スタイルは Tailwind のユーティリティクラスのみ」といったUI固有のルールを書き、ルートの AGENTS.md には言語やコミット規約などプロジェクト共通ルールだけを残す - QA・テストエンジニア:
tests/AGENTS.mdに「テストは Arrange-Act-Assert 構造」「モックの命名規則」などテスト専用の規約を書く。本体コードの編集時にはこの指示が読み込まれないため、コンテキストの無駄がない - 複数のAI CLIを併用する開発者・受託開発: Codex CLI や Cursor と Windsurf を案件によって使い分けている場合、AGENTS.md を単一の情報源にすれば指示ファイルの二重管理を減らせます。Claude Code 中心の環境なら、CLAUDE.md から AGENTS.md を参照させる構成も検討できます
既存の .windsurfrules や Windsurf Rules を使っている場合も、即時の移行は必須ではありません。まず「ディレクトリ固有のルール」だけを AGENTS.md に切り出し、横断的なルールは Rules に残すのが公式の推奨に沿った移行手順と考えられます。
Windsurf Rules・他ツールの指示ファイルとの比較
公式ドキュメントでは、AGENTS.md と Windsurf Rules の違いが次のように整理されています。大きな違いは①配置場所 ②スコープの決まり方 ③フォーマットの3点です。
| 方式 | 対応ツール | 配置場所 | スコープ・適用方法 | 特徴 |
|---|---|---|---|---|
| AGENTS.md | Windsurf / Codex CLI / Cursor ほか（オープン標準） | プロジェクト内の任意フォルダ | ファイル位置に基づき自動適用 | プレーンMarkdown。ディレクトリごとのルール向き |
| Windsurf Rules | Windsurf | .windsurf/rules/ またはグローバル | 手動設定（glob / always on / model decision / manual） | フロントマター付きMarkdown。複雑な発動条件を設定可能 |
| CLAUDE.md | Claude Code | プロジェクトルート・サブフォルダ・ユーザーホーム | セッション開始時に自動読み込み | Claude Code 標準のプロジェクト指示書 |
| .cursorrules | Cursor（旧方式） | プロジェクトルート | 常時適用 | Cursor では現在 Project Rules / AGENTS.md への移行が進む |
公式ドキュメントの推奨は「ディレクトリごとのルールは AGENTS.md、横断的な関心事や複雑な発動条件（特定のファイルパターンでのみ発動させる等）は Windsurf Rules」という使い分けです。両者は排他ではなく併用できます。
注意点・制約
- 指示内容はLLMに送信されます: AGENTS.md の内容はプロンプトの一部として Cascade のバックエンド（クラウド上のLLM）に送られます。APIキーやシークレットは絶対に書かないでください
- 親フォルダの指示も常に適用される: 子フォルダの AGENTS.md で親の指示を打ち消す用途には向きません。矛盾する指示を書くと挙動が不安定になると考えられます
- ツール間で解釈が異なる場合がある: AGENTS.md はオープン標準ですが、階層スコープの扱いなど細部の挙動はツールごとに異なる可能性があります。共通化する場合は各ツールでの動作確認が必要です
- 強制力はない: Rules や AGENTS.md はあくまで LLM への指示であり、リンターのような確実な強制ではありません。重要な規約は CI やフックでの機械的チェックと併用するのが安全です
- 料金プランごとの機能差については公式サイトで確認してください
まとめ
- Windsurf は 2025年10月22日のアップデートで AGENTS.md に対応し、置くだけで Cascade が自動読み込みするようになりました
- 配置フォルダによって適用範囲がスコープ化され、祖先フォルダの指示と積み重なって適用されます（Zennの検証記事で動作確認済み）
- 使い分けの目安は「ディレクトリ固有のルール = AGENTS.md、横断的・条件付きのルール = Windsurf Rules」。オープン標準のため Codex CLI や Cursor との指示共通化にも活用できます
スコープ化の詳細な仕様や Rules の発動条件については、Windsurf公式ドキュメントを参照してください。
コメント