codex-code-review

Codex コードレビューのループ

概要

このスキルは、codex エージェントがレビューするコードの修正ワークフロー全体をオーケストレーションします。以下を処理します。

• codex --full-auto c CLI を使用した codex へのレビュー依頼
• レビュー出力を解析し、P0（セキュリティ／正確性）、P1（信頼性）、P2-P4（品質）の指摘事項を特定
• 最大 3 回のレビュー・修正・レビューサイクルによる重大な問題の修正
• 実装計画と origin:ai-review ラベルを付けた品質改善のバックログへの延期
• 他のエージェントと並行して作業する場合に、対象ファイルを選択してコミットするモノレポへの対応
• 3 サイクル後も P0/P1 の問題が残る場合のサーキットブレーカーによるエスカレーション

使用するタイミング

コードの codex レビューが必要な場合に、このスキルを起動します。一般的な使用例：

• 「このコードを codex でレビューして」 — 現在の変更に対するレビューのループを開始します
• 「変更内容を codex でレビューして」 — 上記と同じです
• 「codex review --uncommitted」 — コミットされていない変更をすべてレビューします
• 「codex review --commit 」 — モノレポ内の特定のコミットをレビューします
• codex に関する質問（例：「codex はどのように動作しますか？」）— このスキルを起動せず、直接回答します

質問では起動しないでください。 直接のレビュー依頼に対してのみ有効にします。

---

レビューループ：手順

ENTRY: User requests codex review or skill is triggered by "codex review" in a message

┌──────────────────────────┐
│ 1. INVOKE CODEX REVIEW   │ ← Run: codex --full-auto c [--uncommitted|--commit <SHA>|--base <BRANCH>]
└──────┬───────────────────┘   Output goes to .agent/reviews/review-<timestamp>.md
       │
       ▼
┌──────────────────────────┐
│ 2. READ & PARSE REVIEW   │ ← Read markdown file, extract P0/P1/P2-P4 findings and verdict
└──────┬───────────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  ANY P0/P1?              NO         FILE P2-P4 ISSUES → Exit loop
       │                              (via backlog CLI)
       │ YES                         Create issue per finding with
       │                             - label: origin:ai-review
  ┌────────────────┐                - Implementation plan
  │ 3. REMEDIATE   │                - Priority (P2 or P3)
  │ P0/P1 FINDINGS │
  └────┬───────────┘
       │ (amend commit or new changes)
       │
       ▼
  ┌──────────────────────┐
  │ 4. LOOP CHECK        │
  │ Cycle count < 3?     │
  └────┬───────────────┬─┘
       │ YES           │ NO
       │               └─→ SUMMARIZE & ASK USER TO CONTINUE
       │                   (or exit if user declines)
       ▼
  Re-run codex review (step 1, same files/scope)
  Loop back to step 2

サイクルの管理

• サイクル 1：実装後の初回レビュー
• サイクル 2：最初の修正後
• サイクル 3：2 回目の修正後
• サイクル 3 の後：P0/P1 が残っている場合は停止します。指摘事項をまとめ、続行するかユーザーに確認します（まれなケースであり、通常は設計レベルの問題を示します）

---

判断ツリー：指摘事項への対応

レビューで P0/P1 の指摘事項が示された場合（判定：REQUEST CHANGES）

1. codex のレビューマークダウンファイルを読みます
2. 各 P0 および P1 の指摘事項について、以下を抽出します。
   • 指摘 ID とタイトル
   • ファイルの場所
   • 提案された修正
3. コード内で指摘された箇所のみを修正します
4. リファクタリングや新機能の追加はしないでください
5. 修正に大幅な設計変更が必要な場合はその旨を記録し、次のサイクルで codex に再評価させます
6. コミットを修正するか、新しいコミットを作成します（git config によるユーザーの選択。デフォルトでは最後に 1 つのコミットにまとめるため、既存のコミットを修正します）
7. サイクルカウンターを増やし、codex レビューを再実行します

レビューで P2-P4 の指摘事項が示された場合（判定：APPROVE または PASS WITH ISSUES）

1. 各 P2/P3 の指摘事項について、以下を判断します。

   • 今すぐ修正：裁量で判断し、同じサイクル内で改善を実装します
   • 延期：以下を含むバックログ課題を作成します。
     • 種別ラベル：remediation
     • 重要度ラベル：P2 または P3
     • カスタムラベル：origin:ai-review
     • codex の提案に基づく実装計画
     • レビューに基づく受け入れ条件

2. 例：

   # P2 finding deferred to backlog
   backlog task create "Code clarity: add docstring to validateInput()" \
     -d "Review finding: missing documentation on public function" \
     -l remediation -p 2 \
     --ac "Add docstring explaining parameter types and return value" \
     --plan "Add JSDoc comment above function definition per project style"
   

レビューで指摘事項がない場合（判定：APPROVE）

ループを終了します。コードに問題はありません。該当する場合はテストレビューに進むか、マージ用にコミットします。

---

モノレポへの対応

複数のエージェントがいるモノレポでは、コミットする内容とレビュー対象の範囲を慎重に選びます。

シナリオ 1：自分の変更のみ

作業ディレクトリに自分の変更のみがある場合：

codex --full-auto c --uncommitted

レビューループが完了したら、変更をコミットします。

シナリオ 2：変更が混在（自分と他のエージェント）

他のエージェントによる未追跡または未コミットの変更がある場合：

1. まず自分のファイルのみをコミットします。

   git add <your-files-only>
   git commit -m "Your commit message"
   

2. コミット SHA を記録します
3. 自分のコミットをレビューします。

   codex --full-auto c --commit <SHA>
   

4. コミットを修正して問題を解決します。

   git add <fixed-files>
   git commit --amend --no-edit
   

   （元のメッセージを保持します。修正内容は追記されます）
5. 通常どおりレビューに戻ります

結果： 自分の変更と修正を含む、問題のない 1 つのコミットになります。他のエージェントの作業は分離されたままです。

---

ファイルの場所

• レビュー出力： .agent/reviews/review-<timestamp>.md（プロジェクトルートからの相対パス）
• サイクルごとにレビュー用ファイルを 1 つ作成 — codex --full-auto c を実行するたびに新しいファイルが作成されます
• 常に最新のファイルを読む — タイムスタンプを確認し、現在のサイクルのレビューを読んでいることを確かめます

---

同梱リファレンス

references/codex-cli-reference.mdを参照してください。内容は次のとおりです。

• codex CLI の完全な構文と呼び出しパターン
• --uncommitted、--commit、--baseを選択する方法
• 各モードを使用するタイミング

references/review-format.mdを参照してください。内容は次のとおりです。

• レビュー用 Markdown 出力の構成
• P0/P1/P2/P3 のセクションの解析方法
• 判定（APPROVE / REQUEST CHANGES / BLOCKED）の特定方法
• レビュー出力の例

references/backlog-integration.mdを参照してください。内容は次のとおりです。

• 保留した指摘からバックログの課題を作成する方法
• ラベルと優先度の規約
• 実装計画のテンプレート
• レビューから起票された課題の例

scripts/parse_codex_review.shを参照してください。内容は次のとおりです。

• レビュー用 Markdown から指摘を抽出するヘルパースクリプト
• サイクルごとの P0/P1/P2/P3 の件数
• 判定の簡易抽出

---

主なルール

1. **ループを終了する前に、すべての P0/P1 を修正してください。**例外はありません。
2. P2〜P4 はバックログに回すか、任意で修正できます。
3. **指摘ごとに課題を1件作成してください。**無関係な P2/P3 を1件の課題にまとめないでください。
4. **保留する課題には計画を含めてください。**codex が問題を特定し、構造化されたアプローチはあなたが提示します。
5. **修正中は新しいコミットではなく、コミットを amend してください。**最終的にクリーンなコミットを1つだけ残します。
6. **レビューサイクルは最大3回です。**サイクル3の後も P0/P1 が残る場合は、要約してユーザーに続行するか確認してください。
7. **モノレポでは、対象を絞ってコミットしてください。**自分が変更したファイルだけをレビューして修正してください。

---

エスカレーション：サーキットブレーカーが作動した場合

レビューサイクルを3回実施した後も P0/P1 の指摘が残っている場合：

1. 修正を停止します。4回目のサイクルは試みないでください。
2. 次の内容を含む、構造化された要約を作成します。
   • 各サイクルで試みたこと
   • 残っている P0/P1 の指摘
   • 指摘が残っている理由（エージェントによる評価 — 設計上の問題か、要件の競合か、仕様の曖昧さか）
   • 推奨する人による対応
3. この要約をユーザーに提示し、次にどうするか確認します。

エスカレーションが必要となるのは通常、元のタスク仕様の明確化が必要な場合、またはコードの修正範囲を超えるアーキテクチャ上の変更が必要な場合です。

---

他のスキルとの連携

• backlog-md：origin:ai-reviewラベルを付けて、保留する P2/P3 の指摘をbacklog task createで起票します
• git-ops：コミットの処理、amend、モノレポで対象を絞ったステージング
• requesting-code-review：codex のレビューループが完了した後、人によるコードレビューも必要な場合に使用します

---

クイックリファレンス：ワークフロー全体

1. User: "codex review"
        │
        ▼
2. Invoke: codex --full-auto c --uncommitted
        │
        ▼
3. Read: .agent/reviews/review-<timestamp>.md
        │
        ├─────────────────────────────────────────┐
        ▼                                         ▼
   P0/P1 FOUND?              NO         FILE P2-P4 ISSUES
   ├─ YES: Fix + Loop ────────────────► backlog task create ... --plan "..."
   └─ NO: File P2-P4 → Exit            (each finding = one issue)
        │
        ├─ Cycle 1 → Fix → Review
        ├─ Cycle 2 → Fix → Review
        ├─ Cycle 3 → Fix → Review
        │
        └─ If P0/P1 remain → Summarize + Ask User
                │
                └─► Continue? (rare) / Stop & Escalate