AIコーディングエージェントに「今はファイルを触るな」と教える — Statewrightのステートマシン式ガードレール

Claude Codeに「このバグを直して」と頼んだら、関係ないファイルまで書き換えていた。Cursorに機能追加を依頼したら、既存のテストが全部壊れていた。

AIコーディングエージェントの問題は、性能不足ではなく、やりすぎることだ。

計画中にいきなりファイルを編集する。テスト前にコードを書き換える。デバッグのつもりで本番設定をいじる。人間なら「今はその段階じゃない」と判断できることを、エージェントは最短経路で突っ走る。

Statewrightは、この問題をステートマシンで解決する。

フェーズごとに「使える道具」を制限する

考え方は単純だ。ソフトウェア開発には段階がある——計画、実装、テスト、レビュー。各段階で使えるツールを明示的に制限すれば、エージェントの暴走を防げる。

具体的にはこうだ。計画フェーズではファイル読み取りと検索だけを許可し、編集ツールはブロックする。実装フェーズに移ったら編集を解禁するが、テスト実行は許可しない。テストフェーズではテストコマンドのみ。レビューフェーズでは再び読み取り専用に戻る。

これをステートマシン（状態遷移図）として定義し、MCP（Model Context Protocol）サーバー経由でエージェントに接続する。Claude Code、Codex、Cursor、opencode——MCP対応のエージェントならどれでも使える。

重要なのは、この仕組みにLLMが一切関与しない点だ。Rustで書かれた決定論的なエンジンが、現在のフェーズに基づいてツール呼び出しを許可または拒否する。「AIにAIの監視をさせる」のではなく、コードで制約をかける。

SWE-benchで2/10から10/10へ

数字で語ると分かりやすい。

Statewrightの開発者Ben Cochran（元NVIDIA/AMD）が公開した実験結果によると、SWE-benchの5タスクサブセットで、ガードレールなしの場合に2/10だったスコアが、Statewright適用後は10/10に改善した。使用したのは13.8GBと19.9GBのローカルモデルで、大型のクラウドモデルではない。

この結果が示しているのは、「モデルの性能を上げる」のではなく「モデルの行動を制約する」ことで、品質が上がる場合があるということだ。これは直感に反するが、人間の開発チームでも同じことが起きる。ジュニアエンジニアに「コードレビュー前にmainにマージするな」と伝えるだけで、品質が上がるのと同じ理屈だ。

動かし方

セットアップは2通りある。

マネージドクラウド版（statewright.ai）を使えば、ブラウザ上のビジュアルエディタでワークフローを定義し、MCP gateway経由でエージェントに接続できる。ワークフローの保存と実行履歴はクラウドで管理される。

ローカルで完結させたい場合は、Docker ComposeでPocketBase、MCPゲートウェイ、ワークフローエディタを立ち上げる。エンジン本体（crates/engineとcrates/agent）はApache 2.0ライセンスで、ランタイム依存もない。

Claude Codeの場合、.claude/settings.jsonにMCPサーバーとしてStatewrightを登録するだけで導入できる。筆者が見た限り、セットアップは5分もかからない。

限界を正直に言えば

Hacker Newsで120以上のupvoteを集めたStatewrightだが、過信は禁物だ。

まず、ステートマシンの定義自体は人間が設計する必要がある。「計画→実装→テスト→レビュー」の流れが適切かどうか、各フェーズでどのツールを許可すべきかは、プロジェクトごとに異なる。テンプレートは用意されているが、複雑なワークフローでは試行錯誤が要る。

次に、SWE-benchでの改善結果は小規模な実験に基づいている。5タスクのサブセットと、大規模な実プロジェクトでは状況が違う可能性がある。

そして、Claude CodeやCursorの側も独自のガードレール機能を強化し続けている。Claude Codeのauto modeにはすでにツール許可の分類機能がある。プラットフォーム側の機能が充実すれば、外部ガードレールの必要性が薄れるかもしれない。

それでも、「ツール制限をステートマシンで宣言的に定義できる」というアプローチは、プラットフォームに依存しない汎用性がある。Claude CodeからCursorに乗り換えても、同じワークフロー定義を使い回せる点は、プラットフォーム内蔵のガードレールにはない強みだ。