プランファーストワークフロー

プランファーストワークフローは、Plan Mode を活用します。これは読み取り専用の実行モードで、Verdent がコードを分析し、調査を行い、変更を実行する前に詳細な計画を作成します。このワークフローは戦略的な計画と実装を分離し、コードの変更に着手する前にレビューと改善を可能にします。

Plan Mode を使用する場面

調整が必要な複数ファイルにまたがる複雑な変更
最適な実装アプローチが不確かな場合
本番環境で重要なコードへの影響が大きい変更
探索が必要な、不慣れなコードベースでのタスク
実行前に承認が必要な戦略的計画

AIによるタスク分解

Verdent は、AIによるタスク分解を通じて、複雑なリクエストを管理しやすい連続したステップに自動的に分解します。

分解プロセス

リクエストの分析

Verdent は自然言語のリクエストを分析し、以下を特定します。

主な目的と望ましい結果
影響を受けるファイル、コンポーネント、システム
必要となる技術的操作と依存関係
複雑さの要因となりうる点

コードベースのコンテキスト

Verdent はプロジェクト構造を調査し、以下を把握します。

既存のアーキテクチャと確立されたパターン
ファイル構成と技術スタック
変更が必要な現在の実装

タスクの分解

Verdent はリクエストを論理的なサブタスクに分解します。

自然な区切りと実装フェーズを特定
依存関係に基づいてタスクを並べ替え（前提となるタスクを先に）
関連する操作をまとめる
各サブタスクの範囲と複雑さを見積もる

対話的な確認

Verdent は分解を洗練するために質問することがあります。

「既存のバリデーションを変更しますか、それとも新しいバリデーターを作成しますか?」
「影響を受けるすべてのコンポーネントのテストを更新しますか?」
「この変更をWebとモバイルの両方のコンポーネントに適用しますか?」

分解の特徴

集中して15〜45分で取り組めるサイズのタスク
テストと検証のための自然な区切り
意味を持つ程度に複雑で、実行できる程度にシンプル

依存関係を尊重（実装の前にセットアップ）
論理的な進行（データ層 → ビジネスロジック → UI）
主要なフェーズの後に検証ステップ

プランの分解形式は plan_rules.md でカスタマイズでき、以下を制御できます。

詳細度（概要レベルか細かいレベルか）
プランの構造とセクション
含める情報（時間見積もり、リスク、依存関係）

プランのレビューと承認

Plan Mode でリクエストを送信すると、Verdent が構造化されたプランを生成し、レビュー用にチャットビューに表示します。

レビュープロセス

構造化されたプランを受け取る

Verdent は、明確なセクション、番号付きステップ、影響を受けるファイル、特定された依存関係を含むプランを生成します

プランの品質を分析する

以下の観点でレビューします。

正確性: このアプローチで問題が解決するか?
網羅性: 必要なステップがすべて含まれているか?
効率性: これが最善のアプローチか?
リスク: 何が問題になりうるか? エッジケースやセキュリティ上の懸念は?

確認のための質問をする

不明な点があれば追加情報を求めます。

Can you explain step 3 in more detail?
Why are we modifying both the service and controller?
What happens if the API call fails in step 5?

修正を依頼する

フィードバックを提供してプランを修正します。

Let's use JWT tokens instead of OAuth2
Can we break step 4 into smaller substeps?
Add error handling considerations to the plan

次のアクションを選択する

Verdent がプランを生成した後、2つの選択肢が表示されます。

Edit: 修正を依頼したり、確認のための質問をしたり、プランをさらに洗練したりします
Start Building: Agent Mode に切り替えて、承認したプランの実行を開始します

プランの操作オプション

生成されたプランをレビューした後、Verdent は2つの選択肢を表示します。

Edit:

このオプションを選ぶと、以下が行えます。

プランのアプローチに対する具体的な変更を依頼する
実装の詳細について確認のための質問をする
不足している要素や考慮事項を追加する
特定のステップを簡素化または拡張する
代替アプローチを検討する

これにより、変更を実行することなく Plan Mode のまま繰り返し洗練を続けられます。

Start Building:

このオプションを選ぶと、以下が行えます。

Agent Mode に切り替えて実行を開始する
承認したプランを完全に自律的に実装する
計画どおりにファイルを変更しコマンドを実行する

次の方法を選ぶこともできます。

手動での実装: プランをレビューして、自分で変更を実装する
段階的な実行: Verdent に特定のフェーズを実装させ、各段階の間にレビューのためのチェックポイントを設ける

Edit を使って必要なだけプランを繰り返し改善できます。アプローチが正しく完全であると確信できたときだけ Start Building を選択してください。

反復的な計画

Edit を選んで会話形式でフィードバックを提供することで、自由にプランを修正・反復できます。Verdent はプラン生成を対話的で反復的なプロセスとして扱います。

修正の方法

具体的な変更を依頼する:

Change step 3 to use Redux instead of Context API
Add input validation before the database insert
Swap the order of steps 4 and 5

不足している要素を追加する:

Add error handling for network failures
Include rollback procedures
Add performance optimization considerations

簡素化または拡張する:

This is too complex - can we simplify the approach?
Break down step 5 into more detailed substeps
Give me more detail on the database schema changes

代替案を検討する:

What if we used webhooks instead?
Show me an alternative plan using microservices architecture
Can we accomplish this without changing the database schema?

反復フローの例

User: "Add user authentication to the API"

[Verdent generates initial plan with JWT tokens]

User: "Actually, let's use OAuth2 instead of JWT"

[Verdent revises plan to use OAuth2]

User: "Add step for migrating existing users"

[Verdent adds migration step to plan]

User: "Can you break down the migration step more?"

[Verdent expands migration with detailed substeps]

User: Chooses **Start Building**

[Verdent switches to Agent Mode and begins execution]

無制限の反復:

修正回数に制限はありません
各反復で会話のコンテキストが維持されます
以前のバージョンはチャット履歴に保存されます
過去のプランバージョンを参照できます: 「最初のアプローチに戻して」

プランの却下は、反復的な計画プロセスの自然な一部です。これにより、承認され十分に理解された戦略だけが実行され、誤った実装に無駄な労力を費やすことを防ぎます。

よくある質問（FAQ）

Plan Mode は実際にファイルにコードを書き込みますか?

いいえ。 Plan Mode は厳密に読み取り専用です。

Verdent はファイルの読み取り、コードの検索、コードベースの分析を行えます
Plan Mode 中にファイルの書き込み、編集、削除は一切行われません
プランはチャットビューに表示されるだけです
コードの実行は、明示的に承認して Agent Mode に切り替えた後にのみ開始されます

安全性の保証: Plan Mode が誤ってコードを変更することはありません。安全な探索と戦略策定のために設計されています。

プランを一度にすべてではなく段階的に実行できますか?

はい。 段階的な実行は完全にサポートされています。

段階的承認のパターン:

Let's start with Phase 1 first, then we'll review before continuing
Implement steps 1-3, then stop for review
Do the database migration first, I'll review before the API changes

仕組み:

Verdent が指定されたステップを実行
レビューのチェックポイントで停止
結果をレビューしてフィードバックを提供
次のフェーズに進むか、アプローチを調整
完了するまで繰り返す

最適な場面: リスクの高い変更、不慣れなパターン、段階的な展開でリスクを減らせる本番環境で重要なコード。

段階的な実行では、プランの一部を承認しつつ、他の部分を保留できます。タスクの途中で優先順位が変わる場合に便利です。

プランを却下するとどうなりますか?

プランの却下はまったく正常で想定された動作です。

Verdent はフィードバックに基づいて新しいプランを生成します
以前のプランバージョンは参照用にチャット履歴に残ります
コードの変更は発生しません（Plan Mode は読み取り専用です）
満足できるまで何度でも反復できます

よくある却下理由:

アプローチが複雑すぎる、または単純すぎる
エッジケースやエラー処理が不足している
より良い代替アーキテクチャが存在する
要件を誤解していた

ヒント: 却下はプロセスの一部です。誤った戦略の実行に労力を費やすより、プランを反復的に洗練するほうが良い結果につながります。

Plan Mode と Agent Mode はどう切り替えますか?

切り替えは入力ボックスから即座に行えます。

Plan Mode に入るには:

入力ボックスの Switch Mode ボタンを選択
ドロップダウンから Plan Mode を選択
または「Switch to Plan Mode」と伝える

Plan Mode を抜けるには:

入力ボックスの Switch Mode ボタンを選択
ドロップダウンから Agent Mode を選択
またはプランをレビューした後に Start Building を選択

モードの永続性:

モードの選択は現在のセッション内で維持されます
新しいセッションはデフォルトの Agent Mode で開始します
いつでも自由にモードを切り替えられます

典型的なワークフロー: Plan Mode → レビュー → Agent Mode → 実行 → 次の複雑な機能のために Plan Mode に戻る。

生成されるプランの形式と詳細度をカスタマイズできますか?

はい、plan_rules.md を使ってカスタマイズできます。

場所: ~/.verdent/plan_rules.md（グローバル設定ディレクトリ）

カスタマイズできる内容:

詳細度: 概要レベルか、細かいステップごとか
プランの構造: 含めるセクション（概要、リスク、依存関係、テスト）
含める情報: 時間見積もり、ファイルパス、検証ステップ
形式の好み: 番号付きリスト、フェーズ、分類

plan_rules.md の例:

# Plan Rules

## Plan Structure
- Start with a brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks and mitigation strategies

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions or components to create/modify
- Provide verification steps for each phase

変更は新しい Plan Mode セッションに即座に適用されます。

Plan Mode は Agent Mode と同じコンテキストを使いますか?

いいえ、Plan Mode は別個のコンテキスト管理を行います。

Plan Mode のコンテキスト: 分析と戦略的思考に最適化
Agent Mode のコンテキスト: 実行と実装に最適化
メリット: プランが探索的な調査で実行コンテキストを汚すことがありません

分離が重要な理由:

Plan Mode は Agent Mode を散らかすことなく複数のアプローチを探索できます
却下されたプランの試行が Agent Mode のコンテキストを消費しません
実行に切り替える際にまっさらな状態になります

コンテキストのリセット: モードを切り替えると、新しいタスクの種類に応じた新鮮なコンテキストが得られます。

計画中に Verdent が確認のための質問をしてきた場合は?

確認のための質問は分解プロセスの一部です。

質問される理由:

曖昧な要件には明確化が必要
複数の有効なアプローチが存在する（1つを選ぶ）
エッジケースや制約がまだ指定されていない
最初のリクエストから好みが明確でない

応答の方法:

会話形式で直接答える
役立つ場合は例を示す
Verdent の判断を信頼するなら「お任せします」と伝える
不明な場合は逆に質問する

やり取りの例:

Verdent: "Should I modify the existing validation or create a new validator?"
You: "Create a new validator - we'll deprecate the old one later"
Verdent: [Updates plan with new validator approach]

ヒント: 質問は、Verdent が特定のニーズに合わせた正確で適切なプランを生成するのに役立ちます。