Codex CLIによるコードレビューの使い分け:ローカル、フック、CIと権限の境界

Yohei Kano (aka Hey9Woz)

目次

はじめに

コードレビューは、品質を守る「最後の砦」になりがちです。 しかし実際には、認識のずれを最後まで運んでから修正するより、早い段階で見つけるほうが安く済むことがほとんどです。

Codexのようなツールは進化が速く、使い方もさまざまです。私自身、多くのパターンを試しては、終わりのない実験に少し疲れ、なかなか一つの方法が定着しませんでした。 だからこそ、少し抽象度を上げて、自分なりの使い分け方を整理するためにこの記事を書いています。

私の結論は、Codex CLIの価値は「AIがコードをレビューしてくれること」ではなく、レビューの摩擦を減らし、改善の反復回数を増やすことにあります。

もう一つ、私が大切だと感じる点があります。 一般的なプロジェクト固有のレビュー観点と比べて、十分な情報を与えられたAIは、より広く洗練された視点から問題を指摘できることです。ローカルなチェックリストは強力ですが、特定の環境に最適化されるため、自然に死角も生まれます。そこを外部の視点が補います。

私はフリーランスとして、さまざまなチームに関わります。レビュー文化はチームごとに大きく異なり、チェックリストもプロジェクトによって違います。そもそもチェックリストがない場合もあります。 そのため、外部から一貫したレビュー観点を持ち込むと、「見えていなかった穴」が表に出やすくなります。

私にとって、ちょうどよい役割は次のとおりです。

人が読むべきものを、人が読める状態に整える。

Codexの背後にあるレビュー観点は、単なる「このプロジェクトの好み」ではありません。OpenAIやコントリビューターが磨いてきた考えが含まれ、単一のプロジェクトだけでは生まれにくい視点を持ち込めます。 そこに至ると、単なる「便利なツール」ではなくなります。

要点

  • まずは ローカルで /review を使ったコミット前レビューから始める。最も費用対効果が高い。
  • pre-commitフックによる自動レビューも可能だが、コミットをブロックさせる設計は高コスト。
  • 権限を絞るほど境界が明確になる。config.toml で管理するのが実用的。
  • 本格導入するなら、力をかける場所を GitHub Actions + codex-actionによるPR時のレビューへ移す。

Codex CLIをレビューに使う理由

人によるレビューは強力ですが、コストがかかります。ここでいうコストとは、時間、集中力、認知負荷です。

私がCodex CLIに求めているのは、人の代わりになることではありません。 人が読む前に、明らかな地雷を拾うことです。

ここでいう「地雷」は、静的解析が検出するものだけではありません。Codexは、次のような「静かだけれど、あとで痛くなる問題」もよく指摘します。

  • 言語やフレームワーク特有の落とし穴
  • セキュリティや入力処理への懸念
  • 運用・保守上のリスク
  • 壊れやすく見える設計や責任分界

これらはプロジェクト固有のチェックリストだけでは拾えないことも多く、追加の視点に価値があります。

使い分けについての私の結論

結論はシンプルです。次の分け方が最も長続きします。

  • ローカル(コミット前): 速く、軽く、コメントだけ(地ならし)
  • フック(pre-commit): 習慣のきっかけを作る(「門番」にはしない)
  • PR/CI: 重要な場所に時間を使う(人の目 + AIで丁寧に確認)

主軸:ローカルでコミット前レビュー(ローカルの/review)

最も一般的で、うまく機能しやすいパターンです。

  • コミット前にCodex CLIを実行する
  • 対話型レビューを使って変更を改善する

中心となる考えは、ワーキングツリーを汚さず、差分を読み、フィードバックだけを返すことです。 判断する力は自分に残します。それが継続しやすさにつながります。

TUIのプリセットを使うなら、まずはこちらです。

  • “Review uncommitted changes”(未コミットの差分をレビュー)

うまく機能する理由

  • 変更が「完成したコミット」になる前に問題が見つかる
  • フィードバック中心なので、心理的なハードルが低い
  • 「人によるレビューの前処理」という用途に合っている

補助:pre-commitでの自動レビュー(ブロックは高コスト)

次に試したくなるのは、次の方法です。

  • pre-commitフックから codex exec などでレビューを実行する
  • 自動的に毎回動かす

コミットを「レビューが起きる場」にできるのは魅力的です。 コミット後にレビューするなら、“Review a commit” プリセットが合います。

ただし、注意点があります。

よくある罠

「指摘があったらコミットを止めたい」と考えるかもしれません。 実際には、これは難しい設計です。

  • 機械判定できる形式(「ブロックする/しない」)が必要になる
  • 出力の揺れやエッジケースへの対応が重くなる
  • フックがCIのようになり、運用コストが一気に上がる

そのため私は、pre-commitレビューを強制的なゲートではなく、振り返りのきっかけとして扱います。

ハイブリッドは、たいていやりすぎになる(QCDで負ける)

ローカルレビュー、フックでのレビュー、PRレビューをすべて行う。 品質は上がるかもしれませんが、QCD(品質・コスト・納期)では負けやすくなります。

ローカル段階で「完璧なレビュー」を目指すと、体力を消耗し、習慣そのものが続かなくなります。 私は「ローカル = 地ならし」「PR = 精査」と分けるのが好きです。

権限設計:絞るほど責任の境界が明確になる

Codex CLIは便利だからこそ、境界を引いたほうが安全に使いやすくなります。

権限を設定する方法はいくつかあります。

  • TUIのコマンド
  • 起動時のオプション
  • config.toml

実際には、コマンドやオプションは忘れやすく、毎回入力することも摩擦になります。 そのため私は、ユーザー共通またはプロジェクト単位の config.toml にルールを固定する方法を選びます。

私が基準にしている権限

  • ファイルの編集は許可する
  • 危険な実行や外部アクセスには承認を求める
  • レビューは基本的にコメントだけにする

こうすると、境界が明確になります。

当たり前ですが、やはり重要なことがあります。コードに対して最終的な責任を持つのは自分です。 高品質な出力が得られる今の時代でも、「AIが書いた。AIが大丈夫だと言った」という意識は背景に残り、ときに前面へ出てきます。

補足すると、プロンプトやアルゴリズムを専門とする職種など、「AIに書かせること」そのものが主戦場になる役割もあります。それは正当な専門性であり、責任もそこにあります。 問題なのは、その責任が誤解されることです。理解していないコードを大量に作り、「AIに書かせること」を目的としていないエンジニアが、巨大な差分を読み、バグを直し、リファクタリングし、ドキュメントを整え、出荷できる品質へ引き上げることになります。すでに私は、いくつかのチームがそのような負債へ流れていくのを見ています。

「AIに書かせること」自体が悪いわけではありません。 ただし、出力が自分の責任範囲にあるなら、意識して引き受ける必要があります。 何かを任せる前に、自分が何に責任を持つのか決める。 それが権限を絞る本当の意味です。

PR時に仕組み化する:GitHub Actions + codex-action

「個人の習慣」から「チームの土台」へ進めるなら、この段階です。

  • GitHub Actions + codex-actionを導入する
  • PR作成時に自動レビューを実行する

安全に始めます。

  • 最初はコメントだけにする
  • 自動修正は、ワークフローが安定してから導入する
  • 人による差を減らすため、.codex/config.toml をリポジトリへコミットする

まとめ:習慣から仕組みへ

私にとってCodex CLIは、「AIにコードレビューをさせるツール」ではありません。 人が読むべきものを、人が読める状態へ地ならしするツールです。

  • ローカルで地ならしする
  • 権限を絞り、安全性と責任を明確にする
  • PR時に仕組み化する

この三つがそろうと、レビューの効果は積み重なります。一度きりの取り組みではなく、仕組みになります。

まずはコミット前の /review から始める。 それが静かに効いてくる一歩です。