open-code-review

Open Code Review

open-code-review（ocr）を呼び出すためのスキルです。これはオープンソースの AI コードレビュー CLI で、Git の diff を読み取り、構造化された行レベルのレビューコメントを生成します。

ワークフロー

ステップ 1: ビジネスコンテキストを収集する

レビュー対象（コミット、ブランチ、または変更内容）を分析し、簡潔なビジネスコンテキストを抽出します。このコンテキストを --background で渡すことで、レビューの品質が向上します。

ステップ 2: コードレビューを実行する

ocr がインストールされているかどうかを事前に確認しないでください — command -v ocr や ocr --version のようなプローブは省略します。CLI が利用可能であると想定してレビューを直接実行してください。これにより、通常のパスでツール呼び出しを 1 回節約できます。command not found でレビューが失敗した場合にのみ、トラブルシューティングに従ってインストールしてください。

適切なフラグを付けて OCR コマンドを実行します。利用可能な場合は、常に --background でビジネスコンテキストを渡してください:

ocr review --audience agent --background "business context here" [user-args]

引数の扱い:

• バックグラウンドコンテキスト（推奨）: --background "context" または -b "context" を使用して、レビュー品質を高めるためのビジネスコンテキストを提供します
• デフォルト（ユーザー引数なし）: ステージ済み、未ステージ、および未追跡の変更をレビューします（ワークスペースモード）
• 特定のコミット: --commit または -c を使用して、単一のコミットをその親と比較してレビューします
• ブランチ比較: --from <ref> と --to <ref> を使用して、2 つの ref 間の diff をレビューします
• タイムアウト: レビューグループごとの実効タイムアウト = --timeout × レビューラウンド数。デフォルトの --timeout 15 とデフォルトのエフォート medium（2 ラウンド）では 30 分、low/high では 15/45 分になります。
• 並行性: デフォルトの並行性は 8 ファイルワーカーです。レート制限に達した場合は --concurrency <n> で減らしてください
• プレビューモード: --preview または -p を使用して、LLM を実行せずにどのファイルがレビューされるかをプレビューします
• 出力ファイル: --output <path> を使用して、完全な結果を stdout ではなくファイルに書き込みます。unknown flag: --output でコマンドが失敗した場合、プレーンな stdout でレビューを続行しないでください。ユーザーにアップグレード（npm i -g @alibaba-group/open-code-review@latest）を行うかどうかを尋ね、先に進む前に回答を待ってください。ユーザーが確認し、アップグレードが成功したら、--output を付けて再実行してください。
• インストール: ocr コマンドが見つからない場合は、npm i -g @alibaba-group/open-code-review を実行してインストールします

一般的な呼び出しパターン:

ユーザーの発言	実行するコマンド
「自分の変更をレビューして」/「作業コピーをレビューして」	ocr review --audience agent -b "context"
「この PR をレビューして」/「フィーチャーブランチをレビューして」	ocr review --audience agent -b "context" --from main --to <branch>
「コミット abc123 をレビューして」	ocr review --audience agent -b "context" --commit abc123
「何がレビューされるの？」（ドライラン）	ocr review --preview

出力モード:

• 進行状況 UI を抑制し、最終的な要約のみを出力するために、常に --audience agent を使用してください
• 出力の切り捨てを防ぐ: 大規模なレビューや制限されたツール環境では、--output /tmp/ocr_out.txt を渡し、stdout を tail や head にパイプするのではなく、ファイル読み取りツールでファイル全体を確認してください。パイプすると以前のレビューコメントが失われます。

失敗時: ocr review が非ゼロで終了した場合（例: LLM 接続エラー）、盲目的に再試行しないでください — 再実行する前に、以下のおトラブルシューティングセクションで該当する修正を確認してください。

ステップ 3: レポート

OCR の出力には、各コメントに構造化された severity（critical / high / medium / low）と category（bug / security / performance / maintainability / test / style / documentation / other）が含まれます。結果を severity ごとにグループ化して提示し、誤検知や些末な指摘である可能性が高い low severity の項目は破棄してください。

ステップ 4: 修正

修正を適用する前に、ユーザーが自動修正を要求したかどうかを確認します:

• ユーザーが明示的に「レビューと修正」または同様のことを要求した場合は、自動修正を進めます
• ユーザーが修正の意図なく「レビュー」のみを要求した場合は、変更を適用する前に許可を求めます

問題と提案を修正する場合:

• critical、high、medium の重大度の項目に焦点を当てます
• 安全で明確に定義されている場合は、修正をコードに直接適用します
• 手動での介入が必要な複雑な修正については、何を行う必要があるかを明確に説明します
• コミットする前に、必ずユーザーと修正を確認します

出力形式

OCR の出力における各コメントには以下が含まれます:

• path: ファイルパス
• content: レビューコメントのテキスト
• start_line / end_line: 行範囲（両方とも 0 の場合は位置特定に失敗したことを意味します）
• category: 問題のカテゴリ（bug、security、performance、maintainability、test、style、documentation、other）
• severity: 問題の重大度（critical、high、medium、low）
• suggestion_code: オプションの修正提案
• existing_code: オプションの元のコードスニペット
• thinking: オプションの LLM 推論プロセス

このテンプレートを使用して、重大度別にグループ化した結果を提示します:

## Code Review Results

**Files reviewed**: N
**Issues found**: X critical, Y high, Z medium

### Critical

- **`path/to/file.java:42`** [bug] — Brief description
  > Recommendation: How to fix

### High

- **`path/to/file.java:26`** [bug] — Brief description
  > Recommendation: How to fix

### Medium

- **`path/to/file.ts:88`** [performance] — Brief description
  > Recommendation: How to fix (if applicable)

フィルタリング後に critical、high、medium の重大度の問題が残っていない場合は、次のように記載します: 「レビュー完了 — N 個のファイルに critical、high、medium の問題は見つかりませんでした。」

位置が特定できなかったコメントの処理:

start_line と end_line が両方とも 0 の場合、コメントはファイル内の正確な位置を特定できませんでした。そのような場合は:

1. コメントの内容を読んで問題を理解します
2. コメントで言及されている対象ファイルを調べます
3. コメントの文脈に基づいて関連するコードセクションを特定します
4. 修正または提案を正しい位置に適用します

カスタムレビュールール

ユーザーがプロジェクト固有のルールを希望する場合、OCR は次の優先順位でそれらを解決します:

1. --rule <path> フラグ（最優先）
2. <repo>/.opencodereview/rule.json
3. ~/.opencodereview/rule.json
4. 組み込みのシステムデフォルト（最低優先）

デフォルトでは、最初に一致したユーザールールが組み込みのシステムルールを置き換えます。一致したシステムルールとユーザールールの両方を含める必要がある場合は、ルールエントリで merge_system_rule: true を設定します。

ルールファイルの形式:

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "All new methods must validate required parameters for null",
      "merge_system_rule": true
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks and missing closing tags"
    }
  ]
}

レビューする前に、どのルールがファイルに適用されるかをプレビューするには:

ocr rules check src/main/java/com/example/Foo.java

高度なレビューオプション

上記の一般的なフラグに加えて、ocr review はいくつかのコントロールグループを公開しています。完全なリストについては ocr review --help を実行してください。

スコープ

• --exclude '<patterns>' — カンマ区切りの gitignore 形式のパターン（例えば --exclude '**/generated/*,**/testdata/*'）、rule.json の除外とマージされます。
• --background-file <path> — Markdown ファイルからレビューコンテキストを読み取ります。--background より優先されます。

出力

• --format text|json|sarif — text（デフォルト）は人間向け、json は機械可読な検出結果向け、sarif は GitHub Code Scanning などのコードスキャン統合向けです。

モデル

• --provider <name> / --model <name> — この実行に限り、設定された provider/model を上書きします（例えば、別のモデルで diff を再確認する場合、ユーザーがモデルを指定します。ocr llm providers に組み込みモデルの一覧が表示されます）。

予算

• --max-tokens <n> — グループごとのプロンプト上限。デフォルトは設定値またはテンプレートのデフォルト（200000）です。
• --max-tokens-budget <n> — 実行の総入力 + 出力トークンを上限設定します。毎回の LLM ラウンドの前にチェックされます: すでに予算を超えたグループは検出結果を送信するための最後の 1 ラウンドが与えられ、それ以上のグループはディスパッチされず、部分的な結果は引き続き公開され、スキップされたファイルは failed(budget) として報告されます。
• --no-filter — すべてのレビューコメントを保持し、LLM のポストフィルタリング呼び出しをスキップします。

注意点

• LLM を最初に設定する必要があります — 到達可能な LLM がない場合、ocr review は明確に失敗します。その場合は、以下のトラブルシューティングセクションを参照してください。
• 作業ディレクトリが重要です — ocr review はカレントディレクトリの Git リポジトリに対して動作します。別の場所から実行するには --repo /path/to/repo を使用してください。
• ワークスペースモードでは未追跡ファイルもレビューされます — 引数なしで ocr review を実行すると、ステージ済み、未ステージ、および未追跡の変更が含まれます。対象を狭めたい場合は選択的にステージしてください。
• 大きな差分はトークン上限に達する可能性があります — MAX_TOKENS はプロンプトの予算を設定します（レビューテンプレートでは 200000、ocr scan では 58888）。会話コンテキストはこのプロンプト予算内に収まるよう圧縮されます。モデルの出力は別途 MAX_COMPLETION_TOKENS（16384）で上限が設けられます。差分だけで MAX_TOKENS の約 80% を超えるファイルは、LLM が呼び出される前にスキップされます。
• プランフェーズは 2 つのしきい値のいずれかで発動します — グループ内の最大の変更ファイルが PLAN_MODE_LINE_THRESHOLD（デフォルト 50）に達した場合、または 変更行数の合計が PLAN_MODE_GROUP_LINE_THRESHOLD（デフォルト 100）に達するファイルを 2 つ以上含む場合、そのグループは本レビューの前に追加のリスク分析フェーズを実行します。これによりレイテンシが増加しますが、品質が向上します。
• --audience human を渡さないでください — 進捗 UI がストリーミングされ、出力が汚染されます。常に --audience agent を使用してください。
• コメントの言語は設定に従います — language 設定はレビューコメントの言語を制御し、デフォルトは English で、任意の言語名（たとえば English や 中文）を受け付けます。
• 出力の切り捨てを避けてください — 大規模なレビュー実行では冗長な出力が生成されます。コマンド出力を tail や head にパイプしないでください。以前のセクションのレビューコメントが失われます。--output <path> を使用して全体を読み取ってください。古い CLI では、上記の 出力ファイル のガイダンスに従ってください。
• 中断されたレビューを再開する — 失敗または中断された範囲/コミットレビューは、同じ --from/--to または --commit ターゲットを指定して ocr review --resume <id> で続行できます（id は失敗時に retry with: --resume <id> として出力されるか、ocr session list で確認できます）。ワークスペースの再開はサポートされていません。

検証

レビューが完了したら、以下を確認して成功を検証します。

1. コマンドがコード 0 で終了した
2. コメントが生成された（または「No comments generated」メッセージが表示された）
3. 警告（ある場合）が stderr に表示された

エラーが発生した場合は、stderr の警告を確認して、どのファイルが失敗したか、その理由の詳細を確認してください。

トラブルシューティング

ocr: command not found

CLI をインストールします。

npm install -g @alibaba-group/open-code-review

unknown flag: --output

CLI が v1.10.0 より古いです。プレーンな stdout でレビューを続行しないでください。アップグレードするかどうかをユーザーに尋ね（npm i -g @alibaba-group/open-code-review@latest）、続行する前に回答を待ってください。ユーザーが確認し、アップグレードが成功したら、--output を付けて再実行してください。

ocr review が LLM 接続エラーで失敗する

ユーザーに LLM プロバイダーの設定を促してください。

対話形式のセットアップ（推奨）：

ocr config provider

手動セットアップ（代替）：

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token <api-key>
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

ocr llm test で接続を検証してください。ここで停止し、ユーザーに認証情報の提供を依頼してください — API キーを捏造したりハードコードしたりしないでください。

参考資料

• 完全なドキュメント: https://github.com/alibaba/open-code-review
• NPM パッケージ: https://www.npmjs.com/package/@alibaba-group/open-code-review
• イシュートラッカー: https://github.com/alibaba/open-code-review/issues