Sphinxを入れたら、AIが書いたコードをmainにpush前でいきなり止められた

AIエージェントが書いた差分を、ろくに読まないままmainへpushしていませんか？ Sphinx（npmパッケージ名は sphinx-understand）を入れると、mainへのgit pushはGitの段階で止まり、その差分についての質問に答えるまで先へ進みません。導入のコマンド、止まったときの出力、急ぎのときの sphinx yolo、入れる前に知っておく設定の範囲まで、使い捨ての環境で動かした記録とあわせてまとめます。

AIが書いた差分を、git pushの手前で説明させるフック

Sphinxの公式READMEには「You can outsource your thinking, but not your understanding.」とあります。考えることはAIに任せられても、理解までは任せられない。AIにコードを書かせる側が、自分の差分を分かっているかを、pushの一点で確かめる道具です。

流れはシンプルです。保護したブランチへpushすると、Gitのフックが処理を止めます。別に用意したレビュー用のモデルがコミットの差分を読んで質問を作り、正しく答えるとpushが続きます。公式READMEによると、質問を作るモデルはコードを書いた会話を見られず、こちらの答えもコーディングエージェントには渡りません。

質問の数もREADMEに書かれています。小さな変更なら最大1問、大きな変更でも既定の深さなら最大3問です。間違えると解説が出て、同じ考え方を問う別の場面で聞き直されます。

GitHubのリポジトリはparthh01さんのもので、ライセンスはMITです。2026年10月20日時点のnpmの最新版は0.1.11で、READMEにも、バージョン0.1はローカルのcommitとpushだけが対象だと書かれています。出たばかりなので、挙動はこの先も変わりそうです。

GitHub - parthh01/sphinx: You can outsource your thinking, but not your understanding. A hook for agent-assisted development that quizzes you on the changes before you push to prod.

You can outsource your thinking, but not your understanding. A hook for agent-assisted development that quizzes you on the changes before you push to prod. - parthh01/sphinx

github.com

sphinx-understandの導入は、審査モデルを選ぶところで一度止まる

動かしたのは使い捨てのコンテナ（node:22-bookworm、Node v22.23.3）で、審査モデルにつなぐキーやCLIは渡していません。そのため、この記事に出てくる質問の数や採点の話は、すべて公式READMEの説明です。

必要なのはNode 22.19以上とGitで、OSはmacOS、Linux、WSLに対応しています。インストールは次の1行です。120パッケージが入り、6.7秒で終わりました。

npm install -g sphinx-understand

つまずいたのは次の sphinx install でした。プリセットを付けずに sphinx install --yes --agents claude を実行すると、こう言われて止まります。

First installation needs an explicit reviewer choice for every change size

--yes を付けて対話を使わない初回は、変更の大きさごとにどの審査モデルを使うかを決める必要があります。--preset claude-economy、--preset codex-economy、--preset openrouter-value --allow-paid のどれかを付けるか、--small --medium --large の3つを個別に指定します。手元では、エージェント連携を外した次の形で通りました。Claude Codeと組み合わせるなら --agents claude にします。

sphinx install --yes --preset claude-economy --agents none --no-launch

続いて、守りたいリポジトリで sphinx init を実行します。.sphinxconfig（ポリシー）、.sphinxignore（送らないパス）、.sphinxcontext.md（プロジェクトの説明）の3つができ、.sphinxconfig の既定値は次のとおりでした。

.sphinxcontext.md はGitの管理外になるので、チームで共有するなら git add -f で足します。

保護ブランチへのgit pushは、Gitが回答を待ったまま止まる

Sphinxが止めるのは、保護したブランチへのpushです。既定は main と master で、.sphinxconfig の branches で対象を変えられます。

手元では sphinx init --yes --branches work で work ブランチを対象にし、コミットを1つ足してpushしました。Gitはその場で止まり、次の出力と、127.0.0.1のランダムなポートのURLを出しました。

Sphinx: understanding check needed for refs/heads/work (small change).
Git is waiting for your answers in the local Sphinx questionnaire. It will continue automatically after you pass.

質問はこのローカルのページに出て、合格すればpushは自動で続きます。60秒で待つのを打ち切ると「Git operation cancelled. Progress is saved.」と出て、pushは通っていませんでした。途中の状態は残り、sphinx pending に未完了のチェックとして並びます。

ここで1つ落とし穴があります。審査モデルにつながっていないと、質問が1問も作られません。手元の sphinx pending は「0/0 concepts complete · 0 tokens」のままで、pushは60秒待っても回答待ちのままでした。入れる前に、Claude CodeかCodexにサインインしているか、OpenRouterのキーがあるかを確かめておくと、この行き止まりを避けられます。

ブラウザを使わず端末で答える sphinx check もあります。対話のできないシェルから呼ぶと、--json を付けてエージェントから使うか、対話できる端末で実行するよう案内されました。

一度合格すれば、同じ変更をpushし直しても聞かれません。READMEによると合格は24時間有効で、コード、宛先、ポリシーのどれかが変わると聞き直されます。1回のチェックでGitを止めるのは最大25分です。

急ぎのときはsphinx yoloで関門を外せて、スキップは記録に残る

本番の障害対応のように、質問に答えている余裕がない場面もありますよね。そのときは sphinx yolo を1回打ちます。

Yolo mode is ON for /work/demo. Git operations skip the understanding check; each skip is logged.

この状態でpushすると、質問なしで通りました（1cbe054..80f72f9 work -> work）。もう一度 sphinx yolo を打てば元に戻ります。

READMEによると、sphinx yolo --reason "prod hotfix" のように理由を添えられ、設定はリポジトリ単位でもグローバルでも持てます。両方あるときはリポジトリ側が優先です。外した記録は、ヘルプの説明では sphinx status で見られます。

切り替え式なので、戻し忘れるとそのリポジトリのpushは素通りし続けます。急ぎの用が済んだら、同じコマンドでOFFに戻すところまでを1セットにしておくのがおすすめです。

入れる前に知っておく、core.hooksPathとコードの送信先

sphinx install は、ユーザー全体のGit設定を書き換えます。手元では core.hooksPath が /root/.config/sphinx/hooks/global に変わり、「Existing hooks are chained.」と表示されました。既存のフックはつないで呼ぶ、という意味です。マシン上のリポジトリ全体に関わる設定なので、すでに core.hooksPath でフックを運用しているなら、git config --global core.hooksPath の値を控えてから入れると安心です。外すときは sphinx uninstall を使います。

もう1つは、コードがマシンの外に出ることです。READMEによると、審査モデルの提供元は、コミットした変更、こちらの回答、.sphinxcontext.md の内容を受け取ります。.sphinxignore で外したファイルは送られず、.env や秘密鍵、認証情報のファイルは自動で除外されます。社外に出せないコードを扱うリポジトリでは、提供元をどこにするかが、入れるかどうかの分かれ目です。

料金の扱いもREADMEにあります。Claude CodeとCodexの経路はサインイン中のプランに課金され、SphinxはAPIキーを環境から外すと書かれています。普段からClaude Codeを使っているなら、--preset claude-economy で新しくキーを用意せずに始められます。

READMEは限界も自分で書いています。チェックは手元で外せますし、Web上のマージ、CI、デプロイは対象外です。そのうえで「practice, not a security gate」、つまり練習であってセキュリティの関門ではない、と言い切っています。私はこの書き方のおかげで、何を期待して入れればいいかが分かりやすくなっていると感じました。

自分のリポジトリでは、まずmainへのpushだけをSphinxに守らせる

Sphinxが問うのは、コードを誰が書いたかより、pushする人がその差分を説明できるかです。AIにコードの大半を書かせるほど、この問いは書かせた側に返ってきます。

最初の一手は小さくて足ります。既定のmainとmasterのまま、1つのリポジトリで sphinx init を実行し、Claude Codeのプランにつないで、次のpushで何を聞かれるかを見てみてください。答えに詰まった問いがあれば、そこが差分のうち、AIに任せたまま読んでいなかった場所だと私は考えています。