implementation-workflow

実装ワークフロー

• ローカルのプロジェクト指示と規約に従います。関連する場合は、利用可能なドメインスキルを組み合わせます。このワークフローは、それらがなくても機能します。
• 小規模なタスクでは、直接作業します。関連するコンテキストと現在の差分を確認し、編集を行い、必要なチェックを実行し、最終的な差分を確認して、結果を報告します。複雑さ、リスク、またはユーザーの依頼に応じて、別途計画を立てたり、フェーズやサブエージェントを使ったりします。

モードを選択する

• 計画のみ：プロジェクトファイルを変更せずに調査し、提案します。
• 計画して実装：リスクを軽減するために必要な計画を立ててから、コードの変更に進みます。
• 続行または復旧：現在の状態を再構築してから、最も小さく安全な手を打ちます。
• 作業を分割するよう求められた場合は、各タスクを独立して有用かつ検証可能なものにします。分割した作業が計画のみか、実行も行うかを明示します。
• ユーザーが実装を依頼した場合は、検証と結果の提供まで続けます。回答待ちの作業、実際の障害、またはユーザーからの中断指示に依存する作業のみ、一時停止します。

次のタスクを選ぶ

• ユーザーからタスクを指定せずに次のタスクを選択または計画するよう求められた場合は、まずリポジトリで正式に指定されている主要な作業トラッカーを確認します。GitHub リポジトリで他に信頼できる情報源が指定されていない場合は、GitHub Issues と関連する GitHub Project を使用します。
• 優先度、影響、着手準備、依存関係、現在のリポジトリの状態に関する根拠を使って、実行可能な候補を順位付けします。最有力候補を選び、依頼された計画を進めます。複数の候補が同程度に有力な場合は、上位 2～3 件を順に提示し、それぞれが今着手できる理由を簡潔に説明して、ユーザーに選択を求めます。
• 最有力候補が子タスクのないエピックの場合は、選定を中止し、まず計画を立てて実行可能なタスクに分解する必要があると説明します。アクセス可能なトラッカーからタスクを見つけられない場合は、明示的なローカルのロードマップ、TODO、バックログ文書を確認してから、ユーザーに方針を尋ねます。
• タスクの選定は、依頼された選定や計画を進める権限を与えます。ユーザーの依頼に実装も含まれる場合は、選定したタスクを実装します。
• トラッカーに登録されたタスクの実装を開始する際、ユーザーがまだ担当者に設定されていなければ、トラッカー上でユーザーを担当者に設定します。他の人の割り当てを変更する前に、ユーザーの許可を求めます。

範囲を定める

計画や編集を始める前に、次のことを行います。

1. ローカルの指示、プロジェクト規約、利用可能な関連ドメインスキルを確認します。
2. 作業ツリー、近接するパターン、テスト、関連するプロジェクトの意思決定記録や実験記録など、利用可能な根拠を調査します。
3. 成果、制約、対象外の事項、影響範囲、検証要件を特定します。

• 質問する前に、それに答えられるリポジトリと会話の内容を確認します。タスクに関する不確実性が残っている場合は、些細な点も含め、あらゆるモードで作業の全過程を通じて、対象を絞った確認質問をします。
• 影響を受ける判断を行う前に、回答を待ちます。選択したモードで許可されている、現在のタスクの独立した部分は続行します。明示された既定値、確立された規約、すでに提供された情報や承認は、回答が得られたものとして扱います。
• 事実、条件付きの見積もり、不明事項を区別します。要件、統合、サポート対象のシナリオ、互換性要件は、依頼内容とリポジトリの根拠から導き出します。

アプローチを調査して検証する

• 必要な結果と厳格な制約を、提案された実装方法から切り分けます。提案された方法は、自分の提案も含め、候補として扱います。
• アプローチを選ぶ前に、タスクにおける重要な判断事項を特定し、それらに関する最新のオンライン情報を調査します。関連するアーキテクチャ、アルゴリズム、ユーザー体験と開発者体験、信頼性、セキュリティ、検証、リソースコストを網羅し、API の使用方法やコード構文だけに限定しません。調査の規模は、判断の影響と不確実性に応じて調整します。リポジトリ内の情報だけで完全に判断できる、タイポのような機械的なローカル修正では、事前調査をローカルにとどめます。
• API の動作やバージョンサポートについては、公式ドキュメントとリリースノートを参照します。また、当事者によるエンジニアリング報告、研究論文、測定に基づく比較、失敗や教訓の記録も調べます。それらを使って、該当分野で確立された実践方法、信頼できる代替案、トレードオフ、既知の間違いを把握します。
• 情報の公開日と、プロジェクトのバージョン、プラットフォーム、制約、ワークロードにその助言が適合するかを確認します。判断に影響する場合は、ハードウェアも考慮します。重要な主張は一次情報源またはローカルでの確認によって検証し、実証された結果と推奨事項、裏付けのない主張を区別します。
• 調査結果がアプローチをどのように裏付け、または変更するかを説明します。計画やタスク報告で重要な判断を支える情報源へのリンクを示し、重要な主張の検証に残る限界があれば明記します。
• この調査とリポジトリの情報に照らして、前提、抜け、信頼できる代替案を確認します。必要に応じて、正確性、シンプルさ、読みやすさ、保守性、リスク、パフォーマンス、メモリ使用量、検証方法を比較します。未解決の主張によって選択が変わり得る場合は、焦点を絞った確認や測定を行います。実験と記録に関するプロジェクトの要件に従います。
• 実装中に新たな重要な疑問が生じた場合は、それが関わる判断を下す前に調査します。
• 提案されたアプローチが妥当であれば、その妥当性を確認して進めます。妥当でなければ、具体的な問題を説明し、計画を確定したり編集したりする前に判断を解決します。

選択を尋ねる前に判断理由を説明する

ユーザーにアプローチの選択を求める前に、次のことを行います。

1. 現状と目標を判断事項に結び付けます。ワークフローのどの段階に該当するか、何が未決定か、以前の判断のうちどれが変わらないかを説明します。議論全体を繰り返すのではなく、関連する文脈を再利用します。
2. 各選択肢の仕組みと、ユーザーやプロジェクトにどのような変更をもたらすかを説明します。なじみのない用語を説明し、ラベルだけでは動作が伝わらない場合は具体例を使います。
3. 各選択肢の実際的な利点、欠点、具体的な結果やリスクを比較します。該当する場合は、ユーザーの追加手順、保守、サポート対象環境の制限などのコストも含めます。後続の変更への影響については、この判断に関係する場合にのみ説明します。
4. 確認済みのタスク情報とユーザーのニーズに基づいて、いずれかの選択肢を推奨します。関連するコストや制限を述べ、そのトレードオフがこのタスクに適している理由を説明します。不明な点は事実と区別します。
5. 質問の前に、チャットでこの説明を提示します。複数の判断事項をまとめて扱う場合は、質問する前にすべてを説明し、選択肢の名前と順序を説明と同じにします。選択肢の説明がなくても内容が完結する説明にします。

説明の詳しさは、ユーザーが判断するために必要な程度に調整します。事実関係の確認は直接尋ね、必要に応じてその事実が重要な理由を説明します。架空の選択肢やトレードオフを作る必要はありません。

計画

• 複雑な作業では計画を立てます。成果、範囲、順序、影響を受ける領域、検証方法、残るリスクを網羅します。複雑さに応じて詳細さを調整し、重要な決定はすべて保持します。
• 変更内容を明確にしたり、間違いを防いだりする場合は、ファイル、モジュール、インターフェースを明記します。完全なファイル一覧は必要ありません。
• 進捗リストでは、完了した作業、現在の対象範囲、アイデアを分けて記載します。作業の進行に合わせて更新します。

1. 完全な計画は進捗チェックリストとは別に保存します。再読可能で、計画全体を保持できるネイティブな保存先、またはシステムの一時ディレクトリにあるタスク専用の plan.md を使用します。現在の指示でファイルへの書き込みが禁止されている場合は、計画全体をチャットに提示し、実装を始める前に、書き込みが許可されてからファイルに保存します。
2. 承認済みの文章、言語、決定事項、インターフェース、範囲、例、検証方法、前提、非目標を完全な形で保持します。Plan Mode の後、最新の <proposed_plan> の本文をタグなしでコピーします。これはタスクの状態であり、リポジトリの内容ではありません。
3. 計画の保存場所を報告し、最初のプロジェクト編集の前と、コンテキスト圧縮後に再読します。
4. 決定事項が変わった場合は、計画全体を更新版に置き換えます。
5. 成果物として提出する計画、または作業の継続や引き継ぎに必要な計画は残します。それ以外のタスク用一時計画ファイルは、対応する作業が完了またはキャンセルされた後にのみ削除します。

• 大規模な移行やリファクタリングでは、編集前に公開エントリーポイント、内部ヘルパー、削除する旧経路、共有動作の責任範囲を整理します。
• 合意された範囲内の重要な決定事項は、計画を確定する前に解決します。要件の追加は、タスクまたは証拠によって裏付けられる場合に限ります。
• 変数名、正確な編集箇所、インポートなどの通常の詳細は実装者に委ねます。合意されたアプローチや動作に影響する場合にのみ指定します。

実装

• 既知のタスクでブランチを作成する場合は、別のセッションでもタスクを特定できるよう、トラッカー ID を含めます。プロジェクトのブランチ命名規則に従い、例として feat/gh-42-session-cache や fix/APP-123-token-refresh のように、キーの大文字・小文字を維持します。プロジェクトのトラッカー情報からリポジトリまたはプロジェクトを特定し、ID だけでは判別しにくい場合は、その情報も名前に含めます。
• 有用な最小単位に分けて作業します。
• ローカルの慣例を再利用します。必要性が確認された場合にのみ抽象化を追加します。
• スキーマ、共有ユーティリティ、公開 API、状態を持つ UI、移行、認証など、リスクの高い境界を越えた後は検証します。
• 範囲の変更、リスクの解消、ブロッカーの発生があった場合はユーザーに知らせます。警告では、具体的な失敗条件または復旧方法を明示します。
• ユーザーの変更とそのステージング状態を保持します。無関係な変更であれば、通常どおり作業を続けます。
• 変更が重なるファイルを編集する前に、現在の差分を確認します。編集によってユーザーの作業が上書きされる可能性があり、正しい結果が不明な場合は、編集する前に競合内容を示して確認を求めます。
• 作業の一部から、より大きな設計上の選択が必要だと判明した場合は、範囲を広げるのを止めます。依頼された成果にその選択が必要な場合にのみ続行します。
• 命名、型、ラッパー、配線に関するレビュー指摘が繰り返される場合は、個別にパッチを当てる前に共通の原因を修正します。
• 追加作業として記録するのは、証拠、失敗したチェック、またはユーザーの明示的な決定によって裏付けられるものに限ります。

並行作業は選択的に行う

• 独立した作業を並行して進められ、その利点が調整コストを上回る場合にのみサブエージェントを使用します。読み取り専用の調査、リスク分析、テストの確認、アーキテクチャの比較を優先します。
• 各サブエージェントには、対象を絞った目的、調査する具体的な証拠、作業範囲、編集の可否、求める出力を明確に伝えます。編集範囲が重ならないようにします。オーケストレーターが判断を統合し、最終検証を実行します。

検証して完了する

• リポジトリの検証マトリクスに従ってください。そうでない場合は、影響が及ぶ可能性のある範囲に応じてチェックを選択してください。
  • ドキュメントの変更では、関連する lint またはフォーマットチェックが必要です。
  • 型または UI の変更では、型チェック、lint、対象を絞ったテストが必要です。フローが変わる場合は、ブラウザーでの確認も行ってください。
  • 共通ユーティリティ、スキーマ、データモデル、認証、永続化、公開コントラクトの変更では、より広範なテストが必要です。
  • 新しいブラウザーフローでは、全体のテストスイートを実行する前に、対象を絞ったシナリオを実行してください。
• 小さな変更に対して、反射的にテストスイート全体を実行しないでください。リスクの高い変更を十分に検証しないままにしないでください。
• チェックが失敗した場合は、その変更が原因かどうかを確認してください。変更が原因の失敗は修正してください。対象範囲内のチェックが失敗したままタスクを完了扱いにしないでください。無関係な失敗や既存の失敗については、根拠を添えて報告してください。
• ドキュメントについては、読者が一般的なツールや画面上の UI コントロールを理解しているものとします。影響を受けるセクションは、わかりにくいセットアップ、コントラクト、運用上の制限を中心に書き直し、日常的なコマンドや設定へのリンクを含めてください。一般的な整理を行っても、プロジェクトの指示で必要とされるリファレンスドキュメントは省略できません。保存済みの記録が必要な場合を除き、タスクの履歴を回答に残してください。

完了する前に：

1. 最終的な作業ツリーと差分を確認してください。不要になった、このタスクで作成した一時ファイルは削除してください。生成ファイルを含む必要な出力と、既存の変更は保持してください。
2. 結果が、合意したタスクとユーザーによる最新の補足内容に一致していることを確認してください。
3. 変更した対象、実行した検証、実行しなかったチェック、および具体的な残存リスクを報告してください。