impl-peer-review

実装のピアレビュー

独立したレビュアーランタイムが、実装の差分に対して負荷の高いテストを行います。このスキルは、実装作業の後にユーザーから明示的な依頼があった場合に限り、LLM 間のレビューを実行します。対象は差分と、ユーザーが指定した --context ファイルに限定され、タスク追跡システムとは切り離されています。Compozy はレビューエンジンです。各ラウンドは、設定可能なランタイムに対する 1 回の compozy exec で構成されます。レビュアーが書き込む指摘ファイルのみが信頼できる唯一の情報源です。compozy exec の標準出力／標準エラーとイベントログは、運用上の証拠としてのみ扱ってください。

同梱ファイル

<skill-dir>（この SKILL.md のあるディレクトリ）を基準に、すべての scripts/<name> パスまたは references/<name> パスを解決してください。同梱ファイルはすべて読み取り専用です。読み取るか実行するだけにとどめ、ラウンド中に編集しないでください。

ユーザーへの質問

手順でユーザーに質問するよう指示された場合（どの指摘を取り込むか、もう一度ラウンドを実行するかなど）は、ランタイムの対話型質問ツール、つまり質問を提示してユーザーの回答まで待機するツール（例：AskUserQuestion）を使用してください。そのようなツールがランタイムにない場合は、質問だけを含むアシスタントメッセージを提示して停止してください。ユーザーの返信後にのみ、回答してください。

入力

すべての入力は任意です。デフォルト設定では、引数なしの impl-peer-review が一般的な使い方になります。

• --files <p1,p2,...> — ブランチ全体の差分ではなく、明示したパスをレビュー対象にします。
• --context <p1,p2,...> — レビュアーに渡す追加のコンテキストファイル（仕様書、ADR、設計ドキュメント、RFC、README など）です。このスキルは、これらのファイルが存在するとは想定しません。
• --base <git-ref> — 差分のベースとなる ref です。デフォルトは main です。対象範囲を絞るには --base HEAD~N を使用します。
• --staged — ブランチの差分ではなく、ステージ済みの変更のみ（git diff --staged）をレビューします。
• --out <dir> — ラウンドの成果物を出力するディレクトリです。「出力ディレクトリ」を参照してください。
• --verify <cmd> — 準備完了ゲートと修正後ゲートの両方で使う検証コマンド（ビルド／テスト）です。省略した場合は references/readiness-checks.md に従って自動検出します。適切なコマンドが見つからない場合は、ユーザーに質問してください。
• --ide <ide>（デフォルトは claude）：レビュアーランタイムです。compozy exec --ide に渡されます。使用できる値は compozy exec と同じです：codex、claude、cursor-agent、droid、opencode、pi、gemini、copilot。無効な値の場合は、使用できる値を列挙し、ユーザーに選択を求めてください。claude にフォールバックしないでください。
• --model <name>（デフォルトは opus）：compozy exec --model に渡されます。事前検証は行わず、互換性の問題は compozy に報告させてください（古いモデルへの対応についてはステップ 3 を参照）。
• --reasoning <effort>（デフォルトは xhigh）：compozy exec --reasoning-effort に渡されます。使用できる値：low、medium、high、xhigh。

出力ディレクトリ

<out> は次の順序で決定します。

1. 指定されている場合は --out を使用します。
2. それ以外の場合、現在の作業に対してリポジトリ内に明確な .compozy/tasks/<slug>/ の構成がある場合は、そのタスクの qa/ ディレクトリ .compozy/tasks/<slug>/qa/ を使用します。
3. それ以外の場合は、リポジトリルートの .peer-reviews/<UTC-timestamp-YYYYMMDDTHHMMSSZ>/ をデフォルトとして使用します。

ディレクトリが存在しない場合は作成してください。各成果物には -roundN を付けてバージョン管理します。以前のラウンドを上書きせず、次のラウンド番号を使用してください。

指摘の成果物

各ラウンドで信頼できる指摘ファイルは 1 つのみです：<out>/impl-review-findings-roundN.md。レビュアーが書き込むのはこのファイルだけです。指定先のパスが存在しない、曖昧、書き込み不可、または <out> の外にある場合、レビュアーは処理を拒否して停止します。標準出力へのフォールバックはありません。

指摘の形式（フロントマター、セクション見出し、項目ごとのフィールド）は references/impl-review-prompt.md で定義され、scripts/validate-findings.sh によって検証されます。

手順

ステップ 0：Compozy が利用可能か確認する compozy バイナリが PATH 上にあることを確認します（例：command -v compozy）。見つからない場合は、Compozy をインストールするよう1行のメッセージを表示して中止します。クロス LLM の独立性が重要なため、必須とし、ハーネスネイティブのサブエージェントにはフォールバックしません。このスキルは compozy exec を直接呼び出します。--agent のインストールは不要です。

ステップ 1：入力の検証とスコープの決定

1. ユーザーが実装作業を完了（または一時停止）した直後であり、現在の状態のレビューを明示的に依頼していることを確認します。編集中にレビューラウンドを実行してはいけません。
2. 差分のスコープを決定します。
   • --files が指定されている場合は、各パスが存在することを確認し、差分の対象をそれらのパスに限定します。
   • --staged が指定されている場合は、git diff --staged を使用します。
   • それ以外の場合は、git diff <base>...HEAD --name-only（<base> の既定値は main）を実行して変更されたファイルの一覧を取得します。差分が空の場合は中止し、レビュー対象がないことをユーザーに伝えます。
3. <out> を決定し（出力ディレクトリを参照）、必要に応じて作成します。
4. 検証コマンドを決定します（--verify、自動検出、それ以外はユーザーに確認）。
5. レビューを実行する前に、references/readiness-checks.md をすべて読みます。 すべてのレディネスマーカーがパスすることを確認します。マーカーと自動検出の順序はそのファイルに記載されています。マーカーが1つでも失敗した場合は、失敗したマーカーを報告して中止します。壊れた状態や未完了の変更に対する外部レビューは、クレジットを無駄にし、ノイズを生みます。
6. 既存の <out>/impl-review-findings-round*.md ファイルと <out>/impl-review-summary-round*.md ファイルを一覧表示して、次のレビューラウンド番号を決定します。ファイルがない場合は round1 から開始します。

ステップ 2：レビュー用プロンプトの作成

1. 停止してください。プロンプトを作成する前に、references/impl-review-prompt.md を最後まで読んでください。 このファイルは正式な実行可能レビュープロンプトのテンプレートです。プレースホルダーをそのまま置き換え、言い換えないでください。組み立てたプロンプトは、テンプレートを説明する Markdown のラッパーではなく、レビュアーへの指示から始めてください。
2. 差分ペイロードを取得します。
   • git diff <base>...HEAD -- <changed-files> を実行するか、--staged の場合は git diff --staged -- <changed-files> を実行し、未加工のパッチを <out>/impl-review-diff-roundN.patch に書き込みます。
   • git log --oneline <base>...HEAD -- <changed-files> を実行し、コミット一覧を取得します（--staged の場合は空文字列）。
3. <out>/ 以下にラウンドの成果物パスを定義します。impl-review-findings-roundN.md、impl-review-events-roundN.jsonl（イベントログ）、impl-review-result-roundN.err（標準エラー）、impl-review-status-before-roundN.txt、impl-review-status-after-roundN.txt、および impl-review-validation-error-roundN.md（必要な場合のみ）。
4. 既存のプロジェクトルールファイルを検出し、{project_rules} に設定します。対象は、ルートレベルの CLAUDE.md、AGENTS.md、.cursor/rules/*、.cursorrules、CONTRIBUTING.md、差分が変更するディレクトリ内のネストされた CLAUDE.md／AGENTS.md、およびプロジェクトのメモリ／指示ドキュメント（例：docs/_memory/、継続的な指示、教訓のインデックス）です。ネストされたルールやメモリには、ルートのみの検索では見落とす、重要な不変条件が含まれています。
5. プロンプトテンプレート内のプレースホルダーを置き換えます。
   • {scope_summary} — 実装内容を説明する段落を1つ記述します。ユーザーの依頼、コミットメッセージ、または --context が渡されている場合はリンク先の仕様／PRD から情報を得てください。
   • {context_paths} — --context で指定されたリポジトリルートからのパスを改行区切りで記述するか、none とします。レビュー対象の差分が仕様ディレクトリ（例：.compozy/tasks/<slug>/、specs/<name>/、docs/rfcs/<name>/）のタスクを実装している場合は、ユーザーが --context を指定していなくても、その仕様の契約を含む関連成果物もここに含めてください（「ガードレール：契約の整合性」を参照）。
   • {project_rules} — 検出したルールファイルのパスを改行区切りで記述するか、none とします。
   • {changed_files} — リポジトリルートからのパスを改行区切りで記述します。
   • {diff_path} — 手順 2 で作成したパッチファイルのリポジトリルートからのパスです。
   • {commit_list} — 取得した git log --oneline の出力です。--staged の場合は none とします。
   • {findings_path} — <out>/impl-review-findings-roundN.md の絶対パスを正確に指定します。
   • {round} — 数値のレビューラウンド N です。
6. 組み立てたプロンプトを <out>/impl-review-prompt-roundN.md に書き込みます。

ステップ 3：クロス LLM レビューを実行する

1. 実行前のステータススナップショットを取得します。

   git status --short > <out>/impl-review-status-before-roundN.txt
   

2. 次のコマンドを実行します（解決済みの --ide／--model／--reasoning を指定し、デフォルトは claude／opus／xhigh です）。

   compozy exec --ide <ide> --model <model> --reasoning-effort <reasoning> --format json --prompt-file <out>/impl-review-prompt-roundN.md > <out>/impl-review-events-roundN.jsonl 2> <out>/impl-review-result-roundN.err
   

3. 実行後のステータススナップショットを取得します。

   git status --short > <out>/impl-review-status-after-roundN.txt
   

4. コマンドがゼロ以外で終了した場合は、明示的に失敗として扱ってください。黙って再試行してはいけません。標準エラーに The model 'X' does not exist と表示された場合、ランタイムに古いモデル名が設定されている可能性があります。設定済みのモデルを提示し、再実行する前にユーザーに確認してください。モデルを独自に置き換えてはいけません。

5. コマンドの終了後、指摘事項の出力先ファイルが存在することを必ず確認してください。存在しない場合、compozy exec が 0 で終了していてもラウンドは無効です。impl-review-validation-error-roundN.md を作成し、再実行するかどうかをユーザーに確認してください。

ステップ 4：指摘事項を検証して要約する

1. 同梱の読み取り専用バリデーターを実行します。

   bash <skill-dir>/scripts/validate-findings.sh --kind implementation --round N --path <out>/impl-review-findings-roundN.md
   

2. 指摘事項のファイルを手動で確認し、セマンティックな契約を検証します。

   • すべての指摘事項に、実在するファイルパスと行番号、または該当しない明示的な理由があること。
   • ブロッカーには、プロジェクトのルールまたはアーキテクチャ上の制約に基づく根拠が含まれていること。
   • TBD、プレースホルダーテキスト、捏造されたパス、標準出力だけの指摘事項がないこと。
   • {context_paths} で仕様契約の成果物が渡されている場合、指摘事項で契約との同等性をフィールドごとに明示的に評価していること（「ガードレール：契約との同等性」を参照）。契約との同等性の評価がない SHIP 判定は無効なラウンドです。
   • 実行前後のステータススナップショットを比較し、想定されるレビュー成果物／ログのパス以外に変更がないこと。

3. 検証に失敗した場合は、失敗したチェック項目、コマンド、終了ステータス、成果物のパスを記載した <out>/impl-review-validation-error-roundN.md を作成します。このラウンドを SHIP として要約しないでください。

4. 検証済みの指摘事項ファイルに基づいて、以下を含む <out>/impl-review-summary-roundN.md を作成します。判定（SHIP／FIX_BEFORE_SHIP／REWORK）、各ブロッカーの1行の根拠、リスクの一覧、軽微な指摘事項の一覧、修正による影響を最も受ける可能性が高いファイル、運用成果物のパス。

5. ユーザー向けに、判定、ブロッカー／リスク／軽微な指摘事項の件数、主なテーマ、このラウンドで作成した成果物のパスを簡潔にまとめます。

6. ステップ5までは、ソース、テスト、設定、ドキュメント、コミットへの変更を保留します。

ステップ5：ユーザー指示による修正

1. どの指摘事項を反映するか、ユーザーに確認します。
   • A）すべてのブロッカー
   • B）選択したブロッカー／リスク／軽微な指摘事項
   • C）何も反映しない — レビュー記録のみを残す
   • D）修正に入る前に手動で編集する
2. ユーザーが選択した指摘事項のみを適用します。
3. コードを変更した場合は、変更を適用した後に解決確認コマンドを再実行します。失敗した場合は、新たな失敗を修正するか、修正完了とする前にユーザーへ伝えます。
4. <out>/impl-review-remediation-roundN.md に修正の判断を記録します。反映した項目と新しいコミット／差分範囲、保留した項目、変更したファイル、確認コマンドと実行結果およびタイムスタンプを記載します。
5. 変更した内容と保留中の項目をユーザーに提示します。ユーザーから明示的な指示がない限り、コミットまたはプッシュしません。

ステップ6：任意の追加ラウンド

1. 更新後のコードを対象に別のピアレビューを行うか、現在の状態で終了するか、ユーザーに確認します。
2. ユーザーが明示的に依頼した場合にのみ、追加ラウンドを実施します。新しい差分を対象にステップ2から再実行し、同じ <out> ディレクトリに新しい roundN+1 の成果物一式を作成します。

ガードレール

契約との同等性。 仕様ワークフローの差分では、エンジニアリング品質だけを理由に SHIP と判定することはできません。差分が仕様ディレクトリ（.compozy/tasks/<slug>/、specs/<name>/、docs/rfcs/<name>/）のタスクを実装するものである場合、レビュー担当者には、その仕様の契約を含む関連成果物（標準例のドキュメント、入力／スキーマの表、QA シード、テスト契約、同等性マップ）が渡されている必要があります。成果物をフィールドごとに照合して評価してください。{context_paths} からこれらの成果物が除外されているラウンドは無効です。タスクファイルの言い換えだけでは、契約の情報源として不十分です。実際に、標準例のドキュメントが渡されなかったため、成果物が仕様に反していることを見抜けず、7 ラウンドにわたり SHIP と判定された事例があります。

クレジットは1回のみ。 このスキルで外部レビューのクレジットを消費するのは compozy exec だけです。1ラウンドにつき1回実行してください。ラウンドが無効であり、ユーザーから再実行の依頼があった場合に限り、再実行します。