codex-review

Codex コードレビュー スキル

トリガー条件

ユーザー入力に以下のいずれかが含まれる場合にトリガーされます。

• 「代码审核」、「代码审查」、「审查代码」、「审核代码」
• 「review」、「code review」、「review code」、「codex 审核」
• 「帮我审核」、「检查代码」、「审一下」、「看看代码」

基本概念：意図と実装

codex review --uncommitted を実行するだけでは、AI に「何が行われたか（実装）」しか示されません。 最初に意図を記録しておくことで、AI に「何を実現しようとしていたか（意図）」を伝えられます。

「コード変更＋意図の説明」を組み合わせて入力するのが、AI コードレビューの品質を向上させる最も効果的な方法です。

スキルの構成

このスキルは、次の 2 つのフェーズで動作します。

1. 準備フェーズ（現在のコンテキスト）：作業ディレクトリを確認し、CHANGELOG を更新します
2. レビュー・フェーズ（分離されたコンテキスト）：Task ツールを呼び出して Lint と codex review を実行します（コンテキストの無駄を減らすため、context: fork を使用）

実行手順

0. ［最初に］作業ディレクトリの状態を確認する

git diff --name-only && git status --short

出力に基づいてレビュー・モードを決定します。

• 未コミットの変更がある → 手順 1〜4 に進みます（通常のフロー）
• 作業ディレクトリがクリーン → codex-runner を直接呼び出します：codex review --commit HEAD

1. ［必須］CHANGELOG が更新されているか確認する

レビューを行う前に、CHANGELOG.md に現在の変更内容が記載されているか必ず確認してください。

# Check if CHANGELOG.md is in uncommitted changes
git diff --name-only | grep -E "(CHANGELOG|changelog)"

CHANGELOG が更新されていない場合は、ユーザーに手動で行うよう求めず、必ず以下を自動で実行してください。

1. 変更を分析する：git diff --stat と git diff を実行して変更内容をすべて取得します
2. CHANGELOG エントリーを自動生成する：コード変更に基づいて、要件に沿ったエントリーを生成します
3. CHANGELOG.md に書き込む：Edit ツールを使用して [Unreleased] セクションの先頭にエントリーを挿入します
4. レビュー・フローを続行する：CHANGELOG の更新後、すぐに次の手順に進みます

自動生成する CHANGELOG エントリーの形式：

## [Unreleased]

### Added / Changed / Fixed

- Feature description: what problem was solved or what functionality was implemented
- Affected files: main modified files/modules

例 — 自動生成のフロー：

1. Detected CHANGELOG not updated
2. Run git diff --stat, found handlers/responses.go modified (+88 lines)
3. Run git diff to analyze details: added CompactHandler function
4. Auto-generate entry:
   ### Added
   - Added `/v1/responses/compact` endpoint for conversation context compression
   - Supports multi-channel failover and request body size limits
5. Use Edit tool to write to CHANGELOG.md
6. Continue with lint and codex review

2. ［重要］新しいファイルをすべてステージングする

codex review を呼び出す前に、すべての新しいファイル（未追跡ファイル）を git のステージング領域に追加する必要があります。そうしないと、codex が P1 エラーを報告します。

# Check for new files
git status --short | grep "^??"

新しいファイルがある場合は、自動的に実行します。

# Safely stage all new files (handles empty list and special filenames)
git ls-files --others --exclude-standard -z | while IFS= read -r -d '' f; do git add -- "$f"; done

説明：

• -z はファイル名をヌル文字で区切るため、スペースや改行を含むファイル名も正しく処理できます
• while IFS= read -r -d '' は、ファイル名を 1 つずつ読み込みます
• git add -- "$f" は区切り文字 -- を使用するため、- で始まるファイル名も正しく処理できます
• 新しいファイルがない場合、ループ本体は実行されず、安全にスキップされます
• 変更済みファイルはステージングせず、新しいファイルのみを処理します
• codex が適切にレビューするには、ファイルが git に追跡されている必要があります

3. タスクの難易度を評価し、codex-runner を呼び出す

変更規模を集計します。

# Get summary line for ALL changes (staged + unstaged)
# IMPORTANT: Must use 'HEAD' as base to include both staged and unstaged changes
git diff --stat HEAD | tail -1

git diff --stat HEAD を使用する理由：

• git diff --stat は、ステージングされていない変更のみを表示します
• git diff --cached --stat は、ステージング済みの変更のみを表示します
• git diff --stat HEAD は、ステージング済みとステージングされていない変更の両方をまとめて表示します
• 最終行（tail -1）は、ファイル数の合計と行の変更数を示す概要行です

難易度の評価基準：

モデルと推論の強度の組み合わせ：

推奨するのは gpt-5.3-codex のみです。タスクの複雑さに応じて model_reasoning_effort とタイムアウトを選択してください。

組み合わせ	品質	所要時間	タイムアウト	推奨される用途
model=gpt-5.3-codex model_reasoning_effort=xhigh	高	約8～20分	15～40分	難しいタスク、重要なコード、アーキテクチャの変更
model=gpt-5.3-codex model_reasoning_effort=high	良好	約5～6分	10分	通常のタスク（デフォルト）

重要なタスク（次の条件のいずれかに該当する場合。最高の推論の強度を使用してください。）

• 変更されたファイルが 30 個以上
• コード変更の合計（挿入行数＋削除行数）が 2000 行以上
• コアアーキテクチャやアルゴリズムの変更を含む（ユーザーが明示的に言及している）
• 設定：--config model=gpt-5.3-codex --config model_reasoning_effort=xhigh、タイムアウトは 40 分

難しいタスク（次の条件のいずれかに該当する場合）：

• 変更されたファイル数 ≥ 10
• コードの変更合計（追加行数 + 削除行数）≥ 500 行
• 単一の指標：追加行数 ≥ 300 行、または削除行数 ≥ 300 行
• モジュールをまたぐリファクタリング
• デフォルト設定：--config model=gpt-5.3-codex --config model_reasoning_effort=xhigh、タイムアウト 15 分

通常タスク（上記以外の場合）：

• デフォルト設定：--config model=gpt-5.3-codex --config model_reasoning_effort=high、タイムアウト 10 分

評価方法：

難易度を判断するため、git diff --stat HEAD の出力を必ず正しく解析してください。

# Get the summary line (last line of git diff --stat HEAD)
git diff --stat HEAD | tail -1
# Example outputs:
# "20 files changed, 342 insertions(+), 985 deletions(-)"
# "1 file changed, 50 insertions(+)"  # No deletions
# "3 files changed, 120 deletions(-)"  # No insertions

重要：サマリー行が重要な理由：

• 各ファイルには個別の統計が表示されます：file.go | 171 ++++++++++++++++++++-
• 合計が表示されるのは最後の行だけです：6 files changed, 1341 insertions(+), 18 deletions(-)
• 正確な合計を取得するには、tail -1 で最後の行を抽出してください

解析ルール：

1. 「X file(s) changed」からファイル数を抽出します（「1 file」と「N files」の両方に対応）
2. 「Y insertion(s)(+)」があれば追加行数を抽出し（「1 insertion」と「N insertions」の両方に対応）、なければ 0 とします
3. 「Z deletion(s)(-)」があれば削除行数を抽出し（「1 deletion」と「N deletions」の両方に対応）、なければ 0 とします
4. 変更合計 = 追加行数 + 削除行数を計算します

重要なエッジケース：

• 単一ファイル：「1 file changed」（単数形）
• 追加行なし：Git は「insertions(+)」を完全に省略するため、0 として扱います
• 削除行なし：Git は「deletions(-)」を完全に省略するため、0 として扱います
• 純粋なリネーム：「0 insertions(+), 0 deletions(-)」と表示される場合もあれば、両方が省略される場合もあります

判定ロジック（上から順に確認し、最初に一致した条件を適用）：

• IF file_count >= 30 OR total_changes >= 2000 → 重大（gpt-5.3-codex + xhigh）
• IF file_count >= 10 → 困難（gpt-5.3-codex + xhigh）
• IF total_changes >= 500 → 困難（gpt-5.3-codex + xhigh）
• IF insertions >= 300 OR deletions >= 300 → 困難（gpt-5.3-codex + xhigh）
• ELSE → 通常（gpt-5.3-codex + high）

例：

• ⭐ 「50 files changed, 2000 insertions(+), 1500 deletions(-)」→ 重大タスク。model=gpt-5.3-codex model_reasoning_effort=xhigh を使用し、タイムアウトは 40 分（コアアーキテクチャの変更）
• ✅ 「20 files changed, 342 insertions(+), 985 deletions(-)」→ 困難なタスク。model=gpt-5.3-codex model_reasoning_effort=xhigh を使用し、タイムアウトは 15 分
• ✅ 「5 files changed, 600 insertions(+), 50 deletions(-)」→ 困難なタスク。model=gpt-5.3-codex model_reasoning_effort=xhigh を使用し、タイムアウトは 15 分
• ❌ 「3 files changed, 150 insertions(+), 80 deletions(-)」→ 通常タスク。model=gpt-5.3-codex model_reasoning_effort=high を使用し、タイムアウトは 10 分
• ❌ 「1 file changed, 50 insertions(+)」→ 通常タスク。model=gpt-5.3-codex model_reasoning_effort=high を使用し、タイムアウトは 10 分

codex-runner サブタスクの呼び出し：

Task ツールを使って codex-runner を呼び出し、Lint と codex review を含むコマンド全体を渡してください：

Task parameters:
- subagent_type: Bash
- description: "Execute Lint and codex review"
- timeout: 2400000 (40 minutes for critical tasks) / 900000 (15 minutes for difficult tasks) / 600000 (10 minutes for normal tasks)
- prompt: Choose corresponding command based on project type and difficulty

Go project - Critical task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Go project - Difficult task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Go project - Normal task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Node project - Critical task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Node project - Difficult task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Node project - Normal task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Python project - Critical task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Python project - Difficult task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Python project - Normal task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Clean working directory:
  codex review --commit HEAD --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

4. 自己修正と重要度に応じた修正

Codex が Changelog の説明とコードのロジックに矛盾があると判断した場合：

• コードのエラー → コードを修正します
• 説明が不正確 → Changelog を更新します

Codex が P0 / P1 / P2 の問題を報告した場合は、報告だけで終わらせず、直ちに積極的に修正する必要があります。

必須の対応：

1. P0 / P1 / P2 がある → 問題を修正するために、コードまたは関連ファイルを直接変更します
2. 修正後 → 必要な lint／検証／レビューコマンドを再実行し、問題が解決したことを確認します
3. 再確認後にのみ完了を報告 → 修正内容と、合格した検証を明確に伝えます
4. P3 以下／提案のみ → ユーザーから追加の整理を明示的に求められていない限り、自動修正せずに報告してもかまいません

修正の優先順位：

• P0：ブロッカー、セキュリティ、データ損失、正確性の不具合 → 最優先で修正する必要があります
• P1：影響の大きい機能またはロジックのバグ → 修正する必要があります
• P2：明確な修正方法がある、保守性または正確性に関わる重要な問題 → 同じ作業内で積極的に修正してください

制約：

• 修正は最小限にし、報告された問題に直接関連するものに限ってください
• 無関係なリファクタリングに範囲を広げないでください
• 問題の解決に構造変更が必要な場合を除き、既存のスタイルとアーキテクチャを維持してください

完全なレビュー手順

1. [GATE] CHANGELOG を確認 - 更新されていない場合は自動生成して記入します（現在のコンテキストを活用して変更の意図を把握します）
2. [PREPARE] 未追跡ファイルをステージング - 新しいファイルをすべて Git のステージングエリアに追加します（codex の P1 エラーを回避します）
3. [EXEC] タスク → Lint + codex レビュー - Task ツールを呼び出して Lint と codex を実行します（コンテキストを分離し、無駄を減らします）
4. [FIX] 重大度に応じた自己修正 - コードを修正するか、意図と実装が異なる場合は説明を更新します。P0/P1/P2 の問題を事前に修正し、チェックを再実行します

Codex レビューコマンドのリファレンス

基本構文

codex review [OPTIONS] [PROMPT]

注：[PROMPT] パラメーターは、--uncommitted、--base、--commit と併用できません。

よく使うオプション

オプション	説明	例
--uncommitted	作業ディレクトリ内の未コミット変更をすべてレビューします（ステージ済み + 未ステージ + 未追跡）	codex review --uncommitted
--base <BRANCH>	指定したベースブランチとの差分をレビューします	codex review --base main
--commit <SHA>	指定したコミットで導入された変更をレビューします	codex review --commit HEAD
--title <TITLE>	任意のコミットタイトル。レビュー概要に表示されます	codex review --uncommitted --title "feat: add JSON parser"
-c, --config <key=value>	設定値を上書きします	codex review --uncommitted -c model="gpt-5.3-codex"

使用例

# 1. Review all uncommitted changes (most common)
codex review --uncommitted

# 2. Review latest commit
codex review --commit HEAD

# 3. Review specific commit
codex review --commit abc1234

# 4. Review all changes in current branch relative to main
codex review --base main

# 5. Review changes in current branch relative to develop
codex review --base develop

# 6. Review with title (title shown in review summary)
codex review --uncommitted --title "fix: resolve JSON parsing errors"

# 7. Review using the recommended model
codex review --uncommitted -c model="gpt-5.3-codex"

重要な制限事項

• --uncommitted、--base、--commit は相互排他的であり、同時に使用できません
• [PROMPT] パラメーターは、上記の 3 つのオプションと相互排他的です
• Git リポジトリのディレクトリ内で実行する必要があります

重要な注意事項

• Git リポジトリのディレクトリ内で実行してください
• タイムアウトはタスクの難易度に応じて自動調整されます：
  • 重要なタスク：40 分（timeout: 2400000）
  • 難しいタスク：15 分（timeout: 900000）
  • 通常のタスク：10 分（timeout: 600000）
• codex コマンドが適切に設定され、ログイン済みである必要があります
• codex は大規模な変更を自動的にバッチ処理します
• CHANGELOG.md を未コミットの変更に含めてください。含まれていない場合、Codex は意図の説明を確認できません

設計上の理由

なぜコンテキストを分離するのですか？

1. CHANGELOG の更新には現在のコンテキストが必要です：ユーザーとのこれまでの会話やタスクの意図を理解し、正確な変更内容の説明を生成します
2. Codex のレビューには会話履歴は不要です：コードの変更と CHANGELOG だけが必要なため、独立して実行するほうが効率的です
3. トークンの消費を抑えます：codex レビューを独立したサブタスクとして実行することで、無関係な会話のコンテキストを引き継ぎません