はじめに
最近、Claude Code（ターミナルで動くAIコーディングアシスタント）用のプラグインを自作しました。「Formal Agent Contracts」というプラグインで、AIにコードを書かせるときに仕様のモレや矛盾を事前に見つけてくれるツールです。
「これ、本当に効果あるの？」と思い、ちゃんと実験してみました。結果は予想以上に良かったので、共有します。
どんなプラグイン？
一言でいうと、AIにコードを書かせる前に、ルールを数学的に整理するツールです。
たとえば「銀行口座の送金機能を作って」とAIに頼むとき、普通はそのまま自然言語で指示を出しますよね。でも実は自然言語の指示って曖昧なところが多くて、AIが「良かれと思って」判断してしまう部分があるんです。
このプラグインを使うと、まず「残高は0未満にならない」「送金元と送金先は別の口座であること」といったルールを形式言語（VDM-SL）で整理してから、コードを書かせます。
「形式言語」と聞くと難しそうですが、実際の操作は日本語でAIと会話するだけ。裏側でAIが形式言語に変換してくれます。
どうやって効果を検証したか
実験の設計
同じお題を、プラグインなし（A群）とプラグインあり（B群）でそれぞれ解かせて、できたコードの品質を比較しました。
- A群（プラグインなし）: Claude Codeに普通に指示して開発
- B群（プラグインあり）: Claude Code + Formal Agent Contractsで開発
お題は難易度別に3つ用意しました。
| お題 | 難易度 | どんなシステム？ |
|---|---|---|
| 銀行口座 | やさしい | 口座開設・入金・出金・送金 |
| 図書館 | ふつう | 貸出・返却・延長・在庫管理（3つの担当AIが連携） |
| オークション | むずかしい | 入札・落札・支払い・キャンセル（時間制限や同時アクセスあり） |
それぞれ5回ずつ試して、合計30回の試行データを集めました。
何を測ったか
コードの品質を4つの観点で点数化しました。
- バグの見つけやすさ（M1）: わざと仕込んだ「ひっかけポイント」をいくつ防げたか
- 仕様のカバー率（M2）: ビジネスルールをコードにどれだけ反映できたか
- 仕様の明確さ（M4）: ルールが「何となく」ではなく、明文化されているか
- テストの質（M6）: 書かれたテストがどれだけ的確にエッジケースを押さえているか
結果
全体スコア
| 評価項目 | A群（なし） | B群（あり） | 差 | 効果の大きさ |
|---|---|---|---|---|
| バグの見つけやすさ | 52.0% | 63.9% | +11.8 | 小さい |
| 仕様のカバー率 | 39.1% | 81.9% | +42.8 | 大きい |
| 仕様の明確さ | 8.9% | 100.0% | +91.1 | 大きい |
| テストの質 | 66.7% | 87.0% | +20.3 | 大きい |
**4項目中3項目で「大きな効果」**が確認できました。
ポイント①：仕様のカバー率が倍以上に
プラグインなしだと約39%しかカバーできなかったビジネスルールが、プラグインありだと約82%まで上がりました。
なぜこうなるかというと、形式言語で仕様を書く過程で「あ、このケースどうするんだっけ？」と自動的にモレに気づくからです。自然言語だけだと「まあ普通こうでしょ」とスルーしてしまうところを、形式言語では曖昧なままにできないのです。
ポイント②：難しい課題ほど効果が大きい
これが一番面白い発見でした。
| 難易度 | 仕様カバー率の差 | テスト品質の差 |
|---|---|---|
| やさしい（銀行口座） | +40.0 | +13.5 |
| ふつう（図書館） | +62.2 | +17.5 |
| むずかしい（オークション） | +26.2 | +30.0 |
簡単なお題だと、プラグインなしでもそこそこ良いコードが出てきます。でも複雑になればなるほど、プラグインの威力が発揮される。
考えてみれば当然で、簡単なシステムなら人間（やAI）の直感でもカバーできますが、「時間制限付きのオークションで、同時に入札が来たらどうする？」みたいな複雑なケースは、何かしらの仕組みがないと見落とします。
ポイント③：一番むずかしい課題での差が顕著
オークションシステム（むずかしい）の結果を見ると、差は歴然です。
プラグインなしでは、以下のようなケースがほぼ毎回見落とされていました。
- 延長が何回まで可能かの上限
- 同時に入札が来たときの優先順位
- 支払いがタイムアウトしたときの処理
- キャンセル後に再出品できるかどうか
プラグインありでは、仕様を定義する段階でこれらが自然と洗い出され、コードにも反映されていました。
注意点（公平のために）
もちろん、この実験には限界もあります。
- 同じAIが両方を担当している: 人間の開発者ではなく、AIが両方のコードを書いています。人間が使った場合の効果は、また別途検証が必要です。
- お題は3つだけ: 実務のプロジェクトはもっと複雑で長期的。今回の結果がそのまま当てはまるとは限りません。
- スコアリングは自動: キーワードマッチングによるヒューリスティックな採点なので、人間のコードレビューほど正確ではありません。
とはいえ、30回の試行で一貫して効果が出ているのは、それなりに信頼できる結果だと思います。
まとめ
「AIにコードを書かせるとき、事前にルールを形式的に整理しておくと品質が上がる」
当たり前のことかもしれませんが、それを数字で確認できたのが今回の収穫です。
特に「複雑な課題ほど効果が大きい」という結果は、実務で使うことを考えると心強いです。簡単なスクリプトならともかく、本番で動くシステムは大抵それなりに複雑ですから。
プラグインはGitHubで公開しています。Claude Codeを使っている方は、ぜひ試してみてください。
/plugin marketplace add kotaroyamame/formal-agent-contracts
詳しい評価レポートはこちら：
https://iid.systems/formal-agent-contracts/evaluation/