req-change-workflow

要件変更ワークフロー

概要

既存の要件をスコープクリープや「边改边炸」なしに変更するため、軽量で繰り返し実行可能なワークフローを使用します。各ゲートで明確な成果物を作成し、実装を開始する前にユーザーが承認できるようにします。

ワークフロー（ゲート付きループ）

手順に沿って進めます。ユーザーがステップ 4 を承認するまで、コードの変更を実装しないでください。

ステップ 0：計画を設定する（任意ですが推奨）

• update_plan を使用して、明確化 → ベースライン → 影響評価 → 設計 → 実装 → 検証 → 文書化の 5～7 個の短いステップを作成します。
• 常に in_progress のステップがちょうど 1 つになるようにし、完了したら次へ進みます。

ステップ 1：変更内容を明確にする（まずスコープを固定）

最小限の情報をユーザーに尋ね、明確な「変更概要」にまとめます。

• 対象（1 文）：どのような結果に変わるのか。
• スコープ外（1 文）：変更してはならないものを明示します。
• 受け入れ条件（3～6 個の箇条書き）：検証可能な観察可能な動作。
• 「維持必須」の制約：互換性、パフォーマンス、セキュリティ、新しい依存関係を追加しない、ネットワークを使用しない、など。
• ロールバックの想定：差分を元に戻せば復元できるか、それともデータの移行やバックフィルが必要か。

references/change-brief-template.md のテンプレートを使用します。

ステップ 2：コードで現在の動作を確認する（ベースライン）

記憶や推測を当てにしないでください。実際のエントリーポイントと現在のデータフローを特定し、5～10 行で要約します。

• UI エントリーポイント（例：sidepanel/、options/）と、ユーザー操作がどこで接続されているか。
• バックグラウンドのオーケストレーション（例：service_worker.js）。
• コアモジュール（例：src/core/...）とストレージ（src/core/local/...）。
• 設定／権限の変更（例：manifest.json）。

Chrome 拡張機能のプロジェクトでは、scripts/impact_scan.sh を使って関連しそうなファイルを特定できます。他のプロジェクトでは、実際のエントリーポイントと検索ツールを使用します。その後、関連する実装を読み、動作を確認します。

成果物：「現在の動作の概要」と、各ファイルが重要な理由を添えた簡潔なファイル一覧。

ステップ 3：影響とリスクを評価する（変更予算）

新しい設計を提案する前に、以下を列挙します。

• 変更が必要なファイル／モジュールと、その理由。
• リスク：認証／セッション、ストレージの移行、並行処理、キャッシュ、権限の範囲、UX のリグレッション。
• テストのチェックポイント：手動で検証する内容（references/regression-checklist.md を使用）。
• ロールバック計画：安全に元に戻せるもの、クリーンアップが必要なもの。

変更が manifest.json または service_worker.js に及ぶ場合は、検証計画に手動で再読み込みする手順を含めます（Chrome 拡張機能は積極的にキャッシュするためです）。

成果物：「影響とリスクの一覧」と「ロールバック計画（1～3 個の箇条書き）」。

ステップ 4：新しい設計を提案する（承認を得る）

以下を使用して、新しい動作を説明します。

• エッジケースを含む新しいフロー（箇条書きの手順）。
• 状態モデル：主要な状態、遷移、障害からの復旧。
• 変更範囲：変更されない部分。
• 可観測性：デバッグ用のログ／イベント／UI のヒント。

次に、以下についてユーザーに承認を求めます。

• ステップ 1 の受け入れ条件を最終版とすること。
• ステップ 2／3 のファイル一覧を変更予算とすること。
• 提案した設計（このステップ）。

ユーザーが「同意／OK／このとおりに実行」と言うまで、コードの編集を開始しないでください。

ステップ 5：差分を最小限に抑え、変更箇所を限定して実装する

実装ルール：

• パッチより根本原因の修正を優先しつつ、差分は小さく、焦点を絞ります。
• 複数のエントリーポイントにロジックを分散させないようにします。可能であれば、1 つのモジュールに集約します。
• ES モジュールのインポートは明示的に記述し、暗黙のグローバル変数は避けます。
• 新しいエクスポートを追加する場合は、エクスポートする関数に短い JSDoc を追加します。
• ユーザーに表示するログには、次に何をすべきかを説明する、実行可能な中国語のメッセージを使用します。

変更に非同期フロー／モジュール間呼び出し／フォールバックが関係する場合は、前提と障害時の処理を説明する中国語のコメントを追加します。

Step 6: 検証（固定の回帰テストサイクル）

• 実際のプロジェクトと変更内容に基づいて、references/regression-checklist.mdから自動チェックと手動チェックを選択します。実行したコマンドと確認された結果を記録します。Chrome 拡張機能の例はreferences/chrome-extension-regression-example.mdにあります。
• manifest.jsonまたはservice_worker.jsを変更した場合は、再テストの前に拡張機能を再読み込みします。
• テストした内容と確認された結果を記録します（手動テストの場合も同様です）。

Step 7: 維持（ドキュメント＋意思決定ログ）

• 今後のメンテナー向けに、プロジェクトのドキュメントまたはインラインノートを更新します。
• 簡潔な「意思決定ログ」の項目を追加します。設計の理由、却下した代替案、ロールバック方法を記載します。

references/decision-log-template.mdのテンプレートを使用します。

リソース

scripts/

• scripts/impact_scan.sh：キーワードと一般的な拡張機能のエントリーポイントを対象に、rgで候補ファイルをすばやくスキャンします。

references/

• references/change-brief-template.md：スコープと受け入れ基準を明確にするための入力テンプレートです。
• references/regression-checklist.md：プロジェクトに依存しない回帰チェックリストです。
• references/chrome-extension-regression-example.md：任意で参照できるChrome 拡張機能の例です。
• references/decision-log-template.md：簡潔な意思決定記録のテンプレートです。