【ITニュース解説】I built an MCP tool and the agent never called it. Here's what worked instead.

ソフトウェア開発の現場では、明文化された設計書やコーディング規約だけでなく、チームやプロジェクトごとに暗黙のルールが存在する。例えば、エラー処理の際に特定の関数を呼ぶ、ログ出力にはこのライブラリを使う、変数の名前はこのスタイルにする、テストには特定のフレームワークを使うといったものだ。これらはコードベースの中に統計的に現れる傾向であり、誰も明示的に書き記していなくても、長年の開発を通じて自然と形成される。

しかし、最近注目されているAIコーディングエージェント、つまりAIによるコード自動生成ツールは、これらの暗黙のルールを理解することが苦手である。AIはコードファイルを読んで学習するが、このような「書かれていない」ルールはファイルそのものには存在せず、コード全体のパターンや傾向の中に隠れているため、「見えない」のだ。その結果、AIエージェントが生成するコードは、プロジェクトの既存のルールやスタイルから逸脱してしまうことが頻繁に発生する。

これまでの対策として、開発者が手動でCLAUDE.mdやAGENTS.mdといったファイルにルールを書き出し、AIエージェントにそれを参照させる方法があった。しかし、一つのプロジェクトには数千もの暗黙のルールが存在する可能性があり、そのすべてを書き出し、常に最新の状態に保つのは困難で、現実的ではなかった。

このようなAIエージェントと暗黙のルールのギャップを自動的に埋めるべく、筆者はいくつかの方法を試みた。最初の2つの試みは失敗に終わったが、そこから重要な教訓が得られた。

まず一つ目の試みは、「エージェントにツールを与える」というものだった。これは、リポジトリ全体を解析してコーディング規約を自動的に抽出し、それをget_style_contextというツールとしてAIエージェントに提供するアイデアだ。エージェントはコードを編集する前にこのツールを呼び出し、ルールを読んでからコードを書くことが期待された。筆者はこのツールが利用可能な状態で実験を行ったが、驚くべきことに、エージェントはこのツールを一度も呼び出さなかった。エージェントは、自分が何か情報が不足しているというシグナルを受け取らない限り、自ら積極的に知識を探しに行かなかったのだ。ここから得られた大きな教訓は、「エージェントは自分が足りないことを知らない知識を自発的に探しに行かない」ということだった。

二つ目の試みは、「エージェントにルールを押し付ける」というアプローチだ。エージェントが自ら知識を探さないのであれば、こちらから強制的に与えれば良いと考えた。Claude CodeというAIエージェントツールには、PreToolUseフックという、コード編集や書き込みの直前に実行される機能があったため、筆者はこれを利用して、関連する規約をエージェントに強制的に注入した。しかし、これも期待通りの効果は得られなかった。注入されたルールがあっても、エージェントはルールがない場合と同じコードを生成してしまったのだ。後から考えれば理由は明白だった。PreToolUseフックが実行される時点では、エージェントはすでに編集内容を決定しており、そのコンテンツはすでに生成済みだった。このタイミングでルールが届いても、それはすでに下された決定に対する「アドバイス」に過ぎず、エージェントはそれを無視してしまったのである。

これまでの失敗から得られた教訓を踏まえ、筆者は三つ目のアプローチで成功を収めた。それは、「教えるのをやめ、チェックする」という方法だ。AIエージェントに事前に情報を提供しようとせず、まずは自由にコードを書かせる。そして、その書かれたコードを後からチェックし、もしルール違反があれば、それをエラーとしてエージェントに突き返すという仕組みである。

筆者が開発したOpenTupleというツールは、このアプローチを実現する。具体的には、エージェントによるコード編集や書き込みが完了した後に実行されるPostToolUseフックを利用する。このフック内で、OpenTupleは編集されたファイルを解析し、そのファイル内の関数と、そのディレクトリから抽出された規約を比較する。もしコードがルールを破っている場合、フックはエラーコードと共に終了し、そのエラーメッセージがAIエージェントに表示される。

例えば、あるプロジェクトのinternal/cliディレクトリでは、「fmt.Fprintfを呼び出す関数は必ずRenderも呼び出す」という暗黙のルールがあったとする。AIエージェントがこれを無視してfmt.Fprintfのみで出力するコードを書くと、OpenTupleは「PrintIndexSummaryはfmt.Fprintfを呼んでいるがRenderを呼んでいない」というエラーメッセージと、そのルール、そして根拠となるデータ（internal/cliの関数は100%このルールに従っていること）をエージェントに返す。エージェントはこのエラーを受け取ると、まるでテストが失敗したかのように、そのエラーを解決するために自律的にコードを修正する。誰かが明示的にテーマの使用を教えることなく、プロジェクトのコード自体がエージェントにルールを教えた形だ。

この方法が機能する理由は、エージェントがフックからのエラーを、単なる「アドバイス」ではなく、「解決しなければならないブロッカー」として扱うからである。これは、開発者が失敗したテストを修正するように、エージェントもエラーを修正しなければならない。試み2で失敗の原因となった「フックが編集後に実行される」というタイミングが、コードをチェックするという目的にはまさに最適だったのだ。

このアプローチにおける最も難しい部分は、誤検知（False Positive）を防ぎ、「サイレンス」を保つことだった。誤検知とは、実際には問題ないコードなのに、ツールが間違ってエラーとして報告してしまうことである。もしツールが不要なエラーばかりを報告するようでは、開発者はすぐにそのツールを「ノイズ」だと判断し、使用を停止してしまうだろう。

そこでOpenTupleでは、ルールを非常に厳格に定義している。まず、あるルールが存在するとみなされるのは、そのディレクトリ内の関数の少なくとも98%がそのルールに従っており、かつ10個以上の関数がそのルールに従っている場合のみだ。これにより、単なる偶然や少数の例外がルールとして強制されるのを防ぐ。次に、「ヘルパーペアリング」という、特定の関数（例：Lock）を呼んだら別の関数（例：Unlock）も呼ぶべき、というルールの場合、そのペアリングが単なる偶然の共通項ではなく、明確な意図を持った関係であるかを統計的に判断する。また、テストファイルとライブラリコードは異なるスコープを持つため、テストコードの規約がライブラリコードに強制されることはない。

これらの厳格なルール定義の結果、OpenTupleは非常に高い精度で動作する。筆者がfzf、GitHub CLI、Kubernetesといった大規模なオープンソースリポジトリでこのツールを実行したところ、ほとんど誤検知がなく、検出されたルール違反は本当に少数派の逸脱や、特定のテストコードにおけるアサーションライブラリの不統一など、意味のあるものばかりだった。これは、OpenTupleが既存のコードの規約を尊重し、不要な警告を出さない「静かな」ツールであることを示している。

OpenTupleは、go installコマンドを使って簡単にインストールできる。プロジェクトのルートディレクトリでopentuple init .と実行するだけで、リポジトリをインデックス化し、必要なフック設定をインストールする。その後は、Claude Codeのセッションを開始すれば、エージェントがコードを生成する際に自動的に規約チェックが働くようになる。Claude Codeを使用していない場合でも、--git-hookオプションを使うことで、ステージングされたファイルに対してpre-commitフックとして同じチェックを実行できる。

このツールはGo言語で書かれた単一のバイナリとして提供され、ローカル環境で動作するため、ネットワークリクエストは一切発生しない。Apache-2.0ライセンスで公開されており、Go、Python、JavaScript、TypeScript、Rust、Cといった複数のプログラミング言語に対応している。

OpenTupleはすでに実用的なツールとして機能しているが、いくつかの課題も残されている。例えば、.tsxファイル（ReactなどのJSX記法を含むTypeScriptファイル）は、TypeScriptの文法解析を通して扱われるため、JSXの部分が完全に解析しきれない場合がある。また、現在のところバイナリ形式での配布は行われていないため、使用するにはGo言語の開発環境がインストールされている必要がある。

さらに、筆者が得た行動に関するデータは小規模な実験によるものであり、実際のAIエージェントが書いたコードに対して、このツールがどれくらいの頻度で、そしてどれほど効果的に機能するのかについて、大規模かつ独立した評価が必要であると考えている。筆者はこの点について、コミュニティからの協力を求めている。OpenTupleのソースコードはGitHubで公開されており、自分のコードベースで試してみて、どのようなルール違反が検出され、それが適切だったかどうかをフィードバックすることが、今後のツール改善に大きく貢献することになるだろう。