Windsurfの設定 - ワークフロー
概要
Workflows (ワークフロー) は、Windsurfにおいてスラッシュコマンドで呼び出す反復タスクの自動化機能である。
Markdownファイルとして定義され、/<ワークフロー名> の形式でCascadeから実行する。
ワークフローは、ルール (Rules) や スキル (Agent Skills) と異なり、ユーザが明示的にスラッシュコマンドで呼び出す点が特徴である。
ルールが「常時適用される制約」、スキルが「自動判断で呼び出される多段階タスク」であるのに対し、ワークフローは「明示的に呼び出す定型作業の自動化」に焦点を当てている。
下表に、ワークフローの主な特徴を示す。
| 特徴 | 説明 |
|---|---|
| スラッシュコマンドによる呼び出し | /<ワークフロー名> でCascadeから即座に実行可能
|
| ファイル名がコマンド名 | research.mdの場合は /research、 git-commit.mdの場合は /git-commit として呼び出される。 |
| 階層的な優先順位 | System > Workspace > Global > Built-in の優先順位で同名ワークフローが解決される。 |
| ネスト呼び出し | ワークフロー内から他のワークフローを呼び出し可能 |
| 引数の受け渡し | スラッシュコマンドの後に自然言語で引数を渡せる。 |
Claude Codeのカスタムコマンド (.claude/commands/*.md) に相当する機能であるが、
ネスト呼び出しが可能な点やシステムレベルワークフローの配置が可能な点で機能が拡張されている。
ワークフローの基本概念
Rules / Skills / Workflowsの比較
Windsurfには、Cascadeの動作をカスタマイズする3つの仕組みが存在する。
| 項目 | Rules (ルール) | Skills (スキル) | Workflows (ワークフロー) |
|---|---|---|---|
| 主な用途 | コーディング規約、スタイルガイド | 多段階ワークフロー、テンプレート活用 | 反復タスクの自動化 |
| 呼び出し方法 | 自動 (発動モード) | 自動 (descriptionベース) / @<スキル名> | /<ワークフロー名> (スラッシュコマンド) |
| ファイル形式 | 単一Markdownファイル | SKILL.md + 支援ファイル群 | 単一Markdownファイル |
| 配置場所 | .windsurf/rules/*.md | .windsurf/skills/<スキル名>/ | .windsurf/workflows/*.md |
| 適用タイミング | 常時 / パターンマッチ時 | タスク実行時のみ | 明示的呼び出し時のみ |
| 引数 | なし | なし | 自然言語で渡せる。 |
| ネスト | なし | なし | 他のワークフローを呼び出し可能 |
ファイル書式と保存場所
下表に、ワークフローファイルの保存場所を示す。
| スコープ | パス | 優先度 | 用途 |
|---|---|---|---|
| システム | /etc/windsurf/workflows/*.md | 最高 | エンタープライズ向けの組織共通ワークフロー |
| ワークスペース | .windsurf/workflows/*.md | 高 | プロジェクト固有のワークフロー |
| グローバル | ~/.codeium/windsurf/workflows/*.md | 中 | 全ワークスペース共通のワークフロー |
| 組み込み | Windsurf内蔵 | 最低 | デフォルトのワークフロー |
ファイル名とコマンド名の対応
ワークフローファイルのファイル名 (拡張子を除く) がそのままスラッシュコマンド名になる。
| ファイル名 | スラッシュコマンド |
|---|---|
| research.md | /research |
| git-commit.md | /git-commit |
| run-tests.md | /run-tests |
| deploy-staging.md | /deploy-staging |
| pr-review.md | /pr-review |
ワークフローファイルの基本書式
ワークフローファイルはMarkdown形式で記述する。
YAMLフロントマターで description を記述できる。(オプション)
---
description: ワークフローの簡潔な説明
---
# ワークフロー名
## 目的
このワークフローは〜を自動化します。
## 手順
1. ステップ1の説明
2. ステップ2の説明
3. ステップ3の説明
## 注意事項
- 注意事項1
- 注意事項2
スラッシュコマンドでの呼び出し
ワークフローは、Cascadeの入力ボックスでスラッシュコマンドとして呼び出す。
基本的な呼び出し
Cascadeの入力ボックスに / を入力すると、利用可能なワークフローの一覧が表示される。
# 引数なしの呼び出し /run-tests # 引数付きの呼び出し /research React hooks のベストプラクティス # 引数付きの呼び出し (ファイル指定) /pr-review src/auth/middleware.js の変更
引数の渡し方
スラッシュコマンドの後に続けて自然言語で引数を渡すことができる。
Cascadeはワークフロー内の指示と渡された引数を組み合わせてタスクを実行する。
ワークフローの探索メカニズム
Windsurfは以下の順序でワークフローファイルを探索する。
- システムワークフロー
- /etc/windsurf/workflows/
- ワークスペースワークフロー
- .windsurf/workflows/
- グローバルワークフロー
- ~/.codeium/windsurf/workflows/
- 組み込みワークフロー (Windsurf内蔵)
同名のワークフローが複数のスコープに存在する場合、より高い優先度のスコープのワークフローが使用される。
例えば、ワークスペースとグローバルの両方に research.md が存在する場合、ワークスペースのワークフローが優先される。
階層と優先順位
下表に、ワークフローの優先順位を示す。
| 優先度 | スコープ | 説明 |
|---|---|---|
| 1 (最高) | System | エンタープライズ管理者が配置するワークフロー |
| 2 | Workspace | プロジェクト固有のワークフロー |
| 3 | Global | ユーザの全ワークスペース共通ワークフロー |
| 4 (最低) | Built-in | Windsurf内蔵のデフォルトワークフロー |
この優先順位により、組織のポリシーを最優先としつつ、プロジェクト固有のカスタマイズを適用できる。
ワークフローの作成方法
ワークフローの作成には3つの方法がある。
UIから作成
Cascadeのスライダーメニューからワークフローを作成する手順を以下に示す。
- Cascadeパネル右上のメニューを開く。
- [Customizations]を選択する。
- [Workflows]セクションに移動する。
- [+ Workspace] または [+ Global]を選択して新規ワークフローを作成する。
- ワークフロー名と内容を入力して保存する。
Cascadeへの依頼
Cascadeに対してワークフローの作成を依頼する方法を以下に示す。
# 依頼例 テスト実行と修正を自動化するワークフローを作成してください。 ファイル名は run-tests.md として .windsurf/workflows/ に保存してください。
Cascadeは指示に基づいてワークフローファイルを自動生成する。
手動作成
ファイルを直接作成する手順を以下に示す。
# ワークフローディレクトリの作成 mkdir -p .windsurf/workflows # ワークフローファイルの作成 touch .windsurf/workflows/my-workflow.md
ファイルの内容をMarkdown形式で記述する。
ネスト呼び出し
ワークフロー内から他のワークフローを呼び出すことができる。
これにより、複数のワークフローを組み合わせた複雑なタスクを実現できる。
ネスト呼び出しの記述例を以下に示す。
---
description: コードの変更をテストしてからコミットする
---
# Test and Commit
## 手順
1. /run-tests を実行してテストを通過することを確認する
2. テストが成功したら、/git-commit を実行して変更をコミットする
3. テストが失敗したら、エラー箇所を修正してから再度テストを実行する
この例では、/test-and-commitワークフローが /run-tests と /git-commit の2つのワークフローを内部で呼び出している。
サンプル
PRコメント対応ワークフロー
Pull Requestのコメントに対応するワークフローの例を以下に示す。
- ファイル名: .windsurf/workflows/pr-respond.md
---
description: PRのコメントを確認して対応する
---
# PR Comment Response
## 手順
1. `git diff` で現在の変更差分を確認する
2. 渡されたPRコメントの内容を分析する
3. コメントで指摘された問題点を修正する
4. 修正内容をレビューして品質を確認する
5. `git add` で変更をステージングする
6. コメント対応を説明するコミットメッセージで `git commit` する
## 注意事項
- 指摘内容を正確に理解してから修正に着手すること
- 修正がコメントの意図に沿っていることを確認すること
- 関連するテストが存在する場合は実行すること
Git操作ワークフロー
ブランチ作成から変更のコミット・プッシュまでを自動化するワークフローの例を以下に示す。
- ファイル名: .windsurf/workflows/git-commit.md
--- description: 変更をステージングしてコミットする --- # Git Commit ## 手順 1. `git status` で変更状況を確認する 2. `git diff` で変更内容を確認する 3. 変更内容に基づいて適切なコミットメッセージを生成する 4. `git add` で関連ファイルをステージングする 5. 生成したコミットメッセージで `git commit` する 6. `git log --oneline -3` でコミット結果を確認する ## コミットメッセージの規約 - Conventional Commits形式を使用: feat:, fix:, docs:, refactor: 等 - 簡潔で変更の目的が分かるメッセージにすること - 日本語で記述すること
テスト実行 および 修正ワークフロー
テストの実行と失敗箇所の修正を自動化するワークフローの例を以下に示す。
- ファイル名: .windsurf/workflows/run-tests.md
--- description: テストを実行し、失敗した場合は修正する --- # Run Tests and Fix ## 手順 1. プロジェクトのテストフレームワークを検出する (Jest, pytest, Go test等) 2. テストを実行する 3. テストが全て成功した場合は結果を報告して終了する 4. テストが失敗した場合: a. 失敗したテストのエラーメッセージを分析する b. 関連するソースコードを確認する c. エラーの根本原因を特定する d. 最小限の修正を実施する e. テストを再実行して修正を検証する ## 注意事項 - テストコードそのものは変更しないこと (テストが正しい前提) - 修正はソースコードのみに対して行うこと - 3回以上の修正サイクルで解決しない場合は報告すること
リサーチワークフロー
指定トピックの調査とレポート作成を自動化するワークフローの例を以下に示す。
- ファイル名: .windsurf/workflows/research.md
--- description: 指定トピックを調査してレポートを作成する --- # Research ## 手順 1. 渡されたトピックの概要を把握する 2. プロジェクト内の関連コードを検索する 3. 公式ドキュメントやベストプラクティスを調査する 4. 調査結果をまとめてレポートを作成する ## 出力形式 - トピックの概要 - 現在のプロジェクトでの使用状況 - 推奨されるアプローチ - 参考リンク
デプロイワークフロー
デプロイ前チェックからデプロイ実行までを自動化するワークフローの例を以下に示す。
- ファイル名: .windsurf/workflows/deploy-staging.md
--- description: ステージング環境にデプロイする --- # Deploy to Staging ## 前提条件 - 全てのテストがパスしていること - mainブランチにマージ済みであること ## 手順 1. /run-tests を実行して全テストの通過を確認する 2. `git log --oneline -5` で最新のコミットを確認する 3. デプロイスクリプトを実行する 4. デプロイ後のヘルスチェックを実行する 5. 結果を報告する ## エラー時の対応 - デプロイが失敗した場合は、ロールバック手順を提示する - ヘルスチェックが失敗した場合は、ログを確認して原因を報告する
エンタープライズ向け設定
エンタープライズ環境では、システムレベルのワークフローを配置することにより、組織全体で共通のワークフローを提供できる。
システムレベルワークフローの配置
システム管理者は、以下に示すパスにワークフローを配置する。
| OS | パス |
|---|---|
| Linux | /etc/windsurf/workflows/ |
| MacOS | /Library/Application Support/Windsurf/workflows/ |
| Windows | C:\Program Files\Windsurf\workflows\ |
システムレベルワークフローは最高の優先度を持ち、ワークスペースやグローバルの同名ワークフローを上書きする。
組織共通ワークフローの管理
下表に、組織全体で統一されたワークフローを管理するための推奨事項を示す。
| プラクティス | 説明 |
|---|---|
| ワークフローのバージョン管理 | 専用のGitリポジトリでワークフローを管理し、変更履歴を追跡する。 |
| 段階的な展開 | テスト環境でワークフローを検証してから本番環境に展開する。 |
| ドキュメントの整備 | 各ワークフローの使用方法と注意事項をドキュメント化する。 |
Claude Codeカスタムコマンドとの比較
下表に、WindsurfワークフローとClaude Codeカスタムコマンドの比較を示す。
| 項目 | Claude Codeカスタムコマンド | Windsurfワークフロー |
|---|---|---|
| 配置場所 | .claude/commands/*.md | .windsurf/workflows/*.md |
| 呼び出し | /<カスタムコマンド名> | /<ワークフロー名> |
| ファイル形式 | Markdown | Markdown |
| 引数 | $ARGUMENTSプレースホルダ | 自然言語で渡す。 |
| ネスト呼び出し | 不可 | 可能 |
| フロントマター | なし | description (オプション) |
| スコープ | プロジェクト / ユーザ | System / Workspace / Global / Built-in |
| GUI作成 | なし | Cascadeメニューから作成可能 |
| 共有スコープ | .claude/commands/ (プロジェクト) | .windsurf/workflows/ (プロジェクト) |
推奨される事柄
ワークフロー作成において、推奨される事柄を以下に示す。
明確なdescription
descriptionフィールドには、ワークフローの目的を簡潔に記述する。
これにより、/ 入力時の一覧表示でワークフローの用途が一目で分かる。
段階的な手順
実行ステップを番号付きリストで明確に記述する。
各ステップは具体的なアクションを含めること。
エラーハンドリング
エラーが発生した場合の対処方法を明記する。
特に、外部コマンドの実行結果に基づく分岐を記述する。
再利用可能な設計
ワークフローは特定のプロジェクトに依存しない汎用的な記述を心がける。
プロジェクト固有の設定は引数として渡す設計が望ましい。
命名規則
ワークフローファイル名は、ケバブケース (kebab-case, ハイフン区切りの小文字) で記述する。
| 良い例 | 悪い例 |
|---|---|
| run-tests.md | RunTests.md |
| git-commit.md | gitcommit.md |
| deploy-staging.md | Deploy_Staging.md |
トラブルシューティング
ワークフローが表示されない
/ を入力してもワークフローが表示されない場合の対処法を以下に示す。
- ファイルが正しいディレクトリに配置されているか確認する。
- ワークスペース: .windsurf/workflows/
- グローバル: ~/.codeium/windsurf/workflows/
- ファイル拡張子が .md であることを確認する。
- Windsurf Editorを再起動する。
スラッシュコマンドが認識されない
- ファイル名にスペースや特殊文字が含まれていないか確認する。
- ファイル名がケバブケース (kebab-case) で記述されているか確認する。
- Markdownの構文が正しいか確認する。
ネスト呼び出しが動作しない
- 呼び出し先のワークフローが存在するか確認する。
- ワークフロー内での呼び出し記述が正しいか確認する。
- 再帰呼び出し (自分自身の呼び出し) が含まれていないか確認する。
参考リンク
