Codex コードレビュースキル

トリガー条件

ユーザー入力に以下が含まれている場合にトリガーされます:

• "代码审核", "代码审查", "审查代码", "审核代码"
• "review", "code review", "review code", "codex 审核"
• "帮我审核", "检查代码", "审一下", "看看代码"

コアコンセプト: 意図 vs 実装

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 に現在の変更の説明が含まれているかを確認する必要があります。

# CHANGELOG.md がコミットされていない変更に含まれているかをチェック
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

- 機能説明: どのような問題を解決したか、またはどのような機能を実装したか
- 影響されるファイル: メインの変更ファイル/モジュール

例 - 自動生成フロー:

1. CHANGELOG が更新されていないことを検出
2. git diff --stat を実行、handlers/responses.go が変更されている (+88 行) ことを確認
3. git diff を実行して詳細を分析: CompactHandler 関数が追加されている
4. エントリを自動生成:
   ### Added
   - 会話コンテキスト圧縮のための `/v1/responses/compact` エンドポイントを追加
   - マルチチャネルフェイルオーバーとリクエストボディサイズ制限をサポート
5. Edit ツールを使用して CHANGELOG.md に書き込み
6. lint と codex review を続行

2. [重要] すべての新規ファイルをステージング

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

# 新規ファイルをチェック
git status --short | grep "^??"

新規ファイルがある場合、自動的に以下を実行:

# 安全にすべての新規ファイルをステージング (空のリストと特殊なファイル名を処理)
git ls-files --others --exclude-standard -z | while IFS= read -r -d '' f; do git add -- "$f"; done

説明:

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

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

変更スケールをカウント:

# すべての変更 (ステージング済み + 未ステージング) の概要行を取得
# 重要: ベースとして 'HEAD' を使用してステージング済みと未ステージング両方の変更を含める
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 出力を正しく解析して難易度を決定する必要があります:

# 概要行を取得 (git diff --stat HEAD の最後の行)
git diff --stat HEAD | tail -1
# 出力例:
# "20 files changed, 342 insertions(+), 985 deletions(-)"
# "1 file changed, 50 insertions(+)"  # 削除なし
# "3 files changed, 120 deletions(-)"  # 追加なし

重要: 概要行が重要な理由:

• 各ファイルは個別の統計を表示: 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 ファイル数 >= 30 OR 合計変更数 >= 2000 → クリティカル (gpt-5.3-codex + xhigh)
• IF ファイル数 >= 10 → 難しい (gpt-5.3-codex + xhigh)
• IF 合計変更数 >= 500 → 難しい (gpt-5.3-codex + xhigh)
• IF 追加 >= 300 OR 削除 >= 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 パラメータ:
- subagent_type: Bash
- description: "Lint と codex review を実行"
- timeout: 2400000 (クリティカルタスク 40 分) / 900000 (難しいタスク 15 分) / 600000 (通常のタスク 10 分)
- prompt: プロジェクトタイプと難易度に基づいて対応するコマンドを選択

Go プロジェクト - クリティカルタスク:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Go プロジェクト - 難しいタスク:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Go プロジェクト - 通常のタスク:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Node プロジェクト - クリティカルタスク:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Node プロジェクト - 難しいタスク:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Node プロジェクト - 通常のタスク:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Python プロジェクト - クリティカルタスク:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Python プロジェクト - 難しいタスク:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Python プロジェクト - 通常のタスク:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

クリーンな作業ディレクトリ:
  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. [ゲート] CHANGELOG をチェック - 更新されていない場合は自動生成して書き込む (現在のコンテキストを活用して変更意図を理解)
2. [準備] 追跡されていないファイルをステージング - すべての新規ファイルを git ステージング領域に追加 (codex P1 エラーを回避)
3. [実行] Task → Lint + codex review - Task ツールを呼び出して Lint と codex を実行 (分離されたコンテキスト、消費を削減)
4. [修正] 重大度駆動の自己修正 - 意図 ≠ 実装の場合はコードまたは説明を修正。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. すべてのコミットされていない変更をレビュー (最も一般的)
codex review --uncommitted

# 2. 最新のコミットをレビュー
codex review --commit HEAD

# 3. 特定のコミットをレビュー
codex review --commit abc1234

# 4. 現在のブランチのすべての変更を main を基準としてレビュー
codex review --base main

# 5. 現在のブランチのすべての変更を develop を基準としてレビュー
codex review --base develop

# 6. タイトル付きでレビュー (タイトルがレビュー概要に表示されます)
codex review --uncommitted --title "fix: resolve JSON parsing errors"

# 7. 推奨モデルを使用してレビュー
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 レビューを独立したサブタスクとして実行し、関連のない会話コンテキストを持たない