ADR管理システム

自社と受託案件のアーキテクチャ決定記録（ADR）を一か所に集め、AI エージェントが作業中に MCP 経由で検索・登録し、人が管理画面で承認する自社システム。自然言語検索、版履歴と置換の管理、再評価条件の点検、検索と評価器の品質測定までを扱います。要件の整理から実装、運用までを自社で行い、運用で分かった事実をもとに決定を重ねています。

作った理由と体制

「なぜこの技術を選んだのか」がリポジトリのコメントやチャットに散っていて辿れず、AI エージェントとの協業では過去の決定を参照しないまま矛盾した実装が生まれる、という問題が出発点です。実装に入る前に関連する決定を検索し、決めたその場で登録する流れを、エージェントが使うツールとして用意しました。

エージェントに必ず守らせたいことは指示文に書くのではなく、サーバー側の構造で強制する方針を先に決めました。指示文に必須と書いた手順をエージェントが省略する事例を、別のエージェントの評価で実測していたためです。

安全装置

承認は人だけが行います。エージェントが登録した決定は「提案中」で止まり、承認・失効・置換の適用は管理画面の操作に限ります。エージェントが承認済みの状態を指定すると拒否し、次に取るべき手順を応答で返します。この制限は当初はなく、8 月下旬の承認がすべてエージェント経路で行われていたことを版履歴から実測して追加しました。

変更は取り消せる形で残します。すべての変更で変更前の内容・操作の経路・時刻を版として保存し、置換関係を持つ記録は削除できず、番号は再利用しません。版履歴から過去の時点の決定の集合を再構成できるため、あるコミットの時点で有効だった決定を後から辿れます。

品質の検査は止めずに促します。エージェントからの登録・更新のたびにルールによる検査と LLM による評価を行い、所見を応答に同梱して修正を促します。所見が残っていても承認はでき、所見を誤検知として却下できるのは人だけです。評価に失敗しても登録は妨げません。

検索と参照の範囲はクライアントの境界で閉じます。呼び出し側の案件から見て同じクライアントの案件と自社の案件だけを対象にし、他のクライアントの決定がエージェントの文脈や納品物に混ざらないようにしました。

テストと計測を持ちます。自動テストは変更のたびに実行してから反映し、静的解析と依存の脆弱性検査はプッシュのたびに CI で実行します。検索の品質は正解つきの質問で、評価器の品質は正解つきの本文で、いずれも週次で測定して月次の報告に載せ、基準を下回ったときに見直す条件を決定に書いています。

何を作らなかったか

決定の正はサーバーのデータベースだけに置き、リポジトリへのファイル保存や署名つきの写しの配布は採りませんでした。写しの検証と鍵の管理という運用が増える一方で、得られる効果のうち PR 上での可視化は第三者の PR レビューが現在の体制になく、必要だった「コミット時点の決定を引く」ことは版履歴からの再構成で足りたためです。

品質所見がゼロでなければ承認できない厳格な関門は設けていません。誤検知の割合が実測されておらず、誤検知 1 件で承認が止まると記録漏れの側に倒れるためです。人による承認は評価器の精度に依存しない別の関門として機能します。同じ理由で、エージェント自身に誤検知を却下する権限も与えていません。

検索は埋め込みベクトルによる自然言語検索とキーワード検索を併用していますが、両者を統合するハイブリッド検索や検索時のクエリ拡張は見送りました。測定した再現率に対して改善の余地が小さく、残る取り逃がしは語彙の一致がない型で統合しても救えないためです。代わりに、登録時に生成している表記ゆれの別名を索引に含めるだけにしました。

0 件になった検索を自動で取り逃がしとして記録することもしていません。別の失敗の型を混ぜると見直し条件を誤って発火させるためで、検索時に事実だけを診断として保存し、判定は人が行います。

今の状態

本番で運用中で、自社の案件と受託案件の決定を案件ごとの連番で記録しています。承認待ちの一覧、品質所見と検索の取り逃がしを見るレビュー用の画面、週次の測定と月次の報告が回っており、再評価条件を持つ決定は点検の結果を記録して次の決定につなげています。この案件ページの原稿の型や図の扱いも、同じ仕組みで決めて記録しています。