レビューの前に、整地する

これは、Codex CLI を使ったコードレビュー運用についての、僕の小さな実験ログです。
個人のホームページ側でまとめた内容ではあるけれど、rutenya の活動とも接点があるので、こちらにも残しておきます。

rutenya の仕事は、最終的に「人が責任を持てる形で」納品することに尽きる。
そのためには、レビューが機能していることが大事だ。でもレビューは重い。最後の砦になりがちで、疲弊もしやすい。

だから僕は最近、こういう方向に寄せています。

レビューを強くする前に、レビューが成立する地面を整える。

Codex CLI は、その“整地”に向いている。
ここまでが、この記事の主題です。

整地のほうが、安い

コードレビューって、結局のところ「品質を上げるための最後の砦」になりがちだ。
でも実際には、最後まで運んでから直すより、もっと手前でズレに気づけたほうが安い。

人間レビューは強い。
ただ、高い。高いというのは、時間と集中力と、読解の体力の話。

僕が Codex CLI に期待しているのは、「人間を置き換える」ことではない。
人間が読む前に、拾える地雷を拾っておくこと。

静的解析が拾う地雷もある。
でもそれだけじゃない。言語やフレームワークの落とし穴、セキュリティ、運用、保守性みたいな「地味だけど痛いやつ」を、結構いい角度で指摘してくれる。

ここが面白い。

外部視点が入ると、穴が浮く

現場のチェックリストは当然強い。
でも現場に最適化されるぶん、どうしても偏りが出る。そこに外部視点が入るのが効く。

僕はフリーランスなのもあって、いろんな現場と関わることが多い。
チェックリストの粒度も種類も違うし、そもそもチェックリスト自体が存在しない現場もある。

だから最近はこう思う。

見慣れて見えなくなっている穴は、外から来た目のほうが見つけやすい。

Codex のレビュー観点には、単一プロジェクトの事情だけでは出てこない視点が混ざる。
その混ざり方が、たまに刺さる。僕はそこに価値を感じています。

使い分けは、割り切ったほうが続く

結論だけ先に書くと、僕の役割分担はこう。

ローカル（コミット前）: 速く、軽く、指摘だけ（整地）
フック（pre-commit）: 自動で振り返るきっかけを作る（止め役にはしない）
PR段階（CI）: 人の目 + AI で時間を使う（精査）

ポイントは、どこでも全力でやらないこと。
全力にすると、習慣として死ぬ。僕はここで何度かやられている。

ローカルで整地する

一番メジャーで、一番うまくいきやすいのがこれ。

ローカルでコミットする前に Codex CLI を起動
差分を読ませて、指摘だけもらう

この運用の核は、作業ツリーを汚さずに差分を読んで指摘だけ返すこと。
提案の採否は自分で握れる。ここが継続のコツだと思う。

未コミット差分をレビューするプリセットがあるなら、まずはそれで十分。
ここまでで「整地」は成立する。

フックは、止め役にしない

次に出てくる発想が pre-commit フックだと思う。

codex exec 等で自動レビューする
コミットを“振り返りイベント”にする

これは悪くない。
ただ、「指摘があったらコミットを止めたい」となると、途端に重くなる。

指摘の有無を機械的に判定する必要がある
出力のブレや例外があると、フックが CI みたいに重くなる

だから僕は、ここは割り切っている。

pre-commit は止め役ではなく、振り返りのきっかけ。

止めるなら、PR段階でやればいい。
ローカルとフックで“締め付け”をやり始めると、続かない。

やり過ぎると、QCDで負ける

ローカルでもレビューして、フックでもレビューして、さらにPRでも…。
やればやるほど品質は上がりそうだけど、QCD（品質・コスト・納期）で見ると負けやすい。

ローカル段階で完璧を狙うと、体力が削れて継続が難しくなる。
僕は「ローカルは整地」「PRで精査」くらいがちょうどいい。

境界線を引く

Codex CLI は便利だからこそ、境界線を引いたほうが使いやすい。

権限の指定方法はいろいろあるけれど、コマンドやオプションは忘れがちだ。
入力するのも面倒になる。
だから僕は config.toml で固定するのが現実的だと思っている（個人・プロジェクト単位どちらでも）。

僕の落とし所はこのあたり。

ファイル編集はできる
危険な実行や外部アクセスは承認で止める
レビューは原則コメント中心

このくらいにしておくと、AIに任せる線引きがはっきりする。

そして当たり前だけど、コードそのものは最終的に自分が責任を持つべきものだ。
ただ、ある程度精度の高い出力ができる現代においては、「AIが書いたから。そう言っていたから。」という意識が深層に残ることがある。表層に出てしまうこともある。

余談だが、プロンプトエンジニアやアルゴリズムエンジニアのように主戦場が「AIに書かせる」ポジションもある。
そこは専門領域として成立しているし、その人達はそこに責任を持つべきだ。

問題は、それを履き違えたまま「自分でも理解していないコード」を量産し、AIに書かせること自体が目的ではないエンジニアが大量のコードを読んで、バグを治し、リファクタリングし、納品レベルでドキュメント化する…という負債の現場が生まれることだ。僕はそういう現場をすでにいくつか見てきた。

逆に言えば、「AIに書かせる」こと自体が悪いわけじゃない。
ただしそれが自分の責任範囲なら、意識的に引き受ける必要がある。

何に責任を持つのかを、AIと自分の間で先に認識しておく。

それが権限を絞る意味だと思っている。

PRで仕組みにする

レビューを「個人の頑張り」から「仕組み」に寄せたいなら、PR段階に寄せるのが良い。

GitHub Actions + codex-action を導入
PR作成時に自動でレビューを流す

最初は安全運用でいい。

まずはコメントのみ
自動修正は運用が固まってから
設定をリポジトリに同梱して個人差を減らす

ここまでくると、レビューは「気合」ではなく「地形」になる。

まとめ

僕にとって Codex CLI は「AIにレビューさせるツール」というより、人間が読むべき場所を、人間が読むための状態に整えるツールだ。

ローカルで軽く整地する
権限を絞って安心して使う
PRで仕組みにする

まずはコミット前の /review から。
そこが一番、静かに効く。