ai-agentic-workflow

ai-agentic-workflow

正確で十分に検討された結果を得るため、重要なタスクではすべて、分析・計画・実行の3段階からなる構造化されたワークフローに従います。

使用するタイミング

次のような場合に、このスキルを使用します。

• 1つの手順だけでは完了しないタスクを受け取った場合
• 複数のファイル、コンポーネント、または概念が関係する依頼の場合
• 問題が曖昧で、作業に取りかかる前に確認が必要な場合
• 全体のコンテキストを把握せずに行動すると、失敗につながるおそれがある場合

些細な依頼（例：「この変数の名前を変更する」「この誤字を修正する」）には、このワークフローを使用しないでください。代わりに、すぐに対応してください。

手順

フェーズ1：分析

解決策を提案する前に、問題を完全に理解します。

1. 依頼を注意深く読みます。 ユーザーが明示的に求めていることと、明言されてはいないものの期待していると思われることを特定します。
2. コンテキストを収集します。 コードベース内の関連ファイル、依存関係、既存のパターンを調べます。推測せず、ツールを使って前提を確認します。
3. 制約を特定します。 適用される技術の選択、アーキテクチャのパターン、コーディング規約、参照されたスキルを確認します。
4. 曖昧な点を明確にします。 複数の妥当な解釈があり、コンテキストから正しい解釈を判断できない場合は、焦点を絞った質問を1つだけします。それ以外の場合は、最も妥当な解釈で進め、前提を明示します。
5. 調査結果を要約します。 次の内容を簡潔にまとめます。
   • 変更が必要な内容
   • 関連する既存の実装
   • 順守すべき制約やパターン
   • リスクやエッジケース

フェーズ2：計画

コードを書く前に、解決策を設計します。

1. タスクを個別の手順に分解します。 各手順は、それぞれ独立して検証できるものにします。
2. 依存関係に沿って手順を並べます。 依存する実装に先立ち、型、インターフェース、モデルなどの基盤となる作業を行います。
3. 影響を受けるファイルを特定します。 作成または変更するすべてのファイルを列挙します。
4. 副作用を検討します。 この変更によって既存のテスト、インポート、連携が壊れる可能性があるかを確認し、対策を計画します。
5. 最小限の方法を選びます。 依頼を完全に満たす、最も小さな変更を優先します。明示的に求められていない限り、無関係なコードをリファクタリングしません。
6. 計画を提示します。 実施内容を簡潔な番号付きチェックリストで提示します。タスクが大規模またはリスクの高い場合は、実行前にユーザーの確認を待ちます。小規模なタスクは、そのまま進めます。

フェーズ3：実行

計画に沿って、順番に実装します。

1. 計画の順序に従います。 手順を省略したり、再計画せずに実行中に方針を変更したりしません。
2. 論理的な変更を1つずつ実装します。 次に進む前に、各手順を完全に完了させます。
3. 作業と並行して検証します。 重要な変更のたびに、次のことを行います。
   • 変更したファイルにエラーがないか確認します。
   • 利用可能な場合は、関連するテストやビルドコマンドを実行します。
   • コンテキスト内で変更が正しく機能することを確認します（インポートが解決されるか、型が一致するか、ロジックが正しく流れるか）。
4. 予期しない問題に対処します。 手順が失敗した場合や問題が判明した場合は、次のようにします。
   • 作業を止め、該当する問題を改めて分析します。
   • 必要に応じて、残りの計画を調整します。
   • より良い選択肢がない場合を除き、回避策でエラーを無理に処理しません。
5. 完了を確認します。 すべての手順が終わったら、解決策全体を検証します。
   • チェックリストの項目がすべて完了している
   • 新たなエラーやリグレッションが発生していない
   • 元の依頼が完全に満たされている

各フェーズの適用方法

タスクの複雑さ	分析	計画	実行
些細（明白な単一の作業）	省略	省略	すぐに対応
小規模（2～5手順、明確な進め方）	簡潔なメンタルモデル	作業内のチェックリスト	すぐに実行
中規模（複数ファイル、一部に曖昧さあり）	十分なコンテキスト収集	明示的な番号付き計画	検証しながら段階的に実行
大規模（複数領域にまたがる、アーキテクチャに関わる）	深く調査し、不明点があれば質問	詳細な計画を作成し、確認を待つ	チェックポイントを設けて段階的に実行

避けるべきアンチパターン

• 理解しないままコードに取りかかること。 分析を終える前に、ファイルを編集してはいけません。
• コンテキストなしで計画を立てること。 検証済みの事実ではなく仮定に基づく計画は失敗します。
• 計画から黙って逸脱すること。 方針を変更する必要がある場合は、そのことを伝えて計画を立て直してください。
• 過剰に設計すること。 いつか必要になるかもしれないものではなく、依頼されたものを実装してください。
• 作業を不完全なまま終えること。 「ほぼ完了」の時点で止めず、検証を含め、すべての手順を完了してください。