qodo-review

ローカルレビュー

説明

コーディング中、および完成した作業を引き渡す前に、ローカルの変更をレビューします。qodo review は、差分、新規／未追跡ファイル、コーディングセッションのコンテキストを Qodo に送信します。構造化された指摘事項を評価し、許可された修正を適用してください。リモートに存在している必要があるのはベースコミットだけです。このコマンドがプッシュや PR の作成を行うことはありません。

プッシュ前の作業を含む、ローカルの変更にはこのスキルを使用してください。PR のリモートレビューで指摘された事項に対応する場合は qodo-review-resolver を使用してください。変更されていないプッシュ済みのスナップショットに対して、同じレビューを重複して実施しないでください。

前提条件

• 認証済みの Qodo CLI、または接続済みの QAR MCP サーバーとテスト済みのローカル入力収集ツールが利用可能であり、レビュー機能が有効になっていること。
• 比較対象のベースがリモートに存在すること。ローカルの変更とコンテキストは、プッシュされている必要はありません。
• コーディングセッションのコンテキスト、および添付するチケットや設計資料が準備できていること。

レビューのタイミングと深さを選ぶ

状況	選択
本格的なコーディング中の、一貫性のあるマイルストーン	--fast --async：軽いチェックポイントとしてレビューします。有益なコーディングを続け、結果を回収します。
PR の作成／更新、または完成した作業の引き渡し前に行う通常の最終レビュー	深さを指定するフラグをどちらも省略します：自動。レビュー完了を宣言する前に、結果を回収して評価します。
ユーザーの意図から通常より綿密な精査が求められる場合、または既知の広範囲に及ぶ影響が懸念される場合	--deep を指定し、依頼内容または影響を受ける動作に関連した簡潔な理由を添えます。

自動コーディングチェックポイントでは、常に --fast を使用します。上記の例外に該当する場合は、意図的に深いレビューを早い段階で行うことができます。「微妙な競合状態を徹底的に調べて」のような依頼は、「deep」という語がなくても、その理由になります。一方、一般的な「レビューして」や「念のため再確認して」だけでは理由になりません。共有認可、破壊的なマイグレーション、複数のサービスが利用する契約など、具体的な影響を特定してください。差分の規模、セッションの長さ、PR の準備状況、セキュリティ関連のファイル名だけでは、deep を選ぶ理由になりません。

フラグを指定しない場合、CLI は深さを指定せず、レビュー担当者／デプロイ環境が選択します。自動選択で deep になることもあります。標準の深さが保証されるわけではなく、費用の上限も設定されません。--standard フラグはありません。--fast と --deep は同時に使用できません。深さは呼び出しのたびに選択されます。

チェックポイントと最終引き継ぎ

• フィードバックを残りの作業に活用できる段階になったら、完了済みでテスト可能な作業単位をレビューします。未完了の調査、編集のたびのレビュー、些細な変更の自動レビュー、あるいは単に時間が経過したという理由でレビューしないでください。ユーザーが指定したレビュー範囲と予算を守ってください。質問や承認を待つための一時停止は、最終引き継ぎではありません。
• タスクごとに、自動チェックポイントは常に最大1つだけ有効にしてください。その操作 ID、送信した範囲、スナップショットとコンテキストの関連付けを、タスクの既存の状態に保持します。有用な作業を続けながら、自然な区切りでステータスを確認してください。進捗確認のために別のレビューを開始したり、変更されていない入力を再レビューしたりしないでください。
• 送信した結果はすべて、保持期間内に収集してください。指摘に対応する前に、現在のコードと照らし合わせて再確認してください。作業ツリーは変更されている可能性があります。置き換えられた結果では、より新しい作業を証明できません。既存の CLI ライフサイクルを使用してください。別のサブエージェントやスケジューラーは不要です。
• 最終レビューの前に、未回収のチェックポイント結果を収集し、その指摘を整理してください。軽いチェックポイントだけで引き継ぐのではなく、auto、または妥当な理由がある場合は deep で、意図した変更全体をレビューします。意図した変更の一部が未レビューになるような一時的なパス制限は解除してください。同じスナップショットが、互換性のあるコンテキストで既に最終レビューを完了している場合は、その結果を使用してください。
• 許可された修正をまとめて適用し、検証したうえで、変更した作業を再レビューします。チェックポイントの修正には --fast を使用し、最終レビューの修正では、要求された auto モード、または妥当な理由がある場合は deep モードを維持してください。増分レビューの適用可否はエンジンに判断させてください。auto では各パスで異なるルーティングになる場合があります。最終修正で手動で --fast に切り替えたり、auto のルーティングを固定するために --deep を強制したりしないでください。実装作業が大幅に再開された場合は、軽いチェックポイントを再開し、引き継ぎ前に最終レビューの対象範囲を改めて確保してください。
• 実行可能な進展がないまま、別のレビューで同じ懸念が繰り返される場合は、自動ループを停止し、残っている問題と必要な判断・確認事項を報告してください。指摘をゼロにするためにレビューを繰り返してはいけません。保留中、失敗、一部のみのレビュー、または置き換えられたレビューは、問題がない状態ではありません。残る指摘とレビュー範囲を明示してください。

PR の引き継ぎ準備

PR を作成または更新する準備をする際は、ユーザーのコミットポリシーに従い、最終ローカルレビューの前に意図した変更をコミットすることを優先してください。ローカルから PR への引き継ぎに対応した Git レビューは、その検証済みのコミットから続行できます。 その後に編集をコミットした場合は、それらも含めるために改めてレビューしてください。コミットは任意です。レビュー済みで利用可能なコミットがない場合、Git レビューは通常の範囲に従います。 許可されたメモのメンテナンスでは、qodo-review-notes を使用して追跡対象を確認します。PR を開く前に既存の HEAD の PR メモを公開し、HEAD が変わった場合は更新してから、その後で関連付けます。ローカルのレビューコンテキストを保持し、その消費状況は別途検証してください。

指示

実行パスを選択する

利用可能な場合は、qodo review を優先してください。追跡対象および未追跡のローカル変更を収集して絞り込み、リモートのベースを解決し、コンテキストを添付して、チェックポイントの状態を管理します。一方、QAR MCP の start-pre-pr-review ツールは、準備済みの diff、base_sha、リポジトリの場所情報、コンテキストを受け取ります。この作業ツリーを読み取ることはできません。この MCP ツールは、テスト済みのローカルコレクターが同じ対象範囲と除外条件を生成し、省略されたファイルを報告し、ベース SHA がフェッチ可能であることを確認した場合にのみ使用してください。場当たり的に git diff を組み立て、同等のカバレッジがあるものとして呼び出さないでください。 コレクターを利用できない場合は、MCP のみを使ったローカルレビューではこの作業ツリーを安全にカバーできないと報告してください。レビューが完了したと主張しないでください。

準備済みの MCP レビューでは、実行時のスキーマを確認してください。review_scope.stream_id には、ちょうど 64 文字の小文字の16進数を設定してください。これは、解決済みの実際の作業ツリーのルートと、パスを限定したレビューの場合は解決済みの作業ディレクトリを含む JSON 配列の SHA-256 です。チェックポイント間で再利用してください。UUID は無効です。 結果が不確かな開始処理では、同じ request_id と完全に同一の引数を保持してください。request_id はこの開始ツールにおける論理アクションの再試行キーであり、別個の idempotency_key 引数は定義されていません。通知された間隔で get-managed-agent-operation をポーリングし、その後、すべての get-managed-agent-result チャンクを取得して、アーティファクトを解釈する前に、報告されたダイジェストとバイト数を検証してください。 これらは短いライフサイクル呼び出しであり、MCP Tasks ではありません。レシートを読む前に isError を確認してください。以下のコンテキスト、深さ、カバレッジ、検出事項、権限に関するルールを同様に適用してください。以下の CLI のバージョン、ID、コマンドに関する指示は、CLI パスにのみ適用されます。

通知を保持し、自己完結したコンテキストを添付し、進行状況を示し、適切なタイムアウトを設定し、 構造化された結果を読み取り、検出事項に対応してください。

スキルの更新通知への対応

古い CLI が対応を求める場合でも、QODO_NOTICE の更新は受動的な通知として扱ってください。インベントリ確認や更新に関する質問をせずにタスクを続行し、各イベントには最大 1 回だけ言及してください。通知を閉じても、記録済みのメンテナンスポリシーやオプトアウトは変更されません。更新されたスキルは次のセッションで読み込まれます。このセッションを中断しないでください。 ユーザーから更新を依頼された場合は、手動更新手順に従ってください。

実行

• MCP：実行時のスキーマ引数を使用し、CLI のシェル手順は省略してください。
• CLI：BOM のない完全な UTF-8 ファイルを使用してください（ツールには --args-file、レビューには --context-file）。例は POSIX 向けです。
• Windows CLI：最初の呼び出しの前にシェルのガイダンスを読み、呼び出しに失敗した場合にのみランチャーの復旧手順を参照してください。解決済みの呼び出し方法を再利用してください。

ランタイム互換性ゲート

このスキルのコマンド未検出時のフォールバックを使って実行ファイルを解決し、プロベナンスフラグを付けずに <qodo> --version を実行してください。このスキルには、Qodo CLI 2.0.0 以降と、レビュー API v2 を備えたランタイムが必要です。 バージョンが古い、または解析できない場合は、whoami、login、レビューを実行せず、認証の失敗と見なさないでください。 自動更新はメジャーバージョンの範囲内に限られます。Qodo または組織が提供するチェックサム固定のインストーラーを使って明示的に 2.x をインストールする場合は、事前に一度だけ確認を求めてください。記録された提供元を保持し、ダイジェストを捏造しないでください。インストール後にバージョンを再確認してください。それ以外の場合は、ファイルを変更せずに停止してください。

クイックスタート

コードを書いたのはあなたなので、レビュー担当者には知り得ない唯一の情報、なぜそうしたのかをあなたは把握しています。 実行のたびに情報を添付してください。まずセッションコンテキストを書き、その後にレビューを行います。 新しい提出を行う前に、レビューターンのコンテキストを読み、recent_workを更新してください。

qodo --version                                  # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-review --skill-version 1.10.10 --distribution skills-sh
review_base=$(git merge-base HEAD origin/main) || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # use the intended target branch
qodo review --base "$review_base" --context-file - <<'EOF' # branch changes, WITH context
{ "summary": "<what this change does and why>",
  "decisions": ["<a choice you made and its rationale>"],
  "recent_work": ["<what changed since the previous review; fixes only or added behavior>"] }
EOF
qodo review --base "$review_base" --context-file ctx.json # context from a file
qodo review --base "$review_base" --ticket <TICKET_URL> ... # ticket URL (repeatable)
qodo review --base "$review_base" --json ...              # machine-readable findings
qodo review --base "$review_base" src/ test/ ...          # limit to paths (git pathspecs)
develop_review_base=$(git merge-base HEAD origin/develop) || { printf '%s\n' 'Cannot resolve merge base for origin/develop; fetch missing history or choose the correct target.' >&2; exit 1; } # another target branch
qodo review --base "$develop_review_base" --json --context-file ctx.json # another target branch
qodo review --base "$review_base" --fast --async --json --context-file ctx.json # checkpoint
qodo review --base "$review_base" --json --context-file ctx.json      # final: auto
qodo review --base "$review_base" --deep --json --context-file ctx.json # justified deep review
qodo review --base "$review_base" # no context only when there is truly nothing to say
qodo review status <operation-id>            # collect an --async result (exit 2 = still running)
qodo review --help                           # exact flags (renders offline)

リポジトリのルートに.qodo/session-context.json（同じJSON形式）を置き、常に最新の状態にしておくこともできます。このファイルは実行のたびに自動で添付されるため、コンテキストを指定しないqodo reviewでも、あなたの情報が引き継がれます。--context-fileを明示的に指定すると、こちらが優先されます。ファイル自体がレビュー対象の差分に含まれることはありません。コミットしないでください（.qodo/を.gitignoreまたは.git/info/excludeに追加してください）。 解析するものには--jsonを追加してください。接続先で実行する場合は、数分のタイムアウトを設定するか、プロセスをバックグラウンドで実行してください。非同期の送信とステータスの取得は、別々の短い呼び出しです。 正確なフラグはqodo review --helpで確認してください（オフライン）。ここにある例はあくまで参考です。

選択したレビューの実行方法

コーディングのチェックポイントでは --async を使用します。レビューを送信したら、有用な作業を続け、その後 review status で結果を取得します。 最終レビューでも非同期実行は有効ですが、引き渡し前に結果を取得して評価してください。実行中の進捗が必要な場合は、接続中の進捗を読み、ホストネイティブのバックグラウンドプロセスで --json --progress を使用します。--progress と --async は決して併用しないでください。 レビューには数分かかることがあります。クライアントの終了でキャンセルされないよう、接続中のプロセスを維持するか、非同期実行を使用してください。 インストール済みの CLI で非同期実行が利用できない場合は、選択した深度を維持し、接続中のフォールバックを使用してください。

接続中の進捗について、標準となる実行ルールは次のとおりです。

• コンテキストはファイル経由で渡してください。バックグラウンド実行には、stdin のヒアドキュメントは適していません。
• 実行ごとに一意の一時ディレクトリを使用してください。stdout の単一の結果 JSON と stderr の NDJSON 形式の進捗を分離します。ホストのノンブロッキングプロセスツールで、増加する進捗ファイルをポーリングしてください。エージェントが完了まで待たされる、フォアグラウンドの tail は実行しないでください。
• 生の JSON やモデル出力ではなく、短いステータスメッセージを中継してください。イベントは kind に応じて変換します。 cli.status は読みやすいメッセージを示します。tool.activity はツール名と結果を示します。 task.delta と未知の種類は、ときどき送る汎用的なハートビートとして扱い、イベントごとにメッセージを送らないでください。
• qar.client.reconnecting では、試行回数／遅延と、存在する場合は構造化されたクローズ／エラーコードを中継してください。 qar.client.reconnected はトランスポートが開いたことを意味し、resubscribeAttempts は再接続された実行中タスクの数です。 qar.client.reconnect_failed は再試行の枯渇を示すもので、最終的なエラーの説明ではありません。
• task.done では payload.status を確認してください。失敗、キャンセル、または error の場合は、進捗の中継を停止しますが、プロセスの終了は引き続き待ってください。終了コードがゼロ以外の場合も含め、必ず結果エンベロープを読み取ってください。closed_preview など、対応に役立つメッセージやヒントは、エンベロープ内にしかない場合があります。進捗はレビュー結果ではありません。
• プロセスの終了ステータスを取得し、子プロセスを回収してから、解析前にその PID の監視を解除してください。中断された場合は、実行中の子プロセスを終了して回収してください。終了、失敗、中断時にクリーンアップするのは、その実行専用のディレクトリだけです。共有された .qodo/review.* パスは決して再利用したり削除したりしないでください。
• バックグラウンド進捗が利用できない場合は、選択した深度とコンテキストを維持し、数分のタイムアウトを設定してフォアグラウンドで実行してください。進捗がないことは、レビューを失敗させたり深度を下げたりする理由にはなりません。

qodo: command not found と表示されますか？ POSIX では "${QODO_HOME:-$HOME/.qodo}/bin/qodo" を再試行してください。Windows ではリンク先のガイドに従ってください。解決した呼び出し方法を維持し、使用できないランチャーは報告してください。 インストールされていない場合は、Qodo または管理者が提供する、チェックサムが固定されたインストーラーを入手してください。ダイジェストを捏造したり、スクリプトをシェルにパイプして実行したりしないでください。

サンドボックス認証の診断。 認証情報がないように見える原因が、キーチェーンにアクセスできないことにある場合があります。その可能性がある場合は、ログインを勧める前に、ホストの承認フローを通じて、読み取り専用の qodo read whoami を一度だけ正確に再試行するよう求めてください。拒否された場合は停止してください。その承認は他のコマンドには適用されません。同じ実行ファイル／ワークスペース／デプロイ環境および実行コンテキストでは、成功した確認結果を再利用してください。必要なホスト承認はそれぞれ取得してください。ネットワーク、TLS、サービス、明示的な認可の失敗は、それぞれ固有の原因として診断してください。ログインを勧めたり、サンドボックスを自動的に迂回したりしないでください。

--async を使って送信・結果を取得する

qodo review --help でサポート状況を確認してください。以下の例では、コーディングのチェックポイントを送信します。最終レビューでは --fast を省略し、上記の選択ポリシーに該当する場合にのみ --deep を追加してください。すべてのモードで同じコンテキストを添付してください。シェルのスニペットは CLI プロトコルを示しています。待機にはホスト独自のノンブロッキング機構を使用してください。

--async を使うと、接続がクリティカルパスから外れます。レビューを HTTP 経由で送信し、operation id を出力して、すぐに終了コード 0 で終了します。プロセスが稼働しているかどうかにかかわらず、実行はサーバー側で継続します。結果は後で qodo review status <operation-id> を使って取得できます。

command -v jq >/dev/null 2>&1 || { printf '%s\n' 'This async recipe requires jq; install it or use the live qodo review flow.' >&2; exit 1; }
QODO_REVIEW_CONTEXT="${QODO_REVIEW_CONTEXT:-.qodo/session-context.json}"
[ -f "$QODO_REVIEW_CONTEXT" ] || { printf '%s\n' "Write the required review context to $QODO_REVIEW_CONTEXT (or set QODO_REVIEW_CONTEXT to its path)." >&2; exit 1; }
QODO_REVIEW_BASE="$(git merge-base HEAD origin/main)" || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # substitute the intended target
if ! submission="$(qodo review --base "$QODO_REVIEW_BASE" --context-file "$QODO_REVIEW_CONTEXT" --async --json --fast)"; then printf '%s\n' "$submission" >&2; exit 1; fi
if ! id="$(printf '%s\n' "$submission" | jq -er '.operation_id | select(type == "string" and length > 0)')"; then printf '%s\n' "$submission" >&2; exit 1; fi
qodo review status "$id" --json                                # collect it

既存の操作が完了するまで状態をポーリングし、その間に有用な作業を進めてください。送信時の終了コード 0 は、受理されたことを意味し、レビュー済みであることを意味しません。結果取得時の終了コードは以下のとおりです。返された再試行までの時間があれば、それに従ってください。

終了コード	意味	対応
0	完了しました。検出結果が表示されます — 稼働中の実行と同一の出力です（--json では {findings, meta}）。	通常どおり検出結果に対応してください。
2	実行中、またはポーリングが制限されています。	retry_after が返された場合はそれに従い、同じ ID を再度ポーリングしてください。
1	失敗、キャンセル、期限切れ、または該当する操作がありません。error エンベロープを確認してください。	以下の制限付きリカバリーに従ってください。クリーンな結果だと決めつけないでください。

# This collection attempt returns failures to the host for classification under Recover a review.
# On nonzero exit, preserve the operation ID and emitted error; apply bounded recovery there.
QODO_REVIEW_TMP="$(mktemp -d "${TMPDIR:-/tmp}/qodo-review.XXXXXX")"
cleanup_qodo_review() { [ -n "${QODO_REVIEW_TMP:-}" ] && [ -d "$QODO_REVIEW_TMP" ] && rm -r -- "$QODO_REVIEW_TMP"; }
trap cleanup_qodo_review EXIT; trap 'exit 130' INT; trap 'exit 143' TERM
while :; do
  status=0; qodo review status "$id" --json > "$QODO_REVIEW_TMP/result.json" || status=$?
  case "$status" in
    0) cat "$QODO_REVIEW_TMP/result.json" || exit 1; break ;;
    2) delay=$(jq -r 'if (.retry_after | type) == "number" and .retry_after > 0 then .retry_after else 15 end' "$QODO_REVIEW_TMP/result.json") || exit 1
       sleep "$delay" ;;
    *) cat "$QODO_REVIEW_TMP/result.json" >&2; exit "$status" ;;
  esac
done

利用を決める前に、以下の制約を把握してください。

• ストリーミングで進捗を確認できません。 この経路では進捗イベントはありません。実行はプロセスに接続されないため、到着しないストリームを出力するのではなく、--async と --progress を併用するとエラーになります。「実行中」より詳しい中間状態はありません。ユーザーが進行状況を見ていて、実行中であることを確認したい場合は、代わりに接続時の進捗表示の手順を使用してください。
• 人間が介在することはできません。 このインターフェイスで実行されるのは決定論的なエージェントのみです。入力を求めるレビューは待機せずに失敗します。（qodo review status はその旨を表示し、--async を付けずに再実行するよう案内します。）
• レビュー完了後、結果は 1 時間保持され、その後破棄されます。 この時間内に取得してください。期限を過ぎると、qodo review status は「期限切れ」「存在したことがない」「別のユーザーのもの」を区別できません。ランタイムは意図的にこの 3 つに同じ応答を返すため、いずれも同様に報告されます。新しい実行が必要か判断する前に、レビュー結果を確認できないことを報告してください。
• 新しい送信は無料とも、重複排除されるとも限りません。 受理済みの実行結果を取得するには review status を使用してください。受理されたか不明な場合は、CLI が返すリカバリーコマンドに従ってください（対応バージョンでは --async --retry-submission <id>）。ポーリングの代わりに、新たに qodo review を実行しないでください。リカバリーの際は、変化する作業ツリーを再度収集するのではなく、保持されたリクエストをそのまま使用してください。
• operation id を保持してください。 これは受理された実行を識別する ID です。送信リカバリー ID とは目的が異なります。結果を取得するか、処理結果を照合するまでは、どちらの ID も破棄しないでください。

operation id は trace id ではありません。 qodo は失敗時に trace <id> の行を出力します。これはサポートチームが実行を診断するための OpenTelemetry ID であり、何かを取得する用途には使えません。--async が返す operation_id は、処理を再開するための ID です。一方が求められている場面で、もう一方を渡さないでください。

事前確認

1. 認証とカタログ。 この実行コンテキストで有効な確認結果がまだ使える場合を除き、qodo read whoami を実行します。該当する場合はサンドボックス診断の後、明示的に認証情報が不足している場合のみログインします。組織指定のログインコマンド／エンドポイントをそのまま使い、顧客環境を推測で Cloud に切り替えてはいけません。No tool catalog cached は認証情報が不足している証拠ではありません。qodo tools --refresh で一度更新してから、確認を再試行してください。その他のエラーはそのまま保持し、このワークフローを停止します。認証が成功した後、管理対象のコマンドが不明な場合は、カタログを一度更新してスキーマを再確認できます。それでも見つからない場合、または tool_unavailable の場合は、不足している機能を報告してください。ログインや更新を繰り返してはいけません。不明な組み込みの qodo review には、ログインやカタログの更新ではなく、ランタイムの復旧が必要です。
2. ベースを解決します。 対象となるターゲット（変更が別のブランチを対象としていない限り origin/main）を選択します。現在のリモート履歴を確認する前に、そのターゲットをフェッチしてください。利用できない場合、または意図的にオフライン／固定の状態である場合は、レビューがローカルでフェッチ済みの履歴を使用していることを明示し、最新の履歴であると主張してはいけません。git merge-base HEAD <target-ref> を計算し、その SHA をすべての送信で --base として渡してください。チェックポイントや接続済みの実行も含みます。これにより、デフォルトでターゲットの先端と比較する古い CLI も適切に処理できます。明示的な --base は厳密に適用されます。ターゲットブランチ自体を渡すと、ターゲットだけに存在する新しい変更が誤って含まれることがあります。ユーザーが指定した厳密な比較方法に従ってください。共通の祖先がない場合は、不足している履歴をフェッチするか、妨げとなっている事項を報告してください。ターゲットの先端に黙って切り替えてはいけません。ベースはプッシュ済みである必要があります。レビュー権限にプッシュは含まれません。ローカルの編集内容と未追跡ファイルは、コミットやプッシュをせずに含めます。
3. コンテキストを記述します。 実行前に、セッションの経緯をコンテキスト JSON として記録します。変更内容と理由、および途中で行った判断をまとめた 2～3 文の要約です。標準入力のヒアドキュメント、ファイル、または .qodo/session-context.json を使用します。必ず記述できる内容があります。コードを書いたのはあなたです。本当に記述することが何もない場合に限り、コンテキストなしで実行してください。

レビュー対象

qodo review は、すべてクライアント側で次の情報を収集します。

• ベースとの差分である 追跡対象の差分 と、新規／未追跡ファイル（シークレット、バイナリ、サイズ超過のファイル、Git で無視されるファイルは除外され、その旨が報告されます。黙って除外されることはありません）。
• ブランチ名、HEAD コミット、およびコミットメッセージから合成された説明。
• 追加したチケット参照とセッションコンテキスト（以下を参照）。

--json は各指摘を findings に一度だけ返し、finding_state には参照 ID を分類して格納します。.introduced と .still_open を評価し、検出された修正は .resolved に、保存済みの却下は .dismissed に報告します。以前の分類には完全なオブジェクトが含まれます。 既定のフィールドは、id、title、description、category、action_level、attribution_status、git_sha、location、evidence.citations です。コードの位置と根拠を確認し、元の指摘 ID を保持してください。 --extended は保存済みの補足詳細を追加しますが、レビューの深さも実行内容も変わりません。 ローカルの review_agent_comment は、どちらの表示でも保存済みのレビューフィードバックです。再利用時には新たな実行なしで引き継がれます。指摘とカバレッジとあわせて確認してください。 承認されたステータス書き込みでは、meta.local_review_ids[id] に従って ID をまとめてください。参照できない項目も報告してください。 修正指示とレビュアーの内部情報は含まれません。フィールドの詳細については、フィールドガイドを参照してください。 finding_state.complete または meta.coverage.complete が false の場合は、カバレッジが不完全であることを報告してください。 meta.analysis.mode は full、incremental、または reused です。reused は、レビュー済みのスナップショットと互換性のあるコンテキストが同じであることを意味します。以前の未解決の指摘は未解決のままです。CLI は送信されたパッチを非公開で保存します。 適格な結果を収集した後、review status を介した場合も含め、チェックポイントを更新します。失敗した完了や古い完了によって、新しいチェックポイントが置き換えられることはありません。 修正ループ中は、同じベース、パスのスコープ、要求する深度モード、コンテキストを維持してください。コンテキストの変更、期限切れまたは検証不能なチェックポイント、サポートされていない差分がある場合は、完全なレビューにフォールバックします。チェックポイントを捏造しないでください。 意図的に新規の評価を行う場合は --full を使用してください（サポート状況は --help で確認してください）。このオプションが制御するのはスコープであり、深度ではありません。修正のたびに使用する必要はありません。要求する深度モードを変更すると、互換性のあるチェックポイントカバレッジは無効になります。Auto は有効なティアを固定で保証しません。返された分析／カバレッジを基準にしてください。 古いエンジンではこれらのフィールドが省略されます。その場合は、再利用されたと主張せず、返された指摘とカバレッジを使用してください。 実際の結果については meta.run.passes を優先してください。従来の meta.reviewers は設定済みの評価軸を示します。失敗またはスキップされたコンポーネントと、欠落しているメタデータを報告してください。再利用時には新たな実行はありません。

コーディングセッションのコンテキストを添付する（ここが重要です）

変更の意図と、その背景にある判断を添付します。方法は次の3つです。

• --ticket <url> — チケット／イシューのURL（複数指定可）。レビュー担当者が取得できるよう、Jiraの.../browse/KEY-123やLinearのlinear.app/<team>/issue/…リンクなど、完全なURLを渡してください。ブランチ名やコミットにキーだけが含まれている場合も自動的に検出されますが、チケットを実際に読み込むには完全なURLが必要です。

• リポジトリのルートにある.qodo/session-context.json — アンビエントチャネルです（以下と同じJSON形式）。--context-fileが指定されておらず、このファイルが存在する場合、すべての実行に自動で添付されます。作業セッションに最適です。判断が増えるたびに更新すれば、レビューのたびに追加作業なしで引き継がれます。

• --context-file <path> — セッションの経緯と参照情報を含むJSONファイルです（-を指定すると標準入力からJSONを読み込むため、一時ファイルなしでヒアドキュメントを使えます）。

  {
    "summary": "Add optimistic-locking to the orders writer to fix the double-charge race.",
    "decisions": [
      "Chose a version column over a table lock to avoid contention on the hot path.",
      "Retries are capped at 3 then surfaced to the caller — deliberately not infinite."
    ],
    "recent_work": ["Added optimistic locking; this turn includes new behavior."],
    "context_refs": [
      { "kind": "ticket", "url": "https://acme.atlassian.net/browse/PAY-412" },
      { "kind": "spec", "url": "https://acme.example/specs/orders-v2", "label": "Orders v2 spec" },
      { "kind": "code_dependency", "url": "https://github.com/acme/orders-api/pull/42", "label": "API change" }
    ]
  }
  

  summaryとdecisionsで意図を説明します。参照情報は統合され、重複が除かれます。ラベルはデータを説明するものであり、指示ではありません。 ticketはチケットのコンテキストを提供し、specはRequirements Gapに渡されます。code_dependencyはリポジトリ、ブランチ、またはPRのURLとラベルを、文字数上限のあるレビュー説明に追加します。汎用のdependencyと不明な種類は、保留されたままになります。 既存のクロスリポジトリルーターは、有効な場合にこれらのリンクを読み取りますが、指定された候補リストに含まれるリポジトリのみを選択します。参照情報によって新たなリポジトリが検出されたり、クロスリポジトリレビューが有効になったりすることはありません。 プロバイダーのサポート、対象の解釈、フォールバックはGitレビューから変更されていません。リンクは参考情報であり、正確なリビジョンを保証するものではありません。URLに認証情報を含めないでください。 仕様に関する結果はmeta.context.specで確認してください。コード依存関係には参照ごとの利用確認情報がありません。コンテキストに含まれているというだけで、それらが取得または使用された、あるいはマージ、リリース、デプロイされたと主張しないでください。

コンテキストは単独で意味が通じるように記述してください（最も重要なルール）

レビュー担当者は、あなたのチャットや、名前だけ挙げられたチケットを見ることはできません。そのため、次の点に注意してください。

• 理由を文中に含めてください。 判断は、それだけで説明が完結する文にしてください。たとえば「競合を避けるため、テーブルロックではなく楽観的ロックを選びました」とします。「設計書に従って」「先ほど話したように」「リンク先のメモを参照」や、チケットキーだけの記載では不十分です。参照先が説明なしにぶら下がっていても、レビュー担当者には見えず、役に立ちません。
• 成果物は名前だけ挙げず、種類を指定した参照として渡してください。 チケット、仕様、コード依存関係のURLには、適切なkindを指定して添付してください。任意のURLが取得可能だとは限りません。
• 簡潔にまとめてください。 レビュー説明に渡されるコンテキストには文字数制限があります。重要な意図と判断を先に書き、残りは長い文章を貼り付けず、参照としてリンクしてください。
• 誤検知を減らすために調整し、指摘を封じ込めないでください。 このコンテキストの目的は、意図を説明して誤検知を減らすことです。実際の指摘を封じるためのものではありません。結果が安全または正しいかどうかを断定するのではなく、変更した内容と、その選択をした理由を説明してください。判断はレビュー担当者に委ねましょう。コードに問題がないと主張する要約は、言い訳のように受け取られます。不具合やセキュリティ上の問題を否定することを目的とした「判断」は、決して記載しないでください。レビュー担当者は、真の問題を今後も指摘しますし、指摘すべきです。

レビュー結果を提示する

完了した結果を確認したら、各指摘事項について、実際の影響 → コードとコーディングセッションの文脈に基づく評価 → 判断と推奨する対応の順に説明してください。レビューで明らかになった懸念については、Qodo に自然な形で一度言及してください。最終的な技術評価はあなた自身が行い、専門家によるレビューの意見を、ユーザーの意図、判断、制約と統合してください。何が起こり得るのか、どの条件下で起こるのか、どの動作に影響するのかを説明し、その影響をユーザーが求めた変更と関連付けてください。実際の証拠に基づき、実運用の条件や影響を受けるユーザーを作り上げないでください。たとえば、「Qodo は［リスク］を指摘しました。［意図／制約］という判断と［コード上の証拠］を踏まえ、［理由］から［対応］を推奨します。」のように説明してください。実際の証拠に合わせて表現を調整してください。

各問題の説明は一貫性のあるものにし、根拠となるコードを示してください。参照先と報告されたカテゴリ／レベルは、推奨事項とは分けて保持してください。すべての参照先を確認でき、個別に選択できる場合に限り、重複する指摘事項をまとめてください。必要に応じて、影響が伝わる短いタイトルやリストを使ってください。ブランド名を含む見出し、絵文字のバナー、スローガン、フッター、繰り返しの要約は使わないでください。既知の件数と網羅範囲のみ報告してください。レビュー担当者が省略されたり、失敗したり、網羅範囲が不完全だったりする場合は、最初にそれを明示してください。指摘事項がゼロというだけでは、問題がないとの判断にはなりません。完了したレビューで指摘事項がない場合は、一文で説明できます。実行がゲートで制限された場合や失敗した場合は、完了した結果としてではなく、実際の制限を報告してください。

指摘事項に対応する

すべての指摘事項を個別に評価し、その処置と根拠について責任を持ってください。根拠のある問題は修正します（Qodo の提案とは異なる修正でもかまいません）。根拠のない懸念は、コード上の証拠を示して却下します。不確かな点は、必要な確認事項を明示して調査します。セッションでの決定を根拠に却下できるのは、その前提がコードによって強制されている場合に限ります。協力的かつ事実に即した口調を保ち、Qodo の能力について常に但し書きを付けたり、誤った指摘を広範な評価に結び付けたりしないでください。 技術的な推奨は、修正の許可を意味しません。以下に示すユーザーの既存のスコープを適用してください。

報告のみ。 変更を加えずにレビューするよう明示的に依頼された場合は、評価を返して終了します。編集の許可を求めないでください。

編集権限が不明確な場合。 修正対象のスコープが曖昧な場合は、上記の評価を各指摘事項について示し、[category/level] と推奨事項を維持したうえで、どの指摘事項を適用するか一度のプロンプトで尋ねます。ホストが提供する機能を使用してください。たとえば、複数選択機能がある場合は Claude Code の AskUserQuestion を使用し、ない場合は番号付きリストを提示して「適用する番号を返信してください」と伝えます。どちらの場合もプロンプトは一度だけとし、指摘事項ごとに尋ねないでください。 事前選択はありません。 推奨する項目を示しますが、ユーザー自身が選択する必要があります。このプロンプトの回答が、指摘事項を編集する前に残された最後の確認です。そのため、何も選択せずに Enter を押しても、何も適用されないようにしてください。ユーザーが選んだ項目だけを適用し、通常どおり、周囲のスタイルに合わせて編集します。それ以外は、理由を添えて未適用として報告します。ユーザーが選択する前にコードを編集してはいけません。

修正が許可されている場合。 autofix、指摘事項を修正する明示的な依頼、または必要な修正を対象とする既存の実装権限があれば、そのスコープ内で修正できます。評価を示し、根拠のある修正を再確認せずに適用してください。レビューのみの依頼では編集権限は付与されません。意図されたスコープが曖昧な場合は、一度だけ確認してください。より限定的なユーザーの制約を優先してください。修正権限があっても、却下の保存、プッシュ、無関係な変更は許可されません。適用した修正と適用しなかった修正を報告してください。

ユーザーがローカルの指摘事項を却下することを明示的に許可した場合は、Record local triage に従って、その判断を保存してください。会話上の「スキップ」だけでは却下の記録にはなりません。また、保存された却下として報告してはいけません。 MCP では、完了したレビューの指摘事項 ID と local_review_id、許可された理由と説明、バッチ用の安定した idempotency_key を使用して、最新の pr-review-dismiss スキーマを利用してください。保存された各結果を読み返して確認してください。リファレンスにある CLI コマンドが適用されるのは CLI 経由の場合のみです。

許可された修正をまとめて適用した後は、変更内容を検証し、上記のライフサイクルポリシーに従って再レビューしてください。結果を問題なしと判断する前に、未対応の指摘事項と対象範囲を評価してください。成果のないループは中止してください。 ユーザーのワークフローに従ってコミット／プッシュしてください。ユーザーから指示がない限り、プッシュする前に確認してください。

レビューの復旧

受け付けられた非同期実行では、操作 ID を使って結果を取得します。ステータス取得時にトランスポートエラーが発生した場合は、返された遅延時間（または 15 秒）後に 1 回だけ再試行します。 取得に失敗した場合は、ID を保持して不足を報告します。ポーリングだけを目的に再送信してはいけません。最終的な失敗が発生した場合は、復旧可能な原因を修正し、同じモードとコンテキストで 1 回だけ再試行します。権限付与、認証、アクセス許可、レート制限、または再度の失敗が原因の場合は停止し、期限切れの結果とレビュー範囲の不足を報告します。

repo_not_connected、MT-REPO-NO-CREDENTIAL、または “could not obtain repository credentials” が発生した場合は、URL 内の認証情報を露出させずに origin を確認します。SSH エイリアスは、接続済みホストと異なる場合があります。 既知の正確なリポジトリ full_name を使用します（セルフホストの名前にはホストが含まれる場合があります）。Codebase Wisdom の候補は、接続できている証明にはなりません。 qodo review --help で --repo がサポートされていることを確認します。自動再試行が禁止されている場合は、停止して、修正したコマンドについてユーザーの明示的な承認を得ます。 元の送信を、他のすべてのフラグを維持したまま --repo <full_name> を付けて 1 回再試行します。該当する場合は、新しい非同期操作 ID を取得します。 対象を特定できない場合、または再試行に失敗した場合は、停止して報告します。切断していると断定せず、管理者に Git 統合の確認を依頼します。

接続済み CLI の実行中は、レビューが完了するまでプロセスを稼働させます。クライアントが強制終了されると、短い猶予期間の後にサーバーがキャンセルする場合があります。ホストで稼働を維持できない場合は、タイムアウトを繰り返さずに非同期実行を使用します。接続状態を維持したまま接続済み実行をバックグラウンドで動かすには、接続済みの進行状況を使用します。

並行するレビューは、それぞれ独立して完了できます。 同じ所有者／リポジトリ／ブランチでは、最新のチェックポイント実行のみが指摘事項の更新を公開できます。古い実行の結果は superseded と報告される場合があります。

クライアントの強制終了、接続切断後のサーバーによるキャンセル、ストリーム切断後の task.done の欠落、バックエンドからの review failed: <detail> 応答を区別します。復旧方法を選ぶ前に、実際の失敗内容と保持された結果に関するヒントを確認します。接続失敗からサイズや複雑さの上限を推測してはいけません。

最初の 3 つの場合は、再送信する前に、CLI の復旧ヒントを使って保持されている結果を取得します。実行がキャンセルされた、または復旧不能だと確認できた場合は、中断のない実行と同じ選択済みの深度／コンテキストを使って、最大 1 回まで再試行します。実行が保留中であることは、再起動する理由にはなりません。さらに失敗した場合は、ループしたり、コンテキストを削除したり、結果を得るために深度を下げたりせず、レビューが未完了であることを報告します。

実行がゲートされている場合：クローズドプレビュー

qodo review は現在クローズドプレビューです。サーバーは、参加登録されていない組織からの実行を拒否します。ゲートされた実行は、安定した機械可読形式のエラーでゼロ以外の終了コードを返します。--json を指定すると {"error": {"code": "closed_preview", "message": ..., "hint": ...}} が出力され、--json を指定しない場合は、同じメッセージとヒントがテキストで出力されます。

closed_preview が発生した場合：

1. message と hint を変更せずにユーザーに提示します（言い換えたり、省略したりしてはいけません。--json のペイロードにはそのまま含まれますが、CLI のテキスト出力では端末制御文字が除去されます）。その後、
2. 停止します。 このゲートは権限付与に関するものであり、一時的な障害ではありません。ユーザーの組織が参加登録されるまでは、再試行、待機、監視、ループを行っても成功しません。ユーザーから参加登録が完了したと伝えられない限り、qodo review を再実行してはいけません（参加登録後、アクセスは約 10 分以内に有効になり、再ログインは不要です）。

ゲートの対象はレビュー自体のみです。認証（qodo read whoami）とその他の qodo コマンドには影響しません。

設定

コーディングのチェックポイントには --fast --async --json を使用し、通常の最終レビューには auto を使用します。--deep は記載された例外の場合に限り使用します。接続済みの進行状況には --json --progress を使用し、解決済みのマージベース SHA を --base に指定します。装飾のないバージョン確認後、最初の Qodo 呼び出しで正確なスキル／バージョン／配布元の情報を記録し、セッションコンテキストをレビュー対象の diff に含めないでください。

エラー処理

終了コードが 0 以外の場合は、構造化された結果を確認してください。範囲を限定して復旧し、コンテキストと権限を維持してください。

ガードレール

• ローカルの範囲。 PR の作成や更新、または完了した作業の引き継ぎの前に、コーディングの各マイルストーンとローカル作業を確認してください。 PR にすでに投稿された指摘には qodo-review-resolver を使用し、内容が変わっていないレビューを重複して行わないでください。
• フォージへの書き込みは禁止。 qodo review はローカルの差分を読み取り、指摘を返します。プッシュ、コメント、PR の作成は行いません。指摘への対応とは、コードを編集することであり、どこかに投稿することではありません。
• ベースはプッシュ済みである必要があります。 ローカル作業はプッシュされていなくてもかまいません。新規ファイルや未追跡ファイルはデフォルトでレビューされます。シークレット、バイナリ、サイズ超過のファイル、Git で無視されるファイルは除外され、報告されます。
• 認証情報やベースを推測しないでください。 まず認証を解決し、ユーザーが厳密なベースラインを明示的に求めていない限り、意図した対象のマージベース SHA を --base に渡してください。
• すべての実行結果を収集してください。 接続状態を維持したままバックグラウンドで実行するか、非同期で実行し、復旧用のハンドルを保持してください。置き換えられた結果では、差分レビューのベースラインは更新されず、現在のコードの認定にもなりません。
• 時間に間に合わせるためにコンテキストを削らないでください。 --context-file を外しても実行は速くならず、レビューの質が下がるだけです。時間をかけてください。タイムアウトの圧力ではなく、ライフサイクルに応じて深度を選んでください。
• MT-TOOL-LOOP または MT-RATE-LIMITED エラーが発生した場合は、停止するか待機時間を置き、再試行ではなく別の方法に切り替えてください。
• closed_preview エラーは、その組織がプレビューの対象になっていないことを意味します。メッセージとヒントをユーザーに伝えて停止し、再試行やループは決して行わないでください（上記の「実行が制限されている場合」を参照）。

承認された修正を行った後は、変更内容、検証方法、残っている作業とその理由を報告してください。