メインコンテンツへスキップ
AGENTS.md ファイルは、プロジェクト内での配置場所に応じて自動的に適用される、コンテキスト対応の指示を Cascade に与えるためのシンプルな手段です。ディレクトリごとのコーディングガイドライン、アーキテクチャ上の判断、プロジェクトの慣習などを定義するのに特に有用です。

​
仕組み

AGENTS.md ファイル (または agents.md) を作成すると、Windsurf は自動的にそれを検出し、.windsurf/rules/ を支えるものと同じ Rules エンジンに取り込みます。違うのは、アクティベーションモードがフロントマターではなく、ファイルの場所から推定される点です。
  • ルートディレクトリ: 常時有効のルールとして扱われます — メッセージごとに、内容全体が Cascade のシステムプロンプトに含まれます。
  • サブディレクトリ: <directory>/** という自動生成パターンを持つ glob ルールとして扱われます — その内容は、Cascade がそのディレクトリ内のファイルを読み取ったり編集したりするときにのみ適用されます。
このような場所ベースのスコープ設定により、AGENTS.md は単一のグローバル設定ファイルを煩雑にすることなく、対象を絞ったガイダンスを提供するのに最適です。

​
AGENTS.md ファイルの作成

任意のディレクトリに AGENTS.md または agents.md という名前のファイルを作成するだけです。このファイルは特別なフロントマターを必要としない、プレーンな Markdown 形式で記述します。

​
構成例

my-project/
├── AGENTS.md                    # プロジェクト全体のグローバル指示
├── frontend/
│   ├── AGENTS.md                # フロントエンドコード固有の指示
│   └── src/
│       └── components/
│           └── AGENTS.md        # コンポーネント固有の指示
├── backend/
│   └── AGENTS.md                # バックエンドコード固有の指示
└── docs/
    └── AGENTS.md                # ドキュメント用の指示

​
コンテンツの例

次は、React コンポーネントのディレクトリ用の AGENTS.md ファイルの一例です。 
# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports

​
検出とスコープ設定

Windsurf は、ワークスペース内の AGENTS.md ファイルを自動的に検出します。
  • ワークスペースのスキャン: ワークスペース内およびそのサブディレクトリ内のすべての AGENTS.md ファイルを検出します
  • Git リポジトリ対応: Git リポジトリの場合、Windsurf は Git のルートまで親ディレクトリも検索します
  • 大文字小文字の区別なし: AGENTS.md と agents.md の両方が認識されます

​
自動スコープ設定

AGENTS.md の主な利点は、ファイルの場所に基づいてスコープが自動的に適用されることです。
ファイルの場所スコープ
ワークスペースのルートすべてのファイルに適用 (常に有効)
/frontend//frontend/** 内のファイルを扱うときに適用
/frontend/components//frontend/components/** 内のファイルを扱うときに適用
つまり、異なる階層に複数の AGENTS.md ファイルを配置でき、それぞれのディレクトリごとに、より具体的なガイダンスを提供できます。

​
ベストプラクティス

AGENTS.md ファイルを最大限活用するには、次の点に留意してください。
  • 指示内容を絞る: 各 AGENTS.md には、そのディレクトリの目的に関連する指示のみを記載する
  • わかりやすいフォーマットを使う: 箇条書き、見出し、コードブロックを使うと、Cascade が指示に従いやすくなる
  • 具体的に書く: あいまいなガイドラインよりも、具体的な例や明示的な規約のほうが効果的
  • 重複を避ける: サブディレクトリのファイルにグローバルな指示を繰り返し記載しない。サブディレクトリは親ディレクトリからそれらの指示を継承する

​
コンテンツガイドライン

# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints

# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices

​
Rules との比較

AGENTS.md と Rules はどちらも Cascade への指示を定義しますが、用途が異なります。
機能AGENTS.mdRules
位置プロジェクトディレクトリ内.windsurf/rules/ またはグローバル
スコープファイルの場所に基づき自動手動 (glob、常時有効、model decision、手動)
フォーマットプレーンな Markdownfrontmatter 付きの Markdown
適している用途ディレクトリ固有のルール・規約横断的な設定・ポリシー、複雑な有効化ロジック
シンプルで場所ベースの指示を設定したい場合は AGENTS.md を使用します。指示がいつ・どのように適用されるかをより細かく制御したい場合は Rules を使用します。