AI エージェントにコードを書かせるのが当たり前になりつつある一方で、「動くかどうか」と「何をしているか」を同じものとして扱う危うさも目立ってきた。今回紹介する Sphinx は、そのズレを Git の push 直前にわざわざ突きつける仕組みだ。コードを最終的に通す前に、変更の意味を人間に説明させる。便利さを追う流れの中で、あえて立ち止まらせる発想が面白い。
Sphinx は、agent-assisted development 向けの Git hook だ。つまり、コードを書いたあと、Git の push の場面で割り込んでくる。しかも止める理由は、テストが落ちたからでも、lint が通らないからでもない。Sphinx が知りたいのは、そのコードが実際に何をするのか、そして何かがうまくいかなかったときにどう振る舞うのかだ。
導入はかなり簡単で、元記事では npm install -g sphinx-understand として入れ、sphinx install を実行する流れが示されている。対象は Git そのものにも、OpenRouter や OpenAI-compatible endpoint、あるいは既存の coding agent にもつなげられる。対応している例としては Codex、Claude Code、Cursor、OpenCode、Pi が挙げられていた。Node は 22.19+、環境は macOS、Linux、WSL で動くという。
Sphinx の動きは、実演のやり取りでよく分かる。たとえば「webhook handler が、charge() を呼ぶ前に event ID を保存する」という変更があったとする。Stripe がタイムアウトして同じイベントを再送したらどうなるか、Sphinx はそこで問いを出す。最初の答えとして「2回処理されて二重請求になる」と返すと、Sphinx はそれは違うと指摘する。再送時には保存済み ID を見つけて、請求せずに 200 を返すからだ。では、charge() 自体が失敗したら次の retry はどうなるか。ここでまた問いが進み、答えが詰まると、保存のタイミングが早すぎることに気づかされる。元記事のこのやり取りは、単なるクイズではなく、失敗時の分岐を頭で追わせるためのものだ。
記事は、こうした質問が「あなたの diff から来る」と説明する。Sphinx はリポジトリの保護されたブランチで Git を止め、変更の内容を読んで、「何かが壊れたときに何が起きるか」をレビューする存在として振る舞う。答えを間違えれば、その場で理解し直す。答えられれば push は続く。宣伝文句としてはかなり強めで、「you can outsource your thinking, but not your understanding」という Sun Tzu の引用まで掲げている。要するに、思考の下働きは agent に任せても、理解まで外注してはいけない、という主張だ。
なお、Sphinx は「質問の答えが coding agent に送られることはない」としている。.env や鍵も開かない。急ぐ場合には sphinx yolo でスキップでき、そのスキップも記録される。自由度は残しつつ、理解の確認をデフォルトに寄せる設計になっている。
Sphinx の発想でいちばん鋭いのは、AI コーディングの弱点を「コード品質」ではなく「説明責任」に置いているところだと思う。生成コードは、見た目の diff だけならそれなりに整っていることが多い。テストも通る。ところが、実運用で問題になるのは、例外時の挙動や再送、二重実行、部分失敗の扱いだ。そこで問うべきなのは、どんな関数を呼んだかではなく、失敗したら誰が何を保証するかだろう。Sphinx はその穴を、push の直前に人間へ突きつける。
ただ、これは「AI は危険だ」という単純な話ではない。むしろ逆で、AI が広く使われるほど、最後に人間が理解を口にする機会は減る。コードは増えるのに、頭の中の説明は薄くなる。そうなると、バグが出たときに誰も全体像を持っていない、という状態になりやすい。Sphinx が面白いのは、そこで「レビュー」を手順化したことだ。人の脳内でやるべき確認を、Git hook に寄せている。これなら、特に忙しいチームほど効くと思う。
元記事の例が webhook と retry を選んでいるのも象徴的だ。Web アプリでは、失敗と再試行は例外ではなく日常だからだ。Stripe のような外部サービスを相手にすると、「成功したように見えて実は失敗していた」「失敗したように見えるが、相手側では処理済み」といったズレが普通に起きる。Sphinx の問いは、そのズレを言語化させる。ここで必要なのは、正しいコードを読む力というより、システムの状態遷移を頭の中で回す力だと思う。
この手の確認は、通常の code review でも本来やるべきことだ。ただ、現実にはレビュー担当も急いでいるし、AI が作った大量の diff だと読み飛ばしが起きやすい。だから Sphinx は、レビューの代替というより、レビュー前の準備運動に見える。説明できない変更は、たぶん自分でも十分に分かっていない。そういう変更を push させないだけで、事故率はかなり下がるはずだ。地味だが、運用の世界ではこの地味さが強い。
Sphinx には sphinx yolo という逃げ道がある。急ぎなら通せるし、スキップも記録される。ここがうまいと思う。完全なゲートにしてしまうと、現場はすぐに嫌がる。深夜の障害対応や、実験的なブランチでは、毎回同じ確認を挟むのは重い。だからこそ、止める仕組みと、例外を許す仕組みを両立させているのだろう。
ただし、この設計には注意もいる。スキップが記録されるだけで、実際に誰がその記録を見るのか、どのくらいの頻度で振り返るのかが曖昧だと、結局は形骸化する。私は、Sphinx の価値は「止める」ことそのものより、チームに“理解を飛ばした回数”を見える化するところにあると思う。もし skip が多いなら、そのチームは理解を求めるコストを払えていない、というシグナルになる。逆に、毎回ちゃんと答えられるなら、AI を使っても設計の感覚は保たれているはずだ。
Sphinx は、AI エージェント時代の便利な補助ツールというより、開発者の評価軸を少しずらす道具だと思う。これまで強かったのは「どれだけ早く書けるか」だった。でも agent が書く速度が上がるほど、差がつくのは「変更の意味を説明できるか」になる。そこを Git の流れの中で確認するのは、かなり筋がいい。
もちろん、これで全てのバグが防げるわけではない。質問の作り方が浅ければ、表面的な答えで通ってしまう。逆に、質問が厳しすぎると、現場は面倒がって外してしまう。だから Sphinx 自体も、使い方次第で良し悪しが出る。でも、少なくとも「AI に書かせたあと、人間が理解し直す場所をどこに置くか」という問いには、かなり明快な答えを出している。私はそこに、このツールの一番の価値があると思う。
参考: Sphinx — you can outsource your thinking, but not your understanding
