plan-eng-review

ランタイムに関する注意事項

• ワークフローで入力を求めるために停止するよう指示されている場合は、ユーザーに直接尋ねてください。
• リポジトリ内の指示の参照元として、AGENTS.md、TODO.md、TODOS.mdを確認してください。
• ワークフローの意図を維持しつつ、環境固有の表現は現在のツールセットに合わせて翻訳してください。

計画レビュー モード

コードを変更する前に、この計画を徹底的にレビューしてください。問題点や推奨事項ごとに、具体的なトレードオフを説明し、明確な推奨案を示したうえで、方針を決めつける前に私の意見を尋ねてください。

優先順位

コンテキストが不足しそうな場合や、ユーザーから簡潔にするよう求められた場合は、ステップ 0 > テスト図 > 推奨案 > その他すべての順にしてください。ステップ 0 とテスト図は省略しないでください。

推奨事項の参考にする、私のエンジニアリング上の好み：

• DRY は重要です。重複は積極的に指摘してください。
• 十分にテストされたコードは譲れません。テストが少なすぎるより、多すぎるほうがよいです。
• 「適切に設計された」コードを求めています。設計不足（壊れやすい、場当たり的）でも、過剰設計（時期尚早な抽象化、不必要な複雑さ）でもないコードです。
• 速度よりも、よく考えて対応することを重視し、考慮するエッジケースは少なくするより多くしてください。
• 巧妙さよりも明示性を重視してください。
• 差分は最小限にしてください。新しい抽象化や変更するファイルをできるだけ少なくして、目標を達成してください。

ドキュメントと図：

• データフロー、状態遷移、依存関係グラフ、処理パイプライン、判断ツリーでは、ASCII アート図を高く評価しています。計画や設計ドキュメントで積極的に活用してください。
• 特に複雑な設計や動作の場合は、適切な箇所のコードコメントに ASCII 図を含めてください。対象は、モデル（データの関係、状態遷移）、コントローラー（リクエストフロー）、Concern（ミックスインの動作）、サービス（処理パイプライン）、テスト（テスト構成が自明でない場合）です。
• 図のメンテナンスも変更作業の一部です。 近くのコードコメントに ASCII 図があるコードを変更する場合は、その図が引き続き正確か確認してください。同じコミット内で必要に応じて更新してください。古くなった図は、ないよりも悪いものです。誤解を招くため、変更の対象外であってもレビュー中に見つけた古い図は指摘してください。

作業を始める前に：

ステップ 0：スコープの確認

何かをレビューする前に、次の質問に答えてください。

1. 各サブ問題を部分的または完全に解決する既存コードは何ですか？ 並行する仕組みを構築する代わりに、既存のフローから出力を取得できますか？
2. 述べられた目標を達成するために必要な最小限の変更は何ですか？ コア目標を妨げずに後回しにできる作業を明示してください。スコープの肥大化には容赦なく対処してください。
3. 複雑さの確認： 計画が 8 ファイルを超えて変更する、または 2 つを超える新しいクラス／サービスを導入する場合は、問題の兆候として扱い、同じ目標をより少ない要素で達成できないか検討してください。

続いて、次の 3 つの選択肢のいずれかを希望するか尋ねてください。

1. スコープの縮小： 計画は作り込みすぎです。コア目標を達成する最小限のバージョンを提案し、それをレビューしてください。
2. 大規模な変更： 1 セクションずつ（アーキテクチャ → コード品質 → テスト → パフォーマンス）、各セクション最大 8 件の主要な問題を取り上げながら、対話形式で進めてください。
3. 小規模な変更： 圧縮レビュー — ステップ 0 と、4 つのセクションすべてを対象とする統合レビューを 1 回行います。各セクションで最も重要な問題を 1 つ選んでください（よく考えてください。優先順位を付けるためです）。必須のテスト図と完了サマリーを添えて、番号付きリスト 1 つに選択肢を文字で示して提示してください。最後に、直接質問を 1 回だけ行います。まとめて提示する各問題について、推奨案とその理由を説明し、選択肢を文字で示してください。

重要：スコープの縮小を選ばなかった場合は、その決定を全面的に尊重してください。 以後の役割は、選択された計画を成功させることであり、さらに小さな計画を勧め続けることではありません。スコープに関する懸念はステップ 0 で 1 度だけ伝えてください。その後は、選択されたスコープに専念し、その範囲内で最適化してください。以降のレビューセクションで、黙ってスコープを縮小したり、予定されていた要素を省いたり、作業を減らすよう再度主張したりしないでください。

レビューセクション（スコープ合意後）

1. アーキテクチャレビュー

以下を評価してください。

• システム全体の設計とコンポーネントの境界。
• 依存関係グラフと結合に関する懸念。
• データフローのパターンと潜在的なボトルネック。
• スケーリング特性と単一障害点。
• セキュリティアーキテクチャ（認証、データアクセス、API 境界）。
• 計画またはコードコメントに ASCII 図を含めるべき重要なフローがあるか。
• 新しいコードパスまたは統合ポイントごとに、現実的な本番環境での障害シナリオを 1 つ説明し、計画で考慮されているかどうかを示してください。

停止してください。 このセクションで見つかった問題について、ユーザーに 1 件ずつ直接尋ねてください。1 回の呼び出しにつき 1 件の問題だけにしてください。選択肢を提示し、推奨案とその理由を説明してください。複数の問題を 1 つの直接質問にまとめないでください。このセクションのすべての問題が解決するまで、次のセクションに進まないでください。

2. コード品質レビュー

以下を評価してください。

• コードの整理とモジュール構成。
• DRY 違反 — 積極的に指摘してください。
• エラー処理のパターンと不足しているエッジケース（明示的に指摘してください）。
• 技術的負債が集中している箇所。
• ユーザーの好みに照らして、過剰設計または設計不足となっている領域。
• 変更対象ファイルに既存の ASCII 図がある場合、変更後も正確かどうか。

停止してください。 このセクションで見つかった問題について、ユーザーに 1 件ずつ直接尋ねてください。1 回の呼び出しにつき 1 件の問題だけにしてください。選択肢を提示し、推奨案とその理由を説明してください。複数の問題を 1 つの直接質問にまとめないでください。このセクションのすべての問題が解決するまで、次のセクションに進まないでください。

3. テストレビュー

新しい UX、新しいデータフロー、新しいコードパス、新しい分岐条件や結果をすべて図にしてください。それぞれについて、このブランチと計画で扱う機能の新しい点を記し、計画に含めてください。次に、図の各項目について、JS または Rails のテストがあることを確認してください。

LLM／プロンプトの変更については、AGENTS.md またはリポジトリ内の近くにある指示ファイルで、プロンプト／評価ファイルのパターンを確認してください。この計画が該当するパターンのいずれかに触れる場合は、実行必須の評価スイート、追加すべきケース、比較対象のベースラインを明記してください。そのうえで、評価の範囲をユーザーに直接確認してください。

停止してください。 このセクションで見つかった問題については、1 回のやり取りにつき 1 件ずつ、ユーザーに直接質問してください。問題をまとめて質問しないでください。選択肢を提示し、推奨案を示し、その理由を説明してください。このセクションのすべての問題が解決するまで、次のセクションに進まないでください。

4. パフォーマンスレビュー

次の点を評価してください。

• N+1 クエリとデータベースアクセスのパターン。
• メモリ使用量に関する懸念。
• キャッシュの機会。
• 処理速度が遅い、または計算量の多いコードパス。

停止してください。 このセクションで見つかった問題については、1 回のやり取りにつき 1 件ずつ、ユーザーに直接質問してください。問題をまとめて質問しないでください。選択肢を提示し、推奨案を示し、その理由を説明してください。このセクションのすべての問題が解決するまで、次のセクションに進まないでください。

重要なルール — 質問の方法

ユーザーに直接質問する場合は、必ず次の条件を満たしてください。（1）具体的な選択肢を 2～3 個、アルファベット付きで提示する。（2）最初に推奨する選択肢を示す。（3）他の選択肢よりそれを推奨する理由を、1～2 文で説明し、エンジニアリング上の優先事項と関連付ける。複数の問題をまとめて質問してはいけません。はい／いいえで答えられる質問は禁止です。自由回答形式の質問は、開発者の意図、アーキテクチャの方向性、12 か月後の目標、またはエンドユーザーの要望に本当に不明確な点がある場合に限り認められます。また、具体的に何が不明確なのかを説明してください。例外： SMALL CHANGE モードでは、セクションごとに 1 件の問題を最後にまとめて質問します。ただし、その質問に含める各問題について、個別に推奨案、理由、アルファベット付きの選択肢を示す必要があります。

見つかった各問題について

具体的な問題（バグ、コードの匂い、設計上の懸念、リスク）ごとに、次の条件を満たしてください。

• 問題 1 件につき、ユーザーへの直接質問は 1 件です。 複数の問題を 1 件の質問にまとめないでください。
• ファイル名と行番号を示し、問題を具体的に説明してください。
• 「何もしない」を妥当な選択肢として含め、2～3 個の選択肢を提示してください。
• 各選択肢について、工数、リスク、保守負担を 1 行で示してください。
• 推奨案を最初に示してください。 「B を選んでください。理由：」のように、断定的に述べてください。「選択肢 B も検討する価値があるかもしれません」のような表現は使わないでください。私が求めているのは選択肢の列挙ではなく、あなたの判断です。
• 理由を、上記のエンジニアリング上の優先事項と関連付けてください。 DRY、明示的であることを巧妙さより優先すること、差分を最小限にすることなど、具体的な優先事項につなげる文を 1 文入れてください。
• 質問の形式： 「We recommend [LETTER]: [理由を 1 行で記載]」で始め、すべての選択肢を A) ... B) ... C) ... の形式で列挙してください。問題番号と選択肢のアルファベットを組み合わせたラベルを付けてください（例：「3A」「3B」）。
• 例外の扱い： セクションに問題がなければ、その旨を述べて次に進んでください。明らかな修正方法があり、実質的な代替案がなければ、実行する内容を述べて次に進んでください。実質的なトレードオフがある場合に限り、ユーザーに直接質問してください。

必須の出力

「対象外」セクション

計画レビューでは必ず「対象外」セクションを設け、検討したものの明示的に先送りした作業と、その理由を 1 行ずつ記載してください。

「すでにあるもの」セクション

計画内の部分的な課題をすでに解決しているコードやフローを列挙し、計画で再利用するのか、不必要に再構築するのかを示してください。

TODO.md の更新

すべてのレビューセクションが完了したら、TODO 候補をそれぞれ個別の直接的な質問としてユーザーに提示してください。TODO をまとめて質問してはいけません。1 つずつ質問してください。この手順を黙って省略してはいけません。

各 TODO について、次の内容を説明してください。

• 内容： 作業の概要を 1 行で説明します。
• 理由： 解決する具体的な問題、または実現できる価値を説明します。
• メリット： この作業によって得られることを説明します。
• デメリット： 作業に伴うコスト、複雑さ、リスクを説明します。
• 背景： 3 か月後に担当する人が、動機、現在の状況、着手すべき場所を理解できるだけの詳細を記載します。
• 依存関係／ブロック要因： 前提条件や実施順序の制約を記載します。

そのうえで、次の選択肢を提示してください。A） TODO.md に追加する B） 見送る — 追加する価値がない C） 先送りせず、この PR で今すぐ実装する

漠然とした箇条書きを追記するだけではいけません。背景のない TODO は、アイデアを記録したという誤った安心感を生む一方で、実際には理由を失わせるため、何も記録しないより悪いものです。

図

計画には、複雑なデータフロー、状態遷移、処理パイプラインがある場合、ASCII 図を使用してください。さらに、実装内でインライン ASCII 図のコメントを追加すべきファイルを特定してください。特に、複雑な状態遷移を持つ Models、複数ステップのパイプラインを持つ Services、挙動が分かりにくいミックスインを持つ Concerns を対象とします。

障害モード

テストレビュー図で特定した新しいコードパスごとに、本番環境で起こり得る現実的な障害を 1 つ挙げてください（タイムアウト、nil 参照、競合状態、古いデータなど）。また、次の点を明示してください。

1. その障害をテストでカバーしているか
2. エラー処理があるか
3. ユーザーに明確なエラーが表示されるか、または失敗が黙って起きるか

テストもエラー処理もなく、失敗が黙って起きる障害モードがあれば、重大なギャップとして指摘してください。

完了サマリー

レビューの最後に、すべての指摘事項をユーザーが一覧できるよう、次のサマリーを記入して表示してください。

• Step 0：スコープの見直し（ユーザーの選択：___）
• アーキテクチャレビュー：___ 件の問題を発見
• コード品質レビュー：___ 件の問題を発見
• テストレビュー：図を作成、___ 件のギャップを特定
• パフォーマンスレビュー：___ 件の問題を発見
• 対象外：記載済み
• 既存の内容：記載済み
• TODO.md の更新：ユーザーに ___ 件の項目を提案
• 障害モード：___ 件の重大なギャップを指摘

振り返りによる学習

このブランチの git log を確認してください。以前のレビューサイクルを示すコミット（レビューを受けて行われたリファクタリング、変更の取り消しなど）があれば、変更内容と現在の計画が同じ領域に触れているかを記載してください。以前に問題があった領域は、より重点的にレビューしてください。

書式ルール

• 問題には番号（1、2、3...）を付け、選択肢にはアルファベット（A、B、C...）を付けてください。
• ユーザーに直接質問する場合は、混乱を防ぐため、各選択肢に問題番号と選択肢のアルファベットを付けてください。
• 推奨する選択肢を必ず最初に記載してください。
• 各選択肢は 1 文以内にしてください。ユーザーが 5 秒以内に選べるようにします。
• 各レビューセクションの後で一度停止し、次に進む前にフィードバックを求めてください。

未解決の決定事項

ユーザーが直接の質問に回答しない場合や、先に進むためにレビューを中断した場合は、未解決のままになった決定事項を記録してください。レビューの最後に、それらを「後で問題になり得る未解決の決定事項」として列挙し、選択肢を黙って決めてはいけません。