Wiki: /* 推奨される事柄 */

2026-02-22T22:10:32Z

推奨される事柄

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

Wiki: /* ベストプラクティス */

2026-02-22T22:09:01Z

ベストプラクティス

← 古い版		2026年2月23日 (月) 07:09時点における版
264行目:		264行目:
	<br><br>		<br><br>

	== ~~ベストプラクティス~~ ==		== 推奨される事柄 ==
	AGENTS.~~mdの記述におけるベストプラクティスを以下に示す。~~<br>		AGENTS.mdの記述における推奨される事柄を以下に示す。<br>
	<br>		<br>
	* 簡潔さの重要性		* 簡潔さの重要性

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

AGENTS.mdの主な特徴を以下に示す。
* 通常のMarkdown形式 (特殊なフロントマター不要) *: 標準的なMarkdown記…」

2026-02-09T03:37:42Z

ページの作成:「== 概要 == AGENTS.mdは、Windsurf Cascade向けのディレクトリスコープ型指示ファイルである。 Windsurfでは、Cascadeへの指示を定義する方法として、.windsurf/rules/ ディレクトリ (推奨) と AGENTS.md ファイルの2種類の現行形式が存在する。 AGENTS.mdの主な特徴を以下に示す。 * 通常のMarkdown形式 (特殊なフロントマター不要) *: 標準的なMarkdown記…」

新規ページ

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

== 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ファイルを編集する場合 
 
# /src/frontend/AGENTS.md (最優先)
# /src/AGENTS.md
# /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/
*: グローバルスキル
 
<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>
 
==== 推奨ディレクトリ構成 ====
推奨プロジェクト構成を以下に示す。 
 
プロジェクト/
├── .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/ の使い分けについて説明する。 
 
<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>
 
推奨される使い分けを以下に示す。 
 
* AGENTS.md
*: プロジェクト概要、技術スタック、一般的なコーディングコンテキスト、他のAIツールとも共有する指示に使用する。
* .windsurf/rules/
*: Windsurf固有の制約、発動モードの制御が必要な指示、言語固有のルールに使用する。
 
.windsurfrules (レガシー形式) について: 
* Wave 8以前の標準形式である。
* 現在も後方互換性として動作する。
* プロジェクトルートに単一ファイルを配置するだけで自動的に読み込まれる。
* 新規プロジェクトでは .windsurf/rules/ への移行が推奨される。
 

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

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

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

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

{{#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__
[[カテゴリ:設定]]

Windsurfの設定 - AGENTS.md - 版の履歴

Wiki: /* 推奨される事柄 */

Wiki: /* ベストプラクティス */