Cursor での Plan と Act デュアルモードエージェントワークフロー
AI コーディングエージェントに関する最大の課題の一つは、未承認の変更を防ぐことです。Plan と Act のデュアルモードワークフローは、エージェントが "Plan モード" で変更を提案し、"Act モード" で実行する前に承認を得ることを要求することで、この問題を解決します。このガイドでは、この強力な安全性パターンを Cursor で実装する方法を示します。
Plan と Act とは？
Plan モード（読み取り専用）
Plan モードでは、エージェントは以下を行います：
- コードを読み取り、分析する
- 構造化された形式で変更を提案する
- ファイルを変更できない
- ユーザー審査のための詳細な計画を提示する
Act モード（読み書き）
Act モードでは、エージェントは以下を行います：
- 承認された変更のみを実行する
- 完全な読み書きアクセス権を持つ
- 提供された正確な計画に従う
- 実行した内容を報告する
なぜこのパターンを使用するのか？
| Plan/Act なし | Plan/Act あり |
|---|---|
| AI が予期せずファイルを変更する | すべての変更に承認が必要 |
| 変更内容の確認が困難 | まず明確な計画が提示される |
| ロールバックが困難 | 変更は追跡可能で元に戻せる |
| 長時間セッションでのコンテキストドリフト | タスクごとに集中的な実行 |
実装方法 1：Cursor ルール
.cursor/rules/plan-act-workflow.mdc を作成：
---
description: 'Plan と Act デュアルモードワークフロー'
globs: ['**/*']
alwaysApply: true
---
# Plan と Act ワークフロー
## 重要なルール
明示的なユーザー承認なしにファイルを変更してはいけません。
## Plan モード（デフォルト）
タスクを与えられたとき：
1. 関連ファイルを読み取り、分析する
2. 具体的な変更を含む詳細な計画を作成する
3. 以下の形式で計画を提示する：
### 計画：[タスク名]
#### 変更するファイル
- `file/path/one.ts` - 変更内容
- `file/path/two.ts` - 変更内容
#### 変更の概要
1. 変更 1 の説明
2. 変更 2 の説明
#### 新しいファイル（ある場合）
- `new/file/path.ts` - 用途
#### テスト計画
- 変更が機能することを確認する方法
4. ユーザーが "PROCEED" または "ACT" と入力するのを待つ
## Act モード（承認後）
ユーザーが "PROCEED" と言った後のみ：
1. 計画から変更を実装する
2. 承認された変更のみを行う
3. ファイルリストと共に完了を報告する
4. テスト手順を提案する
## 絶対にしてはいけないこと
- 計画段階をスキップする
- 計画外の変更を追加する
- Plan モード中にファイルを変更する
- 計画ごとに複数回承認を求める
実装方法 2：カスタムモード
Cursor 設定でカスタムモードを作成：
- Cursor 設定を開く（
Cmd/Ctrl + ,） - "Modes" または "AI Features" に移動
- "Add Custom Mode" をクリック
- 設定：
{
"name": "Planner",
"description": "計画モード - 読み取り専用分析",
"systemPrompt": "あなたは計画モードです。ファイルを読み取ることはできますが、決して変更しないでください。コードベースを分析し、要件を理解し、詳細な計画を提示してください。変更を行う前にユーザー承認を待ってください。",
"tools": ["read", "grep", "search"],
"fileWrite": false
}
{
"name": "Executor",
"description": "実行モード - 承認された変更を実装",
"systemPrompt": "あなたは実行モードです。計画で承認された変更のみを実装してください。承認された範囲から逸脱しないでください。変更を行うたびに報告してくだ さい。",
"tools": ["read", "write", "edit"],
"fileWrite": true
}
実装方法 3：チャットベースのワークフロー
ステップ 1：Plan モードで開始
[PLAN MODE] このアプリにユーザー認証を追加する必要があります。
コードベースを分析して計画を作成してください。
まだ変更は行わないでください。
ステップ 2：エージェントが計画を提示
## 計画：ユーザー認証の追加
### 変更するファイル
1. `src/app.ts` - 認証ミドルウェアを追加
2. `src/routes/users.ts` - ログイン/登録エンドポイントを追加
3. `src/models/user.ts` - パスワードハッシュを追加
### 新しいファイル
1. `src/middleware/auth.ts` - JWT 検証
2. `src/services/auth.ts` - 認証ロジック
3. `tests/auth.test.ts` - ユニットテスト
### 実装の詳細
- パスワードハッシュに bcrypt を使用
- 15 分有効期限の JWT トークン
- リフレッシュトークンローテーシ ョン
### テスト
- 有効/無効な認証情報でログインをテスト
- トークンリフレッシュをテスト
- 保護されたルートをテスト
ステップ 3：レビューと承認
計画を確認し、以下のいずれかを行います：
PROCEEDと入力して承認- 修正を求める
- 拒否して最初からやり直す
ステップ 4：実行
[ACT MODE] 認証計画を PROCEED します。
承認された内容を正確に実装してください。
ステップ 5：検証
実行後：
すべての変更が正しく行われたことを確認：
1. 認証ミドルウェアが適用されていることを確認
2. ログインエンドポイントをテスト
3. 認証テストを実行
高度：自動計画解析
複雑なプロジェクトでは、構造化された計画形式を使用：
## 計画 ID：AUTH-001
## ステータス：承認待ち
## 優先度：高
## 推定時間：30 分
### スコープ
- JWT ベースの認証を追加
- ログイン/ログアウト/登録を実装
- パスワードリセットフローを追加
### 変更
#### ファイル：src/middleware/auth.ts（新規）
```typescript
import jwt from 'jsonwebtoken';
export const verifyToken = (req, res, next) => {
// 実装
};
ファイル：src/routes/auth.ts（新規）
// ログイン、登録、ログアウトエンドポイント
ファイル：src/app.ts（変更）
- 15 行目：
app.use('/auth', authRoutes)を追加
ロールバック
- 削除：src/middleware/auth.ts
- 削除：src/routes/auth.ts
- 復元：src/app.ts 15 行目
テスト
- 有効な認証情報でログイン
- 無効な認証情報でログイン
- トークンなしで保護されたルートにアクセス
- 有効なトークンで保護されたルートにアクセス
## バージョン管理との統合
### 実行前のチェックポイント
計画を実行する前に：
```bash
# チェックポイントブランチを作成
git checkout -b plan/auth-implementation
# 現在の状態をコミット
git add -A && git commit -m "チェックポイント：認証実装前"
実行後の検証
# 変更を確認
git diff
# 問題がある場合は元に戻す
git checkout -- .
# またはチェックポイントに戻す
git reset --hard HEAD~1
チームワークフロー
コードレビュー用
- 開発者が Cursor で計画を作成
- 開発者が計画を PR 説明に貼り付ける
- レビュアーが実行前に計画を承認
- 開発者が Plan と Act ワークフローで実行
- レビュアーが実行が計画と一致することを確認
PR テンプレート
## 計画
[AI 生成の計画をここに貼り付ける]
## 実行
- [ ] 計画された変更がすべて実装された
- [ ] 計画外の変更はない
- [ ] テストが通過する
- [ ] 計画と実行が一致する
## 検証
[実行したテストを記述]
よくある落とし穴
| 落とし穴 | 解決策 |
|---|---|
| エージェントが計画をスキップする | ルールとモード制限で強制する |
| 計画があいまいすぎる | 具体的なファイルパスと行番号を要求する |
| ユーザー承認の疲労 | 関連する変更を 1 つの計画にまとめる |
| 実行が計画から逸脱する | 実行後に diff と計画を比較する |
| 行き来が多すぎる | 小さな逸脱は許容し、大きな逸脱は警告する |
クイックスタートチェックリスト
-
.cursor/rules/plan-act-workflow.mdcを作成 - 小さく安全なタスクでテスト
- エージェントが読み取り専用モードを尊重することを確認
- 計画の承認と拒否を練習
- 実行前に git チェックポイントを設定
- チーム向けにワークフローを文書化