🎊

WindsurfでAGENTS.mdが使えるようになっていました。

に公開
ポエム
IDE
Windsurf
idea

はじめに

明けましておめでとうございます。
SAP 試験など年末ドタバタしていて、気づけば、もう1月中旬になってしまいました。

新年度の新たな取り組みなどが始まる中、Windsurf 記事がほったらかしに。。。

今更ですが、記事を書きながらアップデートのキャッチアップを行っていきたいと思います😭
みなさんは今までのアプデのおさらいだと思って、見ていただけたらと思います。

今回はいつのまにか使えるようになっていたAGENTS.mdについてです。

Windsurf のアップデート

遡ること 2025/10/22 のアップデートで、AGENTS.mdが使えるようになっています。

Windsurf のアップデート

October... 私の Windsurf 知識は 2025 年の 10 月で止まっています😱

AGENTS.md とは

そもそも、AGENTS.md とは何？ということで、Windsurf の公式ドキュメントの記載を読んでみました。

  • カスケードへスコープ化された指示を提供する。

    • ファイルの配置場所に依存して、振る舞いが変わる。

  • AGENTS.md（またはagents.md）ファイルを置くことで、Windsurf の Cascade が自動でそれを読み込む。

    • 修正中のファイルからワークスペースのルート（非gitの場合）または、gitリポジトリのルートまで遡って読み込みます。

スコープ化の部分について、詳細にみていきましょう。

スコープ化された指示

このスコープ化と言っているのは、AGENTS.mdファイルの配置場所によって、適用されるスコープが異なるということです。
たとえば、下記のフォルダ構造があるとしましょう。（projectフォルダがプロジェクトルートだとします。）

project/
├── AGENTS.md          # プロジェクト全体に適用
├── src/
│   ├── AGENTS.md      # src配下のみに適用
│   └── components/
│       └── AGENTS.md  # components配下のみに適用
└── tests/
    └── AGENTS.md      # tests配下のみに適用

project/src/componentsフォルダ配下のAGENTS.mdは、components配下のファイルのみに適用されます。

srcフォルダ配下のAGENTS.mdは、src配下（サブフォルダを含む）のファイルのみに適用されます。

プロジェクトルート（projectフォルダ）にあるAGENTS.mdは、プロジェクト全体に適用されます。

つまり、project/src/components/フォルダ配下のファイルに対して適用されるAGENTS.mdは、

  • project/フォルダ配下のAGENTS.md
  • project/src/フォルダ配下のAGENTS.md
  • project/src/components/フォルダ配下のAGENTS.md
    となります。

AGENTS.mdに記載する指示は、配置するフォルダ（サブフォルダ含む）のファイルに適用されるルールのみを書くのがいいでしょう。

試してみる

では、上記のフォルダ構造を使って実際に試してみましょう。
それぞれのAGENTS.mdファイルに、新規ファイル作成時に特定の文字列を追記する指示を書きます。

例として、project/AGENTS.mdには以下のような内容を記載します。

project/AGENTS.md
# Project Root Agent Instructions

プロジェクト全体に適用される指示です。

新規ファイルを作成する際は、必ず以下の文字列を追記してください：

```HelloWorld_Root```

この文字列が含まれていれば、ルートレベルのAGENTS.mdが適用されています。

同様に、他のフォルダのAGENTS.mdにも以下の文字列を追記する指示を記載しました。

  • project/src/AGENTS.md → HelloWorld_Src
  • project/src/components/AGENTS.md → HelloWorld_Components
  • project/tests/AGENTS.md → HelloWorld_Tests

これで、特定のフォルダに新規ファイルが作られると、そのフォルダと親フォルダ（祖先を含む）のAGENTS.mdで指示した文言が追記されて、新規ファイルが作成されるはずです。

project/src/components/フォルダ配下にCascadeで指示をして、新規ファイルを作成してみましょう。
Cascadeに新規ファイル作成を依頼

できたファイルが下記です。
新規ファイル作成結果

HelloWorld_RootとHelloWorld_SrcとHelloWorld_Componentsが含まれていることがわかります。
親フォルダのAGENTS.mdの指示が正しく適用されています。

project/testsフォルダ配下にも新規テキストファイルを作成してみました。
testsフォルダに新規テキストファイルを追加
testsフォルダでも同様に、期待通りの動作を確認できました。

AGENTS.md のベストプラクティス

Windsurf の公式ドキュメントによると、下記がベストプラクティスとされています。

配置ディレクトリの目的に関係のある指示を書くこと

AGENTS.md は配置されたディレクトリ配下のファイルのみに適用（スコープが絞られる）されます。
そのため、AGENTS.md が配置されたディレクトリの目的に関係する指示を書くことが推奨されています。

わかりやすい記載形式を使用すること

箇条書きや、ヘッダー、コードブロックを適切に使うことで、Cascade が指示に従いやすくなります。

具体的に記載すること

曖昧なガイドラインよりも、具体的な例や明示的な指示を書くことが推奨されます。

冗長性を排除すること

上記で実験した通り、Cascade は現在のファイルの場所の親フォルダ（祖先含む）の AGENTS.md の指示も適用します。
そのため、親フォルダ（祖先含む）の AGENTS.md ファイルとサブディレクトリの AGENTS.md ファイルの指示を重複させないことが推奨されます。

Windsurf の rules との違い

Windsurf の rule も AGENTS.md と同じで、コーディングルールや、Cascade への指示を記載するものです。

AGENTS.md は適用範囲がスコープ化される点など明らかに異なる点もありますが、一旦 Rules と、どう違うのか整理してみましょう。
これも公式ドキュメントがまとめてくれています。

特徴 AGENTS.md Windsurf Rules
配置場所 プロジェクトディレクトリ内 .windsurf/rules/またはグローバル
スコープ ファイルの位置に基づいて自動適用 手動で設定（glob, always on, model decision, manual）
フォーマット プレーンなマークダウン フロントマター付きマークダウン
  • AGENTS.md はディレクトリごとのルールのために使用
  • Windsurf rules は横断的な関心事や複雑なアクティベーションロジックに使用
    することが推奨されています。

複雑なアクティベーションロジックとは何を指しているのかと思って、私がClaudeさんに問い合わせたところ下記の回答をもらいました。

「complex activation logic」= いつルールを発動させるかの複雑な条件設定です。

つまり、複雑な条件でルールを起動したい場合などは、Windsurf rules の方が適しているということでしょう。

まとめ

AGENTS.md はオープンスタンダードで、Claude Code、Codex、Cursor などでも使えます。
ツールによって扱いが異なる場合もありますが、ひとまず Windsurf での AGENTS.md の動作紹介でした。

時代に取り残されているゴリラですが、追いつけないほどの差ではないので、これから全力ダッシュして最新アップデートまで追っていきたいです。
では、また次回。

GitHubで編集を提案

Discussion