review-forge

Review Forge

Review Forge は、保守的で機能スコープを限定したコードレビューのワークフローを実行します。

1. 対象の差分とプロジェクトのコンテキストを確認します。
2. 現在の機能フォルダー内に、モデルまたはエージェントごとのレビュー ファイルを1つ作成します。
3. 複数のモデルレビュー ファイルを、人が管理するチェックリストにまとめます。
4. チェック済みで、確認も完了した項目だけを修正します。
5. 修正の各バッチ後に、対象を絞ったテストと回帰テストを実行します。
6. 可能な場合は、修正を独立した視点から検証します。
7. 機械可読なステータスと、ローカライズされたレポートラベルを更新します。
8. すべてのワークフロー成果物をプロダクトコードから分離します。

コマンド

• review：モデル固有のレビュー ファイルを1つ作成します。プロダクトコードは変更しません。
• synthesize：1つの機能フォルダーにあるモデルレビュー ファイルを1つの要約チェックリストに統合します。プロダクトコードは変更しません。
• fix：チェック済みの要約項目を読み取り、選択されたスコープを確認して、その項目だけを実装し、テストを実行して、ステータスを更新します。
• verify：独立した視点から修正済み項目を検証し、テストを再実行または確認して、検証ステータスを更新します。

レガシーモードのエイリアスもサポートされています。

• review-only は、ユーザーが既存のレビュー ファイルの統合を求めている場合を除き、review を意味します。その場合は synthesize を意味します。
• review-and-fix は fix を意味します。
• review-verify は verify を意味します。

ユーザーがコマンドを指定しない場合は、リクエストに基づいて最も安全なコマンドを推定します。曖昧な場合は、review をデフォルトにします。

入力

作業を開始する前に、次の入力を解決するか、ユーザーに確認してください。

• target：ブランチ、コミット範囲、プルリクエスト、または現在の作業ツリー。
• base：比較対象のブランチまたは参照。省略された場合は、以下のデフォルトの差分ルールに基づいて推定します。
• artifact_root：デフォルトは code_review/。
• feature：成果物のサブフォルダー名として使用する機能名。省略された場合は、ブランチ名、PR タイトル、変更されたパッケージ、または差分の短いサニタイズ済み要約から推定します。
• feature_dir：デフォルトは code_review/<feature>/。
• command：review、synthesize、fix、verify のいずれか。
• model：レビュー ファイルに使用するモデル名またはエージェント名。例：codex、opencode、cursor、claude、gemini。
• report_language：デフォルトは auto で、ユーザーのプロンプトの言語に従います。en、zh-CN、ja などの明示的な値も使用できます。
• auto_fix_allowed：ユーザーが明示的に修正を依頼していない限り、デフォルトは false。
• perspective：任意のレビュー観点。例：正確性、セキュリティ、保守性、テスト、UX。
• test_command：任意の検証コマンドの上書き設定。

デフォルトの差分ルール

ユーザーが対象またはベースを指定しない場合は、次の順序でレビュー範囲を推定します。

1. 作業ツリーまたはインデックスに未コミットの変更がある場合は、未コミットの差分をレビューします。
   • ステージング前とステージング済みの両方の変更を確認します。
   • これを target: working tree として扱います。
   • 追加のコンテキストが必要でない限り、ベースブランチは不要です。
2. 未コミットの変更がない場合は、現在の HEAD と main を比較してレビューします。
   • サポートされている場合は、main...HEAD などのマージベース比較を優先します。
   • main が存在しない場合は、master...HEAD を試します。
3. main と master のどちらも存在しない場合は、利用可能であればブランチの追跡メタデータまたは PR メタデータを調べます。
4. 妥当な比較参照を推定できない場合に限り、ユーザーに base を確認します。

ユーザーが明示的に指定した PR、ブランチ、コミット範囲、またはベース参照は、常にこれらのデフォルトより優先されます。

必須の初期確認

成果物の作成やコードの変更を行う前に、次の項目を確認します。

• リポジトリのステータスと未コミットの変更。
• 選択したベースに対する対象の差分。
• 既存の code_review/ 機能フォルダーとレビュー成果物。
• code_review/ に関する .gitignore の設定。
• パッケージ、ビルド、テストの設定。
• テスト、lint、型チェック、CI に関するプロジェクト固有の指示。

無関係なユーザー変更は絶対に元に戻さないでください。code_review/ が無視対象でない場合は、.gitignore への追加を推奨しますが、ユーザーから依頼されない限り .gitignore は編集しないでください。

成果物の構成

すべてのワークフローを機能ごとにまとめます。

code_review/<feature>/
  <model>.md
  <model>-<perspective>.md
  summary.md
  fix-plan.md
  verify.md
  status.md

ルール：

• モデルによるレビューを1回行うごとに、レビュー用ファイルをちょうど1つ作成します。
• レビュー用ファイル名の先頭には、モデル名またはエージェント名を付けます。例：codex.md、opencode.md、cursor.md、claude.md。
• 同じモデルで複数の観点から実行する場合は、codex-security.mdのように短い観点名のサフィックスを付けます。
• デフォルトではタイムスタンプを含めません。フォルダー内を確認しやすいよう、安定した名前を使用します。
• 複数の過去の実行履歴を保持するよう明示的に求められた場合にのみ、タイムスタンプを使用します。

コマンドの出力境界：

• review：codex.mdのように、モデルのレビュー用ファイルをちょうど1つ作成または上書きします。summary.md、fix-plan.md、verify.md、status.mdは作成しません。
• synthesize：モデルのレビュー用ファイルを読み取り、summary.mdを作成または上書きします。status.mdは作成しません。
• fix：summary.mdからチェック済みの項目を読み取り、fix-plan.mdを作成または更新します。コード変更とテストの後に、status.mdを作成または更新します。
• verify：verify.mdを作成または更新し、検証の根拠を含めてstatus.mdを更新します。

STATUS_20260529.md、REVIEW_SUMMARY_20260529.md、CODE_REVIEW_codex_20260529.mdのような従来のタイムスタンプ付きファイル名は、日付付きの過去の履歴を保持するようユーザーから明示的に求められない限り、作成しないでください。

リポジトリに独自のより確立された規約がない場合は、assets/templates/のテンプレートを使用します。

レビューの収集

reviewコマンドでは、現在のモデルまたはエージェント用に1つのファイルを作成します。ユーザーがmodelを指定していない場合、明らかであれば実行環境から推測します。それ以外の場合は、codexのような分かりやすい名前を使用します。

複数モデルのワークフローでは、各モデルが個別にreviewを実行し、同じfeature_dirに出力します。必要に応じて、異なる観点を指定します。

• 正確性とエッジケース
• セキュリティとデータの安全性
• テストと回帰リスク
• 保守性とアーキテクチャ
• 該当する場合は、プロダクトの動作またはUX

各指摘には、重大度、根拠、影響を受けるファイル、リスク、具体的な修正案を含めます。保守性やユーザー向けの動作に影響しない限り、曖昧なスタイル上の好みは避けてください。

Synthesize コマンド

synthesizeコマンドでは、1つのfeature_dirからレビュー用ファイルを読み取り、summary.mdを作成します。

• デフォルトでは、フォルダー内のすべてのモデルのレビュー用ファイルを選択します。
• summary.md、fix-plan.md、verify.md、status.mdは除外します。
• 重複する指摘を統合します。
• 意味のある見解の相違は保持します。
• レビュアーの合意数を記録します。
• 推奨テストを含めます。
• 人が修正を承認できるよう、チェックボックスを使用します。

チェックボックスの意味は次のとおりです。

• 未チェック：修正は承認されていません。
• チェック済み：修正が承認されています。

未チェックの問題を、ついでに修正してはいけません。

修正のルール

fixコマンドでは、次の手順に従います。

1. 選択したfeature_dirからsummary.mdを読み取ります。
2. 修正可能なステータスのチェック済み項目だけを選択します。
3. ユーザーがすでに明示的に承認している場合を除き、修正範囲を確認します。
4. fix-plan.mdを作成または更新します。
5. 選択した項目に必要なファイルだけを変更します。
6. テストを実行します。
7. status.mdを更新し、必要に応じてサマリーのステータス項目も更新します。

チェック済みの項目から、より大きな問題が判明した場合は、範囲を拡大する前に作業を止めて確認してください。

テストのルール

不可能な場合を除き、修正後のテストは必須です。

次の順序で検証します。

1. 対象の動作に関するテストのうち、特定できるものの中で最も範囲の狭いもの。
2. 変更したファイルに関連する型チェック、lint、またはビルドのチェック。
3. 特定可能で、範囲が妥当な場合は、プロジェクト全体の回帰テストコマンド。

テストを実行できない場合は、次の内容を記録します。

• ステータス列挙値test_blocked
• 実行すべきだったコマンド
• 実行を妨げた理由
• 残存するリスク

テストが失敗した場合は、項目を修正済みまたは検証済みと主張してはいけません。該当する項目をverification_failedまたはpartially_fixedとしてマークし、失敗したコマンドを記録して、失敗の概要をまとめてください。

検証ルール

verify コマンドでは：

• 可能な場合は、修正担当者とは独立した視点で検証します；
• 選択した各指摘事項が実際に対処されたか確認します；
• テストの証拠を再確認するか、調査します；
• 修正によって発生したリグレッションを探します；
• 証拠に裏付けられている場合にのみステータスを更新します。

検証には、テストが合格した証拠、または明確な test_blocked の説明が必要です。

言語ポリシー

スキルの指示、テンプレートのフィールド名、機械可読なステータス列挙値は英語で記述します。

生成される文章レポートでは report_language を使用します：

• auto：ユーザーのプロンプトの言語に従います；
• 明示的な言語値：その言語で文章を記述します；
• ローカライズされたレポート内でも、ステータス列挙値は英語のままにします。

ステータスの表示ラベルはローカライズできます。

ステータス列挙値

次の機械可読なステータス値を正確に使用します：

• open
• approved_for_fix
• fixed
• partially_fixed
• wont_fix
• risk_accepted
• verified
• verification_failed
• test_blocked

各ステータス項目には、次の両方を含める必要があります：

• status：上記の列挙値のいずれか；
• status_label：人が読めるローカライズされたラベル。例：Fixed ✅ または 已修复 ✅。

完了基準

Review Forge ワークフローが完了するのは、次の条件をすべて満たした場合に限ります：

• レビュー成果物が feature_dir の下にある；
• チェック済みの項目のみが修正されている；
• 修正後にテストの証拠、または test_blocked の根拠が記録されている；
• 検証ステータスが実際以上のことを示していない；
• プロセス成果物が製品コードから分離されている。