Windsurfの設定 - AGENTS.md

提供: MochiuWiki : SUSE, EC, PCB

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

AGENTS.mdは、Windsurf Cascade向けのディレクトリスコープ型指示ファイルである。
Windsurfでは、Cascadeへの指示を定義する方法として、.windsurf/rules/ ディレクトリ (推奨) と AGENTS.md ファイル の2種類の現行形式が存在する。

AGENTS.mdの主な特徴を以下に示す。

  • 通常のMarkdown形式 (特殊なフロントマター不要)
    標準的なMarkdown記法で記述可能であり、YAMLフロントマターは任意である。
  • ディレクトリスコープ
    ルートに配置するとプロジェクト全体に適用、サブディレクトリに配置するとその配下のみに適用される。
  • 大文字小文字を区別しない
    agents.md でも認識される。
  • Windsurfによる自動検出
    ワークスペース、サブディレクトリ、Gitルートまで遡って検出される。
  • 60以上のAIコーディングツールで互換性を持つオープンフォーマット
    Linux Foundation傘下のAgentic AI Foundation管理である。


指示ファイルの比較表
種類 ファイル/ディレクトリ 説明
.windsurf/rules/ (推奨) .windsurf/rules/*.md Wave 8以降の標準形式
複数ルールファイルに分割可能で、発動モードによる細かい制御が可能
AGENTS.md 任意のディレクトリ/AGENTS.md ディレクトリスコープ型の指示ファイル
ルートに配置すると全体に適用、サブディレクトリに配置するとその配下のみに適用
.windsurfrules (レガシー) プロジェクトルート/.windsurfrules Wave 8以前の形式
単一ファイルを置くだけで自動的に読み込まれる



AGENTS.mdの基本仕様

ファイル形式

AGENTS.mdの基本的なファイル形式を以下に示す。

  • 通常のMarkdown形式
    特殊なフロントマター不要である。
  • AGENTS.mdの内容はプロンプトの一部としてCascadeに送信される
  • 大文字小文字を区別しない
    agents.mdでも認識される。
  • 推奨長さ
    300行以下
    長すぎるとCascadeのコンテキストを圧迫する。
  • フロントマターはオプション
    name、description等のYAMLフロントマターも記述可能だが必須ではない。


配置場所と自動検出

AGENTS.mdは、プロジェクトルートまたはサブディレクトリに配置可能である。

Windsurfの自動検出の仕組みを以下に示す。

  • ワークスペース内のAGENTS.mdを自動検出
  • サブディレクトリ内のAGENTS.mdも検出
  • Gitルートまで遡って検出


配置したディレクトリの階層に応じて適用範囲が決まる。


ディレクトリスコープの仕組み

AGENTS.mdの適用範囲は、配置場所によって決定される。

  • ルートに配置
    プロジェクト全体に適用される。
  • サブディレクトリに配置
    その配下のみに適用される。
  • 複数のAGENTS.mdが存在する場合
    最も近いファイルが優先される。
    親ディレクトリの指示と併用される。


ディレクトリツリーの配置例を以下に示す。

プロジェクト/
├── AGENTS.md                  # プロジェクト全体に適用
├── src/
│   ├── AGENTS.md              # src/配下に適用 (プロジェクト全体の指示も併用)
│   ├── frontend/
│   │   └── AGENTS.md          # frontend/配下に適用
│   └── backend/
│       └── AGENTS.md          # backend/配下に適用
└── tests/
    └── AGENTS.md              # tests/配下に適用


適用優先順位を以下に示す。
例: /src/frontend/components/Button.tsxファイルを編集する場合

  1. /src/frontend/AGENTS.md (最優先)
  2. /src/AGENTS.md
  3. /AGENTS.md (最低優先度)



Windsurfのプロジェクト構成

.windsurf/ディレクトリ

.windsurf/ ディレクトリの各要素を以下に示す。

  • rules/
    ルールファイル (.windsurf/rules/*.md)
    Wave 8以降の標準形式である。
    複数ルールファイルに分割可能である。
    4つの発動モード (Manual、Always On、Model Decision、Glob) を持つ。
  • workflows/
    ワークフローファイル (.windsurf/workflows/*.md)
    スラッシュコマンド (/workflow-name) で呼び出す反復タスクの自動化である。
  • skills/
    スキルディレクトリ (.windsurf/skills/<skill-name>/)
    SKILL.md + 支援ファイル群で構成される。
    複雑な多段階タスクを実行する。
  • hooks.json
    フック設定である。
    Worktreeの作成時の環境セットアップを自動化する。


グローバル設定 (~/.codeium/windsurf/)

グローバル設定は、ユーザのホームディレクトリ配下のパスに保存される。

  • mcp_config.json
    MCPサーバ設定 (グローバル)
  • hooks.json
    フック設定 (グローバル)
  • memories/global_rules.md
    グローバルルール
  • skills/
    グローバルスキル


機能別保存場所の比較
機能 プロジェクト固有 グローバル
ルール (Rules) .windsurf/rules/ ~/.codeium/windsurf/memories/global_rules.md
スキル (Skills) .windsurf/skills/ ~/.codeium/windsurf/skills/
ワークフロー (Workflows) .windsurf/workflows/ (なし)
AGENTS.md 任意のディレクトリ (なし)
MCP設定 (なし) ~/.codeium/windsurf/mcp_config.json
フック設定 .windsurf/hooks.json ~/.codeium/windsurf/hooks.json


推奨ディレクトリ構成

推奨プロジェクト構成を以下に示す。

プロジェクト/
├── .windsurf/
│   ├── hooks.json
│   ├── rules/
│   │   ├── japanese-output.md
│   │   ├── coding-standards.md
│   │   └── qt-development.md
│   ├── workflows/
│   │   └── research.md
│   └── skills/
│       └── deploy-production/
│           ├── SKILL.md
│           └── deployment-checklist.md
├── .windsurfrules                  # レガシー形式 (任意)
├── AGENTS.md                       # ディレクトリスコープ型の指示
└── src/
    ├── AGENTS.md                   # src/配下のみに適用
    └── ...

~/.codeium/windsurf/                # グローバル設定 (ホームディレクトリ配下)
├── mcp_config.json
├── hooks.json
├── memories/
│   └── global_rules.md
└── skills/
    └── ...



AGENTS.mdとRulesの関係

AGENTS.md と .windsurf/rules/ の使い分けについて説明する。

AGENTS.md と Rulesの比較
項目 AGENTS.md .windsurf/rules/
適用範囲 ディレクトリスコープ (配置場所で決定) 発動モードで制御
ファイル形式 通常のMarkdown Markdownファイル
発動モード 自動 (ディレクトリスコープ) Manual / Always On / Model Decision / Glob
ベンダー互換性 60以上のAIツールで互換性あり Windsurf専用
文字数制限 推奨300行以下 個別6,000文字、合計12,000文字
Git管理 推奨 (チームで共有可能) プロジェクトに含まれる


推奨される使い分けを以下に示す。

  • AGENTS.md
    プロジェクト概要、技術スタック、一般的なコーディングコンテキスト、他のAIツールとも共有する指示に使用する。
  • .windsurf/rules/
    Windsurf固有の制約、発動モードの制御が必要な指示、言語固有のルールに使用する。


.windsurfrules (レガシー形式) について:

  • Wave 8以前の標準形式である。
  • 現在も後方互換性として動作する。
  • プロジェクトルートに単一ファイルを配置するだけで自動的に読み込まれる。
  • 新規プロジェクトでは .windsurf/rules/ への移行が推奨される。



記述例

プロジェクトルートのAGENTS.md

プロジェクトルートのAGENTS.mdの記述例を以下に示す。

 # Project: MyApp
 
 ## Overview
 TypeScript + React 18のWebアプリケーション
 バックエンドはNode.js + Express
 
 ## Tech Stack
 - Frontend: React 18, TypeScript, Vite
 - Backend: Node.js, Express, PostgreSQL
 - Testing: Jest, React Testing Library
 - CI/CD: GitHub Actions
 
 ## Commands
 - `npm run dev` - 開発サーバー起動
 - `npm test` - テスト実行
 - `npm run build` - プロダクションビルド
 - `npm run lint` - リント実行
 
 ## Project Structure
 - `src/frontend/` - Reactコンポーネント
 - `src/backend/` - APIエンドポイント
 - `tests/` - テストコード
 - `docs/` - ドキュメント
 
 ## Coding Conventions
 - 関数名: camelCase
 - コンポーネント名: PascalCase
 - 定数: UPPER_SNAKE_CASE
 - ファイル名: kebab-case


サブディレクトリのAGENTS.md

src/frontend/AGENTS.md の記述例を以下に示す。

 # Frontend Guidelines
 
 ## Component Conventions
 - 関数コンポーネントのみ使用 (クラスコンポーネント禁止)
 - カスタムフックは hooks/ ディレクトリに配置
 - スタイルはCSS Modulesを使用
 
 ## State Management
 - グローバル状態: React Context + useReducer
 - ローカル状態: useState
 - 非同期データ: React Query (TanStack Query)
 
 ## Testing
 - コンポーネントテスト: React Testing Library
 - フック テスト: @testing-library/react-hooks
 - テストファイル: *.test.tsx



推奨される事柄

AGENTS.mdの記述における推奨される事柄を以下に示す。

AGENTS.mdの効果的なルール記述
ポイント 説明
簡潔さの重要性 300行以下を推奨
長すぎるとCascadeのコンテキストを圧迫する。
WHY / WHAT / HOW の3要素 プロジェクトの目的 (WHY)、技術スタック (WHAT)、コーディング規約 (HOW) を含める。
箇条書き・ヘッダー・コードブロックを活用 構造化された形式がCascadeの理解を助ける。
汎用的でない指示は Rules を使用 Windsurf固有の制約 (発動モード等) が必要な指示は .windsurf/rules/ に記載する。
具体的な例と明示的な慣例 抽象的な説明より具体的なコード例・コマンドを優先する。
コマンドを早期配置 ビルド・テスト・リントのコマンドをファイル前半に記載する。
反復的改善 最小限から始め、Cascadeの誤りに応じて指示を追加する。



他のAIツールとの比較

AIツール間のAGENTS.md比較
項目 Windsurf AGENTS.md Claude Code CLAUDE.md GitHub Copilot AGENTS.md Cursor
ファイル名 AGENTS.md CLAUDE.md AGENTS.md .cursor/rules/*.mdc
配置場所 任意のディレクトリ 任意のディレクトリ 任意のディレクトリ .cursor/rules/
ネスト対応 あり (最も近いファイル優先) あり (親と自動マージ) あり (最も近いファイル優先) なし
フォーマット 標準Markdown 標準Markdown 標準Markdown MDC (frontmatter + Markdown)
ベンダー中立 はい (60以上のツール対応) いいえ (Claude Code専用) はい (60以上のツール対応) いいえ (Cursor専用)
発動モード 自動 (ディレクトリスコープ) 自動 (ディレクトリスコープ) 自動 (ディレクトリスコープ) Manual / Always On / Auto Attached


相互互換性の説明を以下に示す。

  • WindsurfとGitHub Copilotは同じAGENTS.mdファイルを共有できる。
  • Claude CodeはCLAUDE.mdを優先するが、AGENTS.mdも参照可能である。
  • CursorはAGENTS.mdに対応しており、.cursor/rules/ と併用可能である。
  • 複数のAIツールを使用するプロジェクトでは、AGENTS.mdでの指示共有が効率的である。



関連項目



「http://mochiuwiki.e2.valueserver.jp/index.php?title=Windsurfの設定_-_AGENTS.md&oldid=14422」から取得