Windsurfの設定 - AGENTS.mdのソースを表示

== 概要 ==
AGENTS.mdは、Windsurf Cascade向けのディレクトリスコープ型指示ファイルである。<br>
Windsurfでは、Cascadeへの指示を定義する方法として、<u>.windsurf/rules/</u> ディレクトリ (推奨) と <u>AGENTS.md</u> ファイル の2種類の現行形式が存在する。<br>
<br>
AGENTS.mdの主な特徴を以下に示す。<br>
* 通常のMarkdown形式 (特殊なフロントマター不要)
*: 標準的なMarkdown記法で記述可能であり、YAMLフロントマターは任意である。
* ディレクトリスコープ
*: ルートに配置するとプロジェクト全体に適用、サブディレクトリに配置するとその配下のみに適用される。
* 大文字小文字を区別しない
*: agents.md でも認識される。
* Windsurfによる自動検出
*: ワークスペース、サブディレクトリ、Gitルートまで遡って検出される。
* 60以上のAIコーディングツールで互換性を持つオープンフォーマット
*: Linux Foundation傘下のAgentic AI Foundation管理である。
<br>
<center>
{| class="wikitable"
|+ 指示ファイルの比較表
! 種類 !! ファイル/ディレクトリ !! 説明
|-
| .windsurf/rules/ (推奨) || .windsurf/rules/*.md || Wave 8以降の標準形式<br>複数ルールファイルに分割可能で、発動モードによる細かい制御が可能
|-
| AGENTS.md || 任意のディレクトリ/AGENTS.md || ディレクトリスコープ型の指示ファイル<br>ルートに配置すると全体に適用、サブディレクトリに配置するとその配下のみに適用
|-
| .windsurfrules (レガシー) || プロジェクトルート/.windsurfrules || Wave 8以前の形式<br>単一ファイルを置くだけで自動的に読み込まれる
|}
</center>
<br><br>

== AGENTS.mdの基本仕様 ==
==== ファイル形式 ====
AGENTS.mdの基本的なファイル形式を以下に示す。<br>
<br>
* 通常のMarkdown形式
*: 特殊なフロントマター不要である。
* AGENTS.mdの内容はプロンプトの一部としてCascadeに送信される
* 大文字小文字を区別しない
*: agents.mdでも認識される。
* 推奨長さ
*: 300行以下
*: 長すぎるとCascadeのコンテキストを圧迫する。
* フロントマターはオプション
*: name、description等のYAMLフロントマターも記述可能だが必須ではない。
<br>
==== 配置場所と自動検出 ====
AGENTS.mdは、プロジェクトルートまたはサブディレクトリに配置可能である。<br>
<br>
Windsurfの自動検出の仕組みを以下に示す。<br>
* ワークスペース内のAGENTS.mdを自動検出
* サブディレクトリ内のAGENTS.mdも検出
* Gitルートまで遡って検出
<br>
配置したディレクトリの階層に応じて適用範囲が決まる。<br>
<br><br>

== ディレクトリスコープの仕組み ==
AGENTS.mdの適用範囲は、配置場所によって決定される。<br>
<br>
* ルートに配置
*: プロジェクト全体に適用される。
* サブディレクトリに配置
*: その配下のみに適用される。
* 複数のAGENTS.mdが存在する場合
*: 最も近いファイルが優先される。
*: 親ディレクトリの指示と併用される。
<br>
ディレクトリツリーの配置例を以下に示す。<br>
<br>
 プロジェクト/
 ├── AGENTS.md                  # プロジェクト全体に適用
 ├── src/
 │   ├── AGENTS.md              # src/配下に適用 (プロジェクト全体の指示も併用)
 │   ├── frontend/
 │   │   └── AGENTS.md          # frontend/配下に適用
 │   └── backend/
 │       └── AGENTS.md          # backend/配下に適用
 └── tests/
     └── AGENTS.md              # tests/配下に適用
<br>
適用優先順位を以下に示す。<br>
例: /src/frontend/components/Button.tsxファイルを編集する場合<br>
<br>
# /src/frontend/AGENTS.md (最優先)
# /src/AGENTS.md
# /AGENTS.md (最低優先度)
<br><br>

== Windsurfのプロジェクト構成 ==
==== .windsurf/ディレクトリ ====
<u>.windsurf/</u> ディレクトリの各要素を以下に示す。<br>
<br>
* 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の作成時の環境セットアップを自動化する。
<br>
==== グローバル設定 (~/.codeium/windsurf/) ====
グローバル設定は、ユーザのホームディレクトリ配下のパスに保存される。<br>
<br>
* mcp_config.json
*: MCPサーバ設定 (グローバル)
* hooks.json
*: フック設定 (グローバル)
* memories/global_rules.md
*: グローバルルール
* skills/
*: グローバルスキル
<br>
<center>
{| class="wikitable"
|+ 機能別保存場所の比較
! 機能 !! プロジェクト固有 !! グローバル
|-
| ルール (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
|}
</center>
<br>
==== 推奨ディレクトリ構成 ====
推奨プロジェクト構成を以下に示す。<br>
<br>
 プロジェクト/
 ├── .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/
     └── ...
<br><br>

== AGENTS.mdとRulesの関係 ==
AGENTS.md と .windsurf/rules/ の使い分けについて説明する。<br>
<br>
<center>
{| class="wikitable"
|+ AGENTS.md と Rulesの比較
! 項目 !! AGENTS.md !! .windsurf/rules/
|-
| 適用範囲 || ディレクトリスコープ (配置場所で決定) || 発動モードで制御
|-
| ファイル形式 || 通常のMarkdown || Markdownファイル
|-
| 発動モード || 自動 (ディレクトリスコープ) || Manual / Always On / Model Decision / Glob
|-
| ベンダー互換性 || 60以上のAIツールで互換性あり || Windsurf専用
|-
| 文字数制限 || 推奨300行以下 || 個別6,000文字、合計12,000文字
|-
| Git管理 || 推奨 (チームで共有可能) || プロジェクトに含まれる
|}
</center>
<br>
推奨される使い分けを以下に示す。<br>
<br>
* AGENTS.md
*: プロジェクト概要、技術スタック、一般的なコーディングコンテキスト、他のAIツールとも共有する指示に使用する。
* .windsurf/rules/
*: Windsurf固有の制約、発動モードの制御が必要な指示、言語固有のルールに使用する。
<br>
.windsurfrules (レガシー形式) について:<br>
* Wave 8以前の標準形式である。
* 現在も後方互換性として動作する。
* プロジェクトルートに単一ファイルを配置するだけで自動的に読み込まれる。
* 新規プロジェクトでは .windsurf/rules/ への移行が推奨される。
<br><br>

== 記述例 ==
==== プロジェクトルートのAGENTS.md ====
プロジェクトルートのAGENTS.mdの記述例を以下に示す。<br>
<br>
 <syntaxhighlight lang="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
 </syntaxhighlight>
<br>
==== サブディレクトリのAGENTS.md ====
src/frontend/AGENTS.md の記述例を以下に示す。<br>
<br>
 <syntaxhighlight lang="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
 </syntaxhighlight>
<br><br>

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

== 他のAIツールとの比較 ==
<center>
{| class="wikitable"
|+ 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
|}
</center>
<br>
相互互換性の説明を以下に示す。<br>
<br>
* WindsurfとGitHub Copilotは同じAGENTS.mdファイルを共有できる。
* Claude CodeはCLAUDE.mdを優先するが、AGENTS.mdも参照可能である。
* CursorはAGENTS.mdに対応しており、.cursor/rules/ と併用可能である。
* 複数のAIツールを使用するプロジェクトでは、AGENTS.mdでの指示共有が効率的である。
<br><br>

== 関連項目 ==
* [[AIモデル - Windsurf]]
*: Windsurfの総合ページ (機能、設定、ルール等)
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Windsurf,AGENTS.md,Cascade,AI,IDE,Development,Programming,Rules,Configuration,Settings
|description={{PAGENAME}} - WindsurfにおけるAGENTS.mdの設定と使い方
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]