Maguyvaブログ

ついてくるコンテキスト

Mon, 07 Sep 2026 00:00:00 GMT

Cursorのインデクサーは、Cursorの中では優秀です。タブ補完、インライン編集、チャット、そしてそのウィンドウの中のエージェントは、すでにCursorが開いているワークスペース用に運用しているプロジェクトインデックスの上に乗っています。Cursorがコードを書く唯一の場所で、そのインデックスがすでに正しいファイルを見つけてくれるなら、そこに留まってください。それが正直な「そこに留まる」ケースであり、このページの最初の一文になる資格があります。

この記事は、よくある一週間のもう半分についての話です。同じリポジトリがClaude Codeでも開かれ、Codex CLIから質問され、二台目のマシンでレビューされ、CIで動くエージェントから問い合わせられます。問題は「どちらのインデクサーが優れているか」ではありません。問題は、あるウィンドウでエージェントが信頼するマップが、次のウィンドウで信頼するマップと同じかどうかです。

Maguyvaが、そのついてくるマップです。リモートのMCPコードベース・コンテキストレイヤーです。エージェントは他のMCPツールを問い合わせるのと同じ方法でこれを問い合わせます。結果は行番号付きのランク付けされたパスとして返ってきます。Cursorはエディタのままです。動くのはコンテキストのほうです。

Cursorのインデクサーは何のためにあるのか

Cursorの組み込みインデックスは、モデルの生のコンテキストウィンドウに収まるものだけに頼るのではなく、エディタ内のチャット、エージェント、検索が関連コードを取得できるようにするために存在します。それはIDEにとって正しい設計です。このインデックスはCursorにネイティブなものです。MCPサーバーではなく、他のどのクライアントからもアクセスできません。

その仕組みは、本稿執筆時点のCursorの公開ドキュメントとCursor自身の説明によれば次のとおりです。主要な検索経路は、もはやクラウドのエンベディングインデックスではありません。Cursorのチームはコミュニティフォーラムで、現在のモデルは生きたツリーを自力でも十分に探索できるため、専用のセマンティック/エンベディングベースの検索はgrepベースの検索に取って代わられて縮小されていると述べています。その代わりにあるのがInstant Grepで、n-gram、転置リスト、ブルームフィルタから構築されたローカル検索インデックスであり、メモリマップされたルックアップテーブルに保持されるため、問い合わせはサーバーではなく開発者自身のマシン上で解決されます。

インデックス自体は、リポジトリ自身の.git/cursor/ディレクトリの中に、特定のgitコミットに固定されて存在します。そのコミット以降の変更は再スキャンを引き起こすのではなく、その上に層として積み重なり、ローカルの状態が構築時の対象から大きく乖離したときにだけインデックスは再構築されます。.gitの中にあるため、追跡もプッシュも一切されません──フォルダを削除すれば、インデックスは消えます。gitで追跡されているコンテンツだけが対象になるため.gitignoreは構造上尊重され、.cursorignoreは読み取り経路で強制されます。もうこの経路にはサーバー側のエンベディングのステップも、リモートのベクターデータベースもありません。以前のドキュメントは、チャンクの暗号化、Merkleツリーによる同期、チームメイト間でのインデックス再利用といった、クラウド支援型の設計を説明していましたが、Cursor自身のチームはその設計が縮小されつつあると述べているため、本稿はもうそれを現状として説明しません。

エディタ内で際立った強みは、CursorのExploreサブエージェントです。より高速なモデルを使い、自身のコンテキストウィンドウの中で複数の並列検索を発射し、関連する結果だけを返すことができるため、メインの会話が検索結果で膨れ上がることがありません。これはエディタ内部での本物の強みです。維持してください。

マルチルートワークスペースもサポートされています。開いている各フォルダのコンテキストがAgentに提供されます。worktreeのような一部のgit依存機能はマルチルート設定では無効になり、Cloud Agentsはマルチルートワークスペースをまったくサポートしません。

これらのどれも、Cursorを離れる理由にはなりません。それは、自分が生きている場所で優れているマップについての正確な記述です。

「ついてくる」が実際に意味すること

マップがついてくるのは、同じ質問が複数のクライアントから、開いて確認できる引用付きで、同じ種類の答えを返すときです。

Cursorで:「parseConfigはどこで定義されていて、誰が呼び出しているか?」
Claude Codeで、同じリポジトリに対して:同じ質問。
Codex CLIで、Cursorのウィンドウを一度も開いたことのないレビュー用マシン上で:同じ質問。
MCPを話すCIエージェントで:同じホスト型スナップショットに対して、同じ質問。

各サーフェスが自分専用のプライベートインデックスを構築するなら、あなたが持っているのは一つのマップではありません。互いにずれていく複数のキャッシュです。エディタのインデックスはディスク上のツリーについては最新かもしれません。CLIセッションは一日遅れているかもしれません。CIジョブは別のチェックアウトを見ているかもしれません。それでもエージェントは自信満々に聞こえ続けます。

Cursorのインデクサーはそれを解決するようにはできていません。エディタの中に生きているため、それが構築するコンテキストはそのエディタのためのものです。CLIやCIパイプライン、別のエディタも必要とする読者は、それらのサーフェス用に別のツールが必要です。それは範囲の事実であり、欠陥ではありません。Maguyvaがその別のツールです。

Cursorのインデクサーの公開された言語数は、本稿が使える資料には明記されていません。Maguyvaは279以上の言語とテキストベースの技術を公開しています。Cursorの価格もここには転載しません。彼らの価格ページを参照してください。Maguyvaは席数ではなくワークスペース単位で課金し、インデックス済みのフットプリントとワークスペースの規模に応じて$0、$19、$49、$149の公開プランがあります。

一つのホスト型マップ、すべてのMCPクライアント

MaguyvaはリモートのMCPサーバーです。GitHubを接続し、リポジトリを選ぶと、クラウドパイプラインがシンボルとグラフのエッジ、そしてランク付けされたマップを構築します。すでに使っているクライアントのMCP設定にAPIキーを追加します。Maguyvaには、Cursorを含む24の文書化されたMCPクライアント向けのセットアップガイドがあり、標準的なMCP設定をサポートする他のMCP互換クライアントにも接続できます。

Cursorが作業場所であれば、Cursorセットアップページがエディタ固有の経路です。同じサーバーがClaude Code、VS Code、Windsurf、Codex CLIなどにも応答します。エディタを乗り換える必要はありません。すべてのエージェントに、検索、シンボル、依存関係分析、ファイル取得、リポジトリコンテキスト、決定論的なユーティリティワークフローにまたがる11の顧客向けMCPツールという、同じツールサーフェスを提供します。セマンティック、構造、グラフ、テキストの検索がランク付けされた結果に融合されます。

それがポータビリティの利点です。今朝Cursorで確認した引用は、今晩Codex CLIが返す引用と同じ形をしています。ファイルパスと行番号。開いてみてください。間違っていれば、それが見えます。正しければ、次の編集には着地する場所ができます。承認された主張は、幻覚編集が減ることであり、すべての編集が正しいという約束ではありません。

鮮度は公開されています。スナップショットにはタイムスタンプが付いているため、エージェントはどのバージョンのツリーを読んでいるかを知ることができます。再構築の頻度は、無料プランでは毎日、有料プランでは毎時です。正直な限界は、同期されていないローカルの作業です。作業ツリーにしか存在しない編集は、まだホスト型マップに入っていません。この限界はどのクライアントから問い合わせても同じであり、それこそがポイントです。クライアント間のずれは、もはや二つ目の隠れた限界ではありません。

ドキュメントは、どのクライアントにも当てはまる有効化ループを示しています。すでに知っているリポジトリをインデックスし、クライアントを接続し、確認できる質問を一つ尋ねる。Cursorで一度それをやってください。実際にレビューの日に使うCLIからもう一度やってください。両方の答えが同じハンドラーを引用していれば、マップはついてきたことになります。

二つのマップが並び立つ方法

両方を使ってください。比較ページ的な意味での代替関係ではありません。

ディスク上のプロジェクトのために、Cursorのインデクサーを有効にしたままにしてください。Explore、Instant Grep、そしてエディタ内のエージェントにそれを使わせてください。このループはネイティブで高速です。
Cursorに、MaguyvaをMCPサーバーとして追加し、同じセッションからホスト型のワークスペースマップにも問い合わせられるようにしてください。CursorはMaguyvaの文書化されたクライアントです。片方のインデックスを選んでもう片方を消す、という話ではありません。
リポジトリに触れるClaude Code、Codex CLI、その他どのMCPクライアントにも、同じMaguyvaサーバーを追加してください。一つのAPIキーの形。一つのワークスペース。
CIエージェントがMCP互換であれば、同じサーバーを指させてください。ノートパソコンが読んだのと同じタイムスタンプ付きスナップショットを読むことになります。

エディタのインデックスは、「今このウィンドウのディスク上に何があるか」に対する最良のツールであり続けます。ホスト型マップは、「今日それに触れるすべてのエージェントにとって、このワークスペースがどう見えるか」に対する最良のツールです。この二つの文は競合しません。

ワークスペースのクォータは価格ページで公開されています。リポジトリ数、インデックス済み行数、ユーザー数を、ワークスペース単位で課金します。エージェントと人間は同じユーザー数を共有します。すでに評価できるリポジトリで無料で始めてください。引用がツリーとの接触を生き延びてから、ワークスペースを引き上げてください。

このページが主張しないこと

Cursorのインデクサーが弱い、不完全だ、あるいはエディタを乗り換える理由だ、とは主張しません。本稿の最初の一文はその逆です。

MaguyvaがInstant GrepやExploreサブエージェントを置き換える、とは主張しません。それらはCursorの機能です。Cursorの中に留まります。

どちらの製品についても、言語数、レイテンシの数値、トークン節約量を捏造しません。分からない数値は公開されないままにします。

プッシュされていないローカルの作業がホスト型マップに入っているふりはしません。タイムスタンプ付きスナップショットがその限界を可視化します。それを取り除くわけではありません。

テストはありふれています。すでに知っているリポジトリをインデックスしてください。確認できる質問を、まずCursorで、次に二つ目のMCPクライアントで尋ねてください。ついてくるコンテキストとは、両方の場所で同じ引用が得られることです。

// same map, wherever you opened it.

マップが先、レビューは後

Mon, 07 Sep 2026 00:00:00 GMT

プルリクエストの両側には、二つの異なる仕事があります。エージェントが書く前には、これから変更しようとしているツリーのマップが必要です。エージェントがPRを開いた後は、何かがその変更をシステムの残りの部分と照らし合わせて読み、人間が行動に移せるコメントを残す必要があります。

これらの仕事は、どちらも「コードベースを理解すること」を含むため、遠くから見ると似ています。同じ製品ではありません。一方は「この変更はどこに着地すべきか」に答えます。もう一方は「行単位のリンターが見逃す、このdiffが何を壊したか」に答えます。この二つを混同すると、より悪い最初の草稿と、より騒がしいレビューが生まれます。

この記事は、共同ワークフローのガイドです。Maguyvaは、エージェントが最初に問い合わせるマップです。Greptileは、その後でPRにコメントするレビューエージェントです。このペアは構造的に補完的です。Maguyvaはプルリクエストをレビューしませんし、Greptileはエージェントがそれらを書くのに使ったコンテキストレイヤーを置き換えません。

この分業が役立つ理由

訓練事前知識といくつかの貼り付けられたファイルから出発するコーディングエージェントは、もっともらしいパスを捏造して編集します。それが間違ったファイルの失敗であり、検索の問題です。Maguyvaはリモートのmcpコードベース・コンテキストレイヤーです。セマンティック、構造(AST)、グラフ/依存関係、テキストの検索がランク付けされた結果に融合され、加えてシンボル検索とファイル取得もあります。根拠のある答えはpath/file.ext:lineとして返ってくるため、パッチが存在する前に見当違いを拒否できます。主張は控えめなままです。幻覚編集が減ること。モデルはそれでも推測できます。ただ最初のステップが、もう推測ではなくなるだけです。

GreptileはAIコードレビューエージェントです。彼ら自身の言葉によれば、コードベースの完全な理解をもって、すべてのプルリクエストを自動的にレビューし、それをシステム全体ではなくファイルを個別に確認する従来のリンターと対比させています。セットアップは、GitHubまたはGitLabアプリをインストールし、リポジトリを選択することです。あなたが運用すべきローカルインデックスはありません。ホスティングはGreptile Cloudで(要求に応じて提供されるレポートとともにSOC 2 Type II準拠を表明しています)、企業向けにセルフホストのオプションも提供しています。

彼ら自身の番号付きフローはこうです。接続し、すべての関数、クラス、依存関係の依存関係グラフを構築する。すべてのプルリクエストで、そのリポジトリ全体のグラフを使って変更を分析し、約三分で修正案付きのPRコメントとして結果を投稿する。各コメントは、チームがすでに使っているコーディングエージェントに問題を引き渡せる。彼らはまた、チームのコーディング標準を学び、騒がしい提案を減らすために、過去の人間によるPRコメントを時間をかけて読むとも述べています。彼らの学習システムは、適応するのに2〜3週間必要だと述べられています。

これはレビューであって、起草ではありません。Greptileの際立った点は、すでにPRに着地した変更に対する、リポジトリ全体のグラフコンテキストであり、その後、発見をClaude Code、Codex、Conductor、Cursor、あるいはDevinに送る閉じたループです。Maguyvaの際立った点は、その変更が書かれる前にエージェントが問い合わせた、ランク付けされたマップです。両方使ってください。どちらにも相手の仕事をさせないでください。

Maguyva–Greptile間のファーストパーティ製品統合は明言されていません。それも必要ありません。MaguyvaはMCPを通じてエージェントと話します。Greptileは自分たちのアプリを通じてGitHubやGitLabと話します。両者はプルリクエストで出会います。糊付けスクリプトも、一方を他方につなぐcronもありません。それぞれの製品がすでに自分の持ち場に立っているため、このペアはbash不要です。

これが何ではないか

これはGreptileを貶める記事ではありません。「レビュアーを乗り換えろ」という記事でもありません。Greptileは2024年3月5日、Y Combinator W24の企業としてHacker Newsでローンチし、そのスレッドは多くの人がこの製品に初めて出会った方法です。もしそれがあなたの出会い方なら、そのまま使い続けてください。このページは、そのループの欠けている前半部分です。Greptileが見るPRが、すでに正しいファイルを狙っているように、先にエージェントに根拠を持たせることです。

Greptileのマーケティング資料は、レビュー速度とバグ検出の主張を前面に出しています。それらを、独立して検証された数値ではなく、Greptile自身の主張として扱ってください。本稿はそれらを事実として繰り返しません。

言語カバレッジも同じ種類の誠実さです。Greptileは、列挙されたリストではなく、すべてのプログラミング言語をカバーするという枠組みでサポートを表現しており、正確な数は明記されていません。Maguyvaは279以上の言語とテキストベースの技術を公開しており、質問が技術的なものであるときは、サイト上で技術的な区分(パーサー支援のASTかテキストのみか)も公開しています。これらは異なる主張をする異なる製品です。混同しないでください。

Greptileの価格は、本稿が使える資料には明記されていません。有料プランは存在します。彼らの価格ページを参照してください。Maguyvaは席数ではなくワークスペース単位で課金します。プランは無料から始まります。ワークスペースの数値が必要なら、価格ページに公開された階層が載っています。

ワークフロー

名前の付いた三つの段階です。この順序で実行してください。このペアを初めて試すときは、どれも飛ばさないでください。

1. Maguyvaのコンテキスト

すでに知っているリポジトリを一つインデックスしてください。すでにコードを書いているMCPクライアントを接続してください──Claude Code、Cursor、Codex CLI、VS Code、Windsurf、あるいは他のMCP互換クライアント。Maguyvaには24の文書化されたMCPクライアント向けのセットアップガイドがあり、標準MCP設定をサポートする他のクライアントにも接続できます。

誰かが一行でも書く前に、評価できる質問をしてください。「セッションの有効期限はどこで処理されていて、何がそれを呼び出しているか?」は「認証を直して」よりも良い最初の一手です。引用を要求してください。file.ext:lineの結果を開いてください。シンボルをたどってください。今から触れようとしている依存関係を確認してください。

Maguyvaは、検索、シンボル、依存関係分析、ファイル取得、リポジトリコンテキスト、決定論的なユーティリティワークフローにまたがる11の顧客向けMCPツールを提供します。四つの検索モードがランク付けされた結果に融合されます。すでに名前を知っている場合、find_symbolは別のツールです。ドキュメントは最短経路を説明しています。無料で始め、すでに知っているリポジトリをインデックスし、クライアントを接続し、それから確認できる質問を尋ねる。

スナップショットにはタイムスタンプが付いているため、エージェントはどのバージョンのツリーを読んでいるかを判別できます。正直な限界は、同期されていないローカルの作業です。編集が作業ツリーにしか存在せず、プッシュされていない場合、ホスト型マップはまだそれを含んでいません。指示ファイル(CLAUDE.md、AGENTS.md)は、慣習と触れてはいけないもののために、依然としてここに居場所があります。それらは生きたマップではありません。振る舞いにはそれらを使い、事実にはMaguyvaを使ってください。

引用がリポジトリとの接触を生き延びる前に、エージェントにPRを開かせないでください。この関門こそが、この段階の意義のすべてです。

2. エージェントのPR

同じエージェントが今度は、あなたがすでに料金を払っているクライアントの中で変更を書きます。Maguyvaはエディタでもレビュアーでもありません。エージェントは依然としてdiffを生成します。あなたは依然として、すでにやっているようにGitHubやGitLabでプルリクエストを開きます。

違うべきなのは最初のファイルです。PRは、その振る舞いを実際に実装しているハンドラー、壊れることになる呼び出し元、そして変更が間違っていれば失敗するテストを名指しすべきです。第1段階が飛ばされていれば、第3段階は間違ったパッケージに着地した変更に、そのコメントを費やすことになります。Greptileはそれでも体系的な問題を見つけられます。それに加えて、幻覚のパスからも回復しなければならない必要はないはずです。

PRの範囲を絞ってください。根拠のある最初のファイルは、モジュールを書き直すライセンスではありません。この補完的なペアが機能するのは、エージェントがマップを使って一つの仕事をし、その後レビュアーに、範囲を限定したdiffで別の仕事をするよう頼んだときです。

3. Greptileのレビュー

GreptileはすでにGitHubまたはGitLabアプリを通じてリポジトリに接続されています。新しいプルリクエストでは、自ら構築したリポジトリ全体のグラフを使って変更を分析し、修正案付きのコメントとして結果を投稿します。彼ら自身の資料は、この処理を約三分としています。

コメントは、注意深いチームメイトを読むように読んでください。引用された場所を開き、その発見が本物かどうかを判断し、それから行動する。Greptileが「Fix with your Agent」を提供する場所では、ファイルパス、行番号、提案されたコードを含む問題を、Claude Code、Codex、Conductor、Cursor、あるいはDevinに送ります。「Fix All」はレビュー内のすべての問題を一度に送ります。彼らはまた、その引き渡しのためにGreptile MCPとClaude Codeプラグインも提供しています。Maguyvaはその名指しされた対象リストには入っていません。その不在は問題ではありません。Maguyvaはすでに第1段階で自分の仕事を終えています。PRを書いたコーディングエージェントこそが、修正ペイロードを受け取るべき対象です。

Greptileの学習システムがあなたのチームが実際に残すコメントに適応する最初の2〜3週間は、ノイズを覚悟してください。それは彼らが表明したスケジュールであって、このペアの欠陥ではありません。人間によるレビューはループの中に残ります。Greptileは自動化された最初のパスであり、マージボタンではありません。

Greptileのコメントが、エージェントが第1段階で一度も問い合わせなかったファイルを指している場合、それは有用なシグナルです。マップが呼び出し元を見逃したか、エージェントが引用を飛ばしたかのどちらかです。そのコメントに合わせて草稿を直してください。レビュアーを無効化しないでください。

この補完関係を誠実に保つ方法

Maguyvaが常に先。間違ったファイルのPRをレビューしても、それは依然として間違ったファイルのレビューです。
Greptileが常に後。よく引用された草稿でも、システム全体レベルでのdiffの通読は依然として必要です。
MaguyvaにPRコメントを投稿するよう求めないでください。それはしません。
エージェントがまだパスを選んでいる最中に、Greptileにその最初の検索レイヤーになるよう求めないでください。それは、彼らのGitHubやGitLabアプリが担うよう作られている仕事ではありません。
両者を「同期」するbashパイプラインを捏造しないでください。PRがインターフェースです。
両側を独立して検証してください。すでに知っているリポジトリをインデックスしてください。確認できる質問を尋ねてください。それから小さなPRを開き、Greptileが実際に何をコメントするかを読んでください。

名前を付けてしまえば、このループはありふれたものです。マップが先。エージェントのPR。レビューが後。それぞれの製品は、自分が得意なプルリクエストの側に留まります。

// map first. review second. in that order.

ローカルインデクサーなしで、大規模リポジトリのコンテキストをAIエージェントに与える

Fri, 14 Aug 2026 00:00:00 GMT

大規模なリポジトリはコンテキストウィンドウに収まりません。そして、本物のmonorepoにノートパソコンのインデクサーを向けたことがあるなら、そこにも心地よくは収まらないことを知っているはずです──メモリが跳ね上がり、最初のインデックス作成に一時間かかり、それでもあなたのエージェントは次のセッションの開始時に、どのファイルが重要かをまだ推測しています。

よくある答えは、エディタの隣でインデクサーを動かすことで、一台のマシンに心地よく収まるリポジトリであれば、それは良い答えです。あなたのmonorepoがすでにCursorで高速にインデックスされていて、マップが必要な場所がそこだけなら、この記事に付け加えることは何もありません──読み飛ばしてください。

この記事は別のケース、つまりエージェントが大規模リポジトリの問い合わせ可能なマップを必要としていて、それを手に入れるためにローカルインデクサーを動かしたくないときの話です。

ローカルインデクサーが間違ったツールになるとき

ローカルインデックスは、コードがそれを問い合わせるマシンの上に存在することを前提としており、本物のmonorepoの規模では、この前提は単一のエディタの中でさえ限界に近づきます。リポジトリは、ノートパソコンでずっと温めておきたい大きさを単純に超えています。あるパッケージで作業している間、影響範囲は三つ先のディレクトリにあり、200万行のツリーの最初のコールドインデックス作成は、二度経験したいことではありません──あなたのマシンでも、そのツリーを一度もクローンしたことのないCIランナーでも。あるいは、チームメイトが自分のマシンで同じインデックスを苦労して通過するのを待たずに、あなたと同じマップを問い合わせられるべきかもしれません。

これらのどれも、良いエディタのインデクサーを捨てる理由にはなりません。それは、どのエージェントもMCPで問い合わせられるホスト型マップも持つべき理由です。

そして規模の問題は、「貼り付けるにはファイルが多すぎる」よりも根深いものです。大きなツリーでは、興味深い質問はほとんど「このファイルを見せて」ではありません──どのファイルか、どのシンボルか、どの呼び出し元か、どのテストかです。src/を一覧表示して最初の三件の結果を読むことから始めるエージェントは、apps/apiにあるハンドラーとpackages/sdkにある生成されたクライアントを、平然と見逃すでしょう。必要なのは、ツリー全体から構築され、ランク付けされ、引用された検索です。

「大規模リポジトリのコンテキスト」が実際に意味すること

ファイルをプロンプトに流し込むことはコンテキストではありません──それはツリーのより小さく、より劣ったコピーにすぎません。あなたのエージェントが実際に必要としているのは、質問をして引用付きの答えを受け取ることです。このシンボルはどこで定義されていて誰が呼び出しているか、今変更しようとしているモジュールに何が依存しているか、どのテストファイルがこの振る舞いをカバーしているか、そしてツリーが前四半期ではなく今どう見えるか。

これらの答えは、他人のリポジトリについてのモデルの記憶ではなく、あなたのリポジトリから構築されたインデックスから来る必要があり、そのインデックスはエージェントのコンテキストウィンドウ以外のどこかに存在する必要があります。この問題については、あなたのノートパソコン以外のどこかにも存在すべきです。

指示ファイルがあなたのためにできないことがもう一つあります。CLAUDE.mdとAGENTS.mdは慣習と振る舞いのための正しい場所ですが、200万行のツリーの、生きていて、ランク付けされた、問い合わせ可能なマップではありません。振る舞いにはルールを、事実にはリポジトリインテリジェンスを使ってください。

クラウドでマップを構築し、どのクライアントからも問い合わせる

MaguyvaはリモートのMCPコードベース・コンテキストレイヤーです。GitHubを接続し、リポジトリを選べば、あとはクラウドパイプラインがツリーを解析し、シンボルとグラフのエッジを構築し、ランク付けされたマップを維持している間、その場を離れられます──ローカルインデクサーは決して不要です。

コードをプッシュすると、変更されたファイルは段階的に解析され、グラフとランキングのレイヤーはスケジュールに従って再構築されます。無料プランでは毎日、有料プランでは毎時です。すべてのスナップショットにはタイムスタンプが付いているため、あなたのエージェントはどのバージョンのツリーを読んでいるかを判別できます。ここでの正直な限界は、同期されていないローカルの作業です。あなたの作業ツリーにしか存在せず、一度もプッシュされていない編集は、まだホスト型マップに入っていません。

次に、すでに使っているクライアントのMCP設定にAPIキーを追加して接続します。24の文書化されたMCPクライアント向けのセットアップガイドがあり、標準設定をサポートする他のMCP互換クライアントも接続できます。Cursorが本拠地であれば、Cursorページがその経路をたどります。同じサーバーがClaude Code、VS Code、Windsurf、Codex CLIなどにも応答します。

エディタを乗り換える必要はありません。検索、シンボル、依存関係分析、ファイル取得、リポジトリコンテキストにまたがる11のMCPツールというツールサーフェスを、あなたのエージェントに与えます。279以上の言語とテキストベースの技術をカバーしており、何年も前から単一言語ではなくなったmonorepoでは、これは思う以上に重要です。

答えは行番号付きのファイルパスとして、根拠のある形で返ってきます。セマンティック、構造、グラフ、テキストの検索がランク付けされた結果に融合されるため、「parseConfigに何が依存しているか」のような質問に対して、grepのダンプでも単一のセマンティックな断片でもなく、実際に重要な数か所が返ってきます。

具体的なやり方

会社全体をインデックスすることから始めないでください。実際に機能する経路はこうです。

すでによく知っているリポジトリを一つ選んでください。手で評価できるパッケージのほうが、手元にある最大のツリーよりも価値があります。
無料で始めてください。リポジトリ3件、インデックス済み5万行、11ツールすべて、月間クエリ上限なし。代表的なリポジトリがそれより大きい場合、価格ページに、席数ではなくインデックス済みフットプリントによるワークスペース階層($0、$19、$49、$149)が掲載されています。
GitHubを接続し、最初のインデックス作成が終わるのを待ってください。ローカルでは何もコンパイルしていません。
MCPクライアントを接続してください──設定は数行です。Maguyvaはリモートのmcpサーバーなので、プラグインも拡張機能も、採用すべき二つ目のエディタもありません。
確認できる質問を一つしてください。「parseConfigに何が依存しているか?」あるいは「ログインセッションの有効期限はどこで処理されているか?」引用されたfile.ext:lineの結果を開き、目の前のツリーと照らし合わせてください。
引用がその照合を生き延びてから、初めてエージェントに編集させてください。

最初のリポジトリがうまく合っていて、あなたのツリーが大きいなら、インデックス済み行数と再構築の頻度に合わせてワークスペースを引き上げてください。人間とエージェントは同じユーザー数を共有します──Maguyvaは席数ではなくワークスペース単位で課金するため──ループに三体目のエージェントを加えても、あなたに追加コストはかかりません。

有効化テストは、ドキュメントがどの初回実行にも推奨するものと同じです。すでに知っているリポジトリをインデックスし、確認できる質問を尋ねる。大規模なリポジトリだからといってテストが変わるわけではありません。最初に選び間違えたファイルの代償が大きくなるだけです。

接続した後に注意すべきこと

三つのことに注意してください。鮮度:有料プランは毎時、無料プランは毎日再構築され、プッシュされていないローカルの作業はマップに入りません──それがあなたが受け入れるトレードオフです。範囲:アーカイブされたフォークすべてではなく、代表的なリポジトリの集合をインデックスしてください。無料枠は、その答えが保持する価値があるかどうかを見極めるために、意図的にそのくらいの規模に設定されています。そして検証:パスと行番号を引用できない大規模リポジトリのマップは、より遅い推測エンジンにすぎません。だから、パッチを出す前にエージェントに場所を示させてください。

それから、小規模なリポジトリで行うのと同じテストを実行してください。すでに知っているリポジトリをインデックスしてください。確認できる質問を尋ねてください。マップが本物なら、あなたのエージェントは冷えたツリーから出発するのをやめます。

// no laptop got hot building this map.

AIコーディングエージェントがファイルパスを幻覚する理由

Fri, 14 Aug 2026 00:00:00 GMT

その兆候は、間違った関数本体ではありません。存在しないファイル、あるいは存在してもその振る舞いを実装していないファイルに対する、自信満々の編集です。

あなたはセッション有効期限の修正を依頼しました。エージェントはsrc/auth/session.tsを開きました。そのパスはもっともらしい。そして間違ってもいます。本物のハンドラーはapps/api/src/middleware/expiry.tsにあり、二回のリファクタリング前に名前が変わりました。エージェントはあなたに嘘をついたわけではありません。訓練事前知識と、すでにコンテキストウィンドウにあったものを組み合わせて、パス形状の文字列を補完しただけです。

これは実際のリポジトリでよくある失敗パターンです。モデルはコードを書けます。ミスは、書く場所を間違えることにあります。

エージェントがパスを捏造する理由

コーディングエージェントは、ツールを持った次トークン予測モデルです。「セッション有効期限を直して」と言うと、何かを読んだりパッチしたりする前に、まずファイルを一つ名指ししなければなりません。まだ根拠のあるマップを持っていない場合、次のものからパスを構築します。

他のリポジトリで見た命名規則。src/auth/session.tsはよくある形です。
すでに会話にあるファイル。それは今重要なものではなく、先週貼り付けたものかもしれません。
たまたま実行したディレクトリ一覧。大きなツリーでは不完全です。
指示ファイル。CLAUDE.mdとAGENTS.mdはエージェントにどう振る舞うべきかを伝えます。それらはシンボルや呼び出し元、現在のパスの生きたインデックスではありません。

これらの出典のどれも、今日のこのリポジトリのマップではありません。モデルは、どんな空白でも埋めるのと同じ方法で、この空白を埋めます。確率の高い続きでです。その続きは、しばしば本物のパスのように見えます。ファイルが存在していて、正しいファイルの隣にあることもあります。先月マージされたブランチに存在していたこともあります。一度も存在しなかったこともあります。

エージェントが正しい文字列をそもそも検索していないなら、ここではgrepもあなたを救いません。エージェントはパスを推測し、そのパスが返したものを読み、それを編集しました。最初の誤ったステップはパスであり、パッチではありませんでした。

ファイルを読むことも、正しいファイルを見つけることと同じではありません。Claude Code、Cursor、Codex、そして似たようなツールは、あなたが指し示すものなら何でも開けます。問題は、編集する前に、正しいファイル、重要なシンボル、依存関係、テスト、そして影響範囲を確実に見つけられるかどうかです。マップのないファイルアクセスは、依然として推測から始まります。

間違ったファイルの編集は検索の問題である

捏造されたパスを、性格上の欠陥としてではなく、検索の見当違いとして扱ってください。

エージェントが編集を許可される前にpath/file.ext:lineを返さなければならないとしたら、二つのことが起きます。第一に、あなたはその引用を開いて、十秒でその作業を却下できます。第二に、エージェントは実際にツリーを知っている何かに問い合わせなければならなくなります。

それがコードベース・コンテキストレイヤーの仕事です。セマンティック検索だけでは十分ではありません。「セッション有効期限っぽく聞こえる」断片が、それでも廃止されたパッケージに着地することがあります。文字列を知っているときには正確なテキストも、名前を知っているときにはシンボル検索も、形を知っているときには構造検索も、呼び出し元と影響範囲が必要なときには依存関係グラフも必要です。

Maguyvaは、MCP互換のコーディングエージェント向けのそのレイヤーです。エディタではありません。Claude Code、Cursor、Codex CLI、VS Code、Windsurf、そして他のMCPクライアントは、それぞれいた場所に留まります。エージェントは、一行に触れる前にランク付けされたマップに問い合わせます。

その主張は意図的に控えめです。幻覚編集が減ること。Maguyvaはモデルから推測する能力を奪いません。デフォルトの最初のステップを、「もっともらしいパスを捏造する」ことから、「ランク付けされ引用された場所を要求する」ことへと変えるだけです。

根拠のある答えとはどんなものか

「セッション有効期限はどこで処理されているか」に対する有用な答えは、一つの段落ではありません。短い場所のリストです。

apps/api/src/middleware/expiry.ts:48 - ハンドラー
apps/web/src/lib/auth-client.ts:112 - 呼び出し元
apps/api/tests/expiry.test.ts:20 - 変更が間違っていれば失敗するテスト

あなたはこれらの行を開けます。間違っていれば、そこで止まります。正しければ、エージェントは編集してもかまいません。ポイントは検証であって、スローガンではありません。

Maguyvaは、検索、シンボル、依存関係分析、ファイル取得、リポジトリコンテキスト、決定論的なユーティリティワークフローにまたがる11の顧客向けMCPツールを提供します。四つの検索モード(セマンティック、構造、グラフ/依存関係、テキスト)がランク付けされた結果に融合され、シンボル検索は独立したMCPツール(find_symbol)です。根拠のある答えはファイルパスと行番号とともに返ってくるため、目の前のツリーと照らし合わせて評価できます。

ドキュメントは最短経路を説明しています。無料で始め、すでに知っているリポジトリをインデックスし、クライアントを接続し、それから確認できる質問を尋ねる。

最初の編集を変えるループ

新しいワークフローの信条は必要ありません。最初に書く前に、もう一つのステップが必要なだけです。

すでに評価できる質問をしてください。「ログインとセッション有効期限を扱うコードは何か」は「認証を直して」よりも優れています。
引用を要求してください。「認証モジュール」の要約ではなく、ファイルパスと行番号を。
引用されたファイルを開いてください。シンボルをたどってください。今から触れようとしている依存関係を確認してください。
そのときになって初めて、エージェントにパッチさせてください。

ステップ2が何も有用なものを返さない場合、エージェントにはパスを即興で作る資格がありません。もう一度検索するか、あなたが指し示します。この一つの関門こそが、幻覚編集の減少を生み出します。モデルは同じモデルです。変わったのはマップのほうです。

指示ファイルは依然として重要です。維持してください。慣習、レビュールール、触れてはいけないもののために使ってください。それらにインデックスであることを求めないでください。三つの重要なディレクトリを列挙したCLAUDE.mdは、パッケージ分割の翌週には古くなります。問い合わせ可能なマップは、リポジトリが更新されれば更新されます。

関連する失敗は、惜しいファイルです。振る舞いがauth-client.tsにあるのに、エージェントがauth.tsを開く。ソースの代わりに生成されたファイルにパッチを当てる。あるいは、名前が一致したという理由でpackages/legacyのコピーを編集する。引用は、そうしたミスを不可能にするわけではありません。diffが着地する前に、それらを見えるようにするだけです。

マップがあなたのために解決してくれないこと

何を得ているのかについて、冷静でいてください。根拠のあるマップは、すべての編集を正しくしてくれるわけではありません──あなたのエージェントは、まさに正しいファイルの中で、それでも悪いパッチを書くことがあります。あなたのコードベースが動的ディスパッチ、リフレクション、モンキーパッチに依存しているなら、一部のシンボル検索は、あなたが望むよりも薄い結果を返すでしょう。実行時の間接性が、どんな静的インデックスにもそうさせるからです。そして、もしあなたがパーセンテージを期待しているなら──「幻覚パスがX%減少」──ここではそれを見つけられません。あなた自身以外の誰も、あなたのリポジトリについてのその数字を正直に測定できないからです。

あなたが期待できるのは、もっと狭く、もっと役に立つものです。エージェントは、推測したパスで編集を始めることをやめます。その最初のステップが本物のマップに根拠を持つようになり、幻覚編集の減少はそこから生まれます。引用の後のすべて──diffを読むこと、パッチを判断すること──は、これまでずっとそうであったように、依然としてあなたの仕事です。

このテストはほとんど何も費やしません。すでに知っているリポジトリをインデックスし、確認できる質問を尋ねてください。以前に痛い目にあったパスから始めてください。引用が間違っていれば、すぐにそれが分かります。正しければ、あなたのエージェントの次の編集には、より良い着地場所ができます。

// it doesn't know the file. it knows how to find it.

コード検索をvoyage-4-largeへアップグレードした理由

Tue, 09 Jun 2026 00:00:00 GMT

この記事のベンチマーク数値は、公開時点(2026年6月)のRTEBリーダーボードを反映しています。リーダーボードは変動するものなので、この順位は永続的な事実ではなく、ある時点のスナップショットとして捉えてください。

セマンティック検索の質は、その土台にある埋め込みの質次第です。

エージェントがMaguyvaに「リトライはどこで処理しているか」と尋ねるとき、それは「retry」という単語をgrepしているわけではありません。求めているのは意味です ―― バックオフループ、サーキットブレーカー、不安定な呼び出しをラップしているもの。この問いに答えるのは、コードを空間上の1点に変換し、その近傍を見つけるベクトルモデルです。より良いモデルを選べば、プロダクト内のあらゆるセマンティッククエリが静かに鋭くなります。

そこで私たちは自分たちのモデルを変更しました。2026年6月時点で、Maguyvaのコード埋め込みは**voyage-4-large**上で動作しており、voyage-code-3を置き換えています。

ベンチマーク

この判断を、なんとなくの感覚で下したわけではありません。公開されているRetrieval Embedding Benchmark(RTEB)は、実際の検索タスクで埋め込みモデルをランク付けしており、そのCodeリーダーボードではvoyage-4-largeが**総合1位(90.86)**につけています ―― gemini-embedding-2-preview(90.26)を上回り、そして特筆すべきは、私たちがそれまで使っていたモデルであるvoyage-code-3(89.73、3位)をも上回っている点です。

絶対値としては小さな差です。しかしそれは、公開ベンチマークにおいて、私たちが気にかけているまさにそのタスク ―― 意味によってコードを検索すること ―― において、正しい方向への差です。

私たちが受け入れるトレードオフ:バイナリ量子化

ここが、たいていの「モデルをアップグレードしました」系の記事が省略する部分です。

Maguyvaはフル精度のベクトルを保存していません。私たちが保存しているのはバイナリ量子化された埋め込みです。2048次元のベクトルはそれぞれ2048ビットの署名へと圧縮されます ―― ベクトルあたり256バイトです。これらの署名はハミング距離で検索され、テナントごとにインデックス化・パーティション分割されています。

これは意図的なトレードオフです。バイナリ量子化は、劇的に小さいストレージと、別途ベクトルデータベースを運用する必要のない高速で安価な距離計算と引き換えに、いくらかの検索精度を犠牲にします。ワークスペースごとにリポジトリ全体をインデックス化するプロダクトにとっては、ベンチマークの最後の端数を絞り出すことよりも、この経済性の方が重要です。

voyage-4-largeは、ストレージ層の移行を強いることなく、この設計にぴたりと収まります。voyage-code-3と同じく2048次元の出力を生成するため、私たちのbit(2048)カラムとハミング検索の経路は変更する必要がありませんでした。モデルは良くなり、スキーマはそのままです。

コードはほんの始まりに過ぎなかった

Maguyvaはコードインテリジェンスのツールです。しかし私たち自身も最初の顧客であり、それを別のものにも向けています。コードと並んでリポジトリに存在するMarkdownです。アーキテクチャ上の意思決定記録、ランブック、契約書、財務・ポリシー文書 ―― そのすべてがGitでバージョン管理され、そのすべてが同じMCPサーバーの背後にあり、ソースコードだけでなく文書そのものに対するセマンティックインデックスが張られています。

だからこそ、voyage-4-largeの守備範囲の広さが重要なのです。同じRTEBファミリーのリーダーボード群において、これはfinance(金融)で1位、healthcare(医療)で1位、そして総合テキスト検索でも1位です ―― GoogleのGemini Embedding、CohereのEmbed v4、OpenAIのtext-embedding-3-largeを上回っています。(Voyageは RTEBの共同開発者でもあるため、私たちはこれを完全に中立な審判というより、強力な公開シグナルとして読んでいます ―― とはいえ、プライベートなホールドアウトセットの上で、あらゆる主要な商用モデルと直接比較されてはいます。)エージェントのために正しい関数を見つけ出すのと同じインデックスが、契約書の中の正しい条項や、ポリシーの中の正しい一文を見つけ出します ―― そしてそれらの領域において、voyage-4-largeは妥協案ではなく、トップランナーです。

なぜプレミアムな埋め込みにお金を払うのか

検索にはもっと安く済ませる方法があり、その多くは無料です。字句検索 ―― BM25やその類 ―― はキーワードにマッチし、ローカルで動作し、コストはゼロです。BGE、Nomic、embeddinggemmaのようなオープンソースの埋め込みモデルは、正真正銘まずまずなセマンティック検索を提供してくれますし、GPU1台分の費用で自前ホストすることもできます。Maguyvaもこの無料の側面を使っています ―― すべてのクエリは、テキスト検索、AST検索、グラフ検索、セマンティック検索を統合しています。私たちが手を抜かないのは、このセマンティックレイヤーです。

私たちは、無料モデルを自前ホストする代わりに、トークンあたりの課金でプレミアムな埋め込み ―― voyage-4-large ―― を利用しています。理由は2つあります。第一に、コードがbackoffやcircuit breakerと書いていて「retry」という単語を一度も使っていない場合、キーワード検索だけでは「リトライはどこで処理しているか」に答えられません ―― 意味こそが埋め込みの存在意義であり、私たちが扱うドメインにおいてオープンモデルはプレミアムモデルに後れを取っています。一般的なテキストでは数ポイント差、コード・契約書・金融のようなニッチな領域ではさらに差が開きます。第二に、私たちの経験では、最終的な答えの質は、応答する側のモデルよりも検索の質によって形作られます ―― 優れたエージェントであっても、誤ったコンテキストを渡されれば誤った答えを返しますし、渡されなかった文書を目にすることは決してありません。

つまりプレミアムな埋め込みは、インデックス化するリポジトリや文書が増えるたびにスケールする、トークンあたりの請求書です ―― そして私たちは、それを意図的に払っています。ユーザーが得る成果 ―― 正しい関数、あるいは正しい条項 ―― を考えれば、そのトレードオフには十分見合う価値があると私たちは考えています。

正直な部分

Voyage自身のドキュメントは、今もvoyage-code-3をコードに最適化されたモデルとして位置づけています。では、なぜ移行したのでしょうか?

私たちは、ベンダーのモデル表だけでなく、公開ベンチマークそのものを読んだからです。そしてそのベンチマークは、コード検索においてvoyage-4-largeをトップに置いていました。これは先を見据えた判断でした。より新しく、全般的により強力なモデルを選び、重要なタスクにおいて公開リーダーボードで検証する、という判断です。私たちがこの賭けに踏み切れるのは、その根拠が幅広いからです ―― voyage-4-largeはコードだけで勝っているのではなく、金融、医療、そして総合検索でも先頭に立っています。

静かな土台

私たちが公開しているすべてのツール ―― セマンティック検索、タスクコンテキストの収集、根拠に基づくQ&A ―― は、最終的には検索に行き着きます。検索エンジンが改善されれば、その先にいるエージェントはより良いエビデンスを手にし、誤った方向へ進む回数が減り、正しいコード ―― あるいは正しい条項、正しいポリシー ―― に自らの答えを根拠づけられるようになります。より鋭い埋め込みモデルは、派手な機能ではありません。それは、他のすべてを支える土台であり、私たちはたった今、それを引き上げました。あなたは気づかないでしょう。それこそが狙いです。

言語の再帰的自己改善:約280言語にわたるコードインテリジェンスの磨き上げ

Tue, 26 May 2026 00:00:00 GMT

この記事の数値は公開時点(2026年5月)のシステムを反映しています。最新の数値はチームページをご覧ください。

Maguyvaは、約280言語のソースコードからシンボル、参照、そして依存関係グラフを抽出します。言語ごとにカスタムのtree-sitterハンドラー ―― クエリ、ヒューリスティクス、エッジケース ―― が存在し、どのハンドラーもそれぞれ独自の形で微妙に間違っている可能性があります。メソッド呼び出しがreadとして出力される。関数が誤った包含スコープに帰属させられる。本来は存在しないはずの関係が生成される、といった具合です。

これを手作業で監査することはできません。どんなチームであっても、280種類の文法にまたがる抽出結果をすべて読んで、誤ったエッジを見つけ出すことはできません。だから興味深い問いは「私たちの抽出は正しいか」ではなく、「この規模で、すべてのループに人間を挟むことなく、どうやって間違いを見つけ出すか」なのです。私たちの答えは、言語エージェントが主導する品質ループと、判定者として振る舞うLLM、そして繰り返し学び直している1つのルール ―― グリーンであることと正しいことは同じではない ―― による、言語の再帰的自己改善です。

グリーンは正しさではない

どの言語にもフィクスチャ(テスト用固定データ)一式があり、リリースゲートは精度、構造的整合性、網羅性、品質、パフォーマンスという5つの次元でスコアを付けます。ある言語がGREENになるのは、そのフィクスチャ上でprecision(適合率)が0.95以上、recall(再現率)が0.99以上、F1が0.97以上、かつ統計的な信頼性のために期待エッジ数が20以上ある場合のみです。それを下回るとYELLOWまたはREDとなり、出荷されません。

このゲートは必要条件ではありますが、十分条件ではありません。フィクスチャは私たちが書いたフィクスチャに対して検証されるものです。つまり、私たちがすでに思いついたケースしか反映されていません。ハンドラーはフィクスチャ上では完璧でも、実際のコードにしか現れないパターン ―― マクロのイディオム、ジェネリック型の制約を持つメソッド、誰もフィクスチャを書かなかった言語機能 ―― をぐちゃぐちゃにしてしまうことがあります。GREENが意味するのは、フィクスチャが通ったということだけです。実際のリポジトリがきれいに抽出できることを意味するわけではありません。だからこのループは、フィクスチャを離れて野生のコードに目を向けなければならないのです。

内側のループ:抜き取り検査、判定、修正、証明

中核となるループは、一度に1言語ずつ実行されます:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

これが空回りせずに機能するのには、いくつかの理由があります。

判定者はAPI呼び出しではなく、エージェント自身です。 私たちが「LLM-as-judge」と言うとき、それは言語エージェント自身が、サンプリングされた各エッジを実際のソースコードと突き合わせて読み、固定の5カテゴリーからなるルーブリックで分類することを意味します。すなわち、そのエッジは正しいのか、偽陽性なのか、関係は正しいが型が間違っているのか、誤ったスコープに紐づいているのか、それとも誤ったメタデータを持っているのか、という分類です。このルーブリックがすべての鍵です。「エラー率23%」という数字は、それが本物の欠陥なのか、それとも判定者の数え間違いなのかがわからない限り、何の意味も持ちません。

1点だけ修正し、それを証明する。 各イテレーションは編集可能な資産をちょうど1つだけ変更し、固定のハーネスに対して再実行し、F1が改善し再分類の結果もよくなった場合にのみその変更を残します。そうでなければロールバックします。投機的な変更をまとめて行うことも、「よくなるはずだ」という思い込みもありません。変更はその価値を証明して初めて残るのであり、そうでなければ消えます。そして修正が定着すると、それはフィクスチャ一式に昇格します ―― これにより、修正したバグが静かに再発することは二度となくなります。この昇格のステップこそが、このループを単なる反復ではなく再帰的なものにしています。1回のパスごとに、次のパスが検証の基準とするオラクルそのものが強化されていくのです。

繰り返し学び直している教訓:メトリクスは過大報告する

ここに落とし穴があり、私たちはまさにそこへまっすぐ踏み込んでしまいました。副次的なコーパスメトリクス ―― 抽出されたターゲットに解決可能なシンボルがない頻度や、いくつのシンボルが「孤立」しているように見えるか、といった指標 ―― は、問題を大幅に過大報告します。それらのほとんどは、バグではなく*パラダイム上のアーティファクト(現れ方の癖)*にすぎません。

もっとも分かりやすい例がllvmです。かつて「シンボルなしソース」率が73%を示し、壊滅的だと烙印を押されました。しかし掘り下げてみると、実際の精度は**98.5%**でした。「欠落しているシンボル」のほとんどは、標準ライブラリやフレームワーク、リポジトリの外にあるコードへの、正当な外部参照だったのです。このメトリクスが測っていたのは、ハンドラーの欠陥ではなく、その言語自体の性質でした。Zig、COBOL、Odinのような言語は65〜70%の「孤立」率を示しますが、まったく正しく、COBOLに至っては実際のエラーはゼロでした。

もしこの数字に作業を主導させていたら、すでに正しいハンドラーを何週間もかけて「修正」し続け、静かに本物のバグを抱えている言語を無視していたことでしょう。結論は率直です。集計メトリクスは、よくてもおおまかなトリアージ用のシグナルにすぎません。本当の品質シグナルは、エッジ分類つきの抜き取り検査です ―― 実際のリポジトリにある実際のエッジを1つずつ見て判断すること。直感よりデータを優先すべきですが、それはどのデータが真実を語っているかがわかって初めて成り立つのです。

外側のループ:マラソンではなく艦隊で

280言語すべてを一度に1言語ずつ処理していては永遠に終わりません。そこで内側のループは、多数を並列に実行する外側のループの中に包み込まれています。

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

各エージェントは使い捨てのworktreeの中で作業するため、互いに干渉することはありません。オーケストレーターは、各エージェントの修正を1つずつ、フルマニフェストの回帰チェックを通した上で統合します。自分の言語には効果があっても、他の3言語を静かに壊してしまうような変更は取り込まれません。統合は何かをプッシュする前にゲートを通り、確認されます ―― 回帰ゲートが決めるのは何が安全かであり、何を出荷するかを決めるのは今も人間です。その後、プールは次の言語群へとローテーションし、同じプロセスがまた繰り返されます。

まだ不完全な部分

判定者は間違えることがあり、その間違い方には方向性があります。コンテキストが不足した状態で動いているエージェントは過大報告する傾向にあるのです。あるバッチでは8言語がエラー率5〜20%としてフラグ付けされましたが、調べてみると本物の言語固有バグだったのは1件だけで、残りはすべて、その言語固有のセマンティクスを判定者が見落としたことによる誤りでした(1行のソースが正当に複数のエッジを生成する、パラメータバインディングが代入としてモデル化される、識別子ごとに参照を持つ言語、など)。だからこそ私たちは2つのシードでサンプリングして相互チェックを行い、判定者とフィクスチャの間の不一致を、確定した判定としてではなくもっとも興味深いシグナルとして扱っています ―― ときには、間違っているのはフィクスチャの方だからです。

目標についても正直でありたいと思います。ゴールは正真正銘のゼロエラーであり、それ以上でも以下でもありません ―― しかし「ゼロ」はチェックボックスにチェックを入れて終わるものではなく、言語ごとに少しずつ磨き上げていく方向性です。常に、また別のイディオムを持つ別のリポジトリが存在するからです。

主張するのではなく、勝ち取る

Maguyvaがエージェントのために行うすべてのこと ―― シンボルを見つけること、依存関係をたどること、コードを引用しながら質問に答えること ―― は、その土台にある抽出が正しいという前提の上に成り立っています。280言語にわたって、「正しい」ということは主張できるものではなく、実際のコードに対して継続的に勝ち取るものでなければなりません。私たちがそれを勝ち取る方法がこのループです。自らのメトリクスを疑ってかかり、あらゆる変更を証明し、それぞれの修正を次の回帰に対する防御へと変えていく、自律的な抜き取り検査と修正のサイクル。華やかな仕事ではありません。しかしこれこそが、「あなたの言語に対応しています」と、本気でそう言い切るための土台となる仕事なのです。グリーンになるのは簡単です。正しさは、勝ち取るものです。

マルチモーダル・フュージョン検索:あらゆるクエリに最適な検索エンジンを選ぶ

Wed, 15 Apr 2026 00:00:00 GMT

過去の設計について：この2026年4月の記事は、当時のルーティング設計を説明するものであり、現在のデフォルト動作を説明するものではありません。以下の9月の訂正は、測定に関する主張のみを対象としています。現在のルーティング、プリセット、明示的なモダリティ制御については、仕組みをご覧ください。

検索クエリは、一枚岩ではありません。

「parseConfigはどこで定義されているか」は、正確なシンボル ―― 素早く得られる1つの正確な場所 ―― を求めています。「認証はどう動いているか」は意味を求めています ―― ある概念を説明する、関連コードの広がりです。「この関数を変更したら何が壊れるか」は依存関係グラフを求めています。「文字列ECONNREFUSEDを見つけて」はリテラルな一致を求めているのであって、気の利いたことは何もいりません。

Grepはリテラルな一致には優れており、一部の参照探しにも有用ですが、依存関係グラフではありませんし、意味を理解することもありません。埋め込み(embedding)は意味的な側面をカバーしますが、正確な文字列や影響分析には向いていないツールです。ほとんどのコード検索ツールは1つのエンジンを選び、あらゆるクエリをそのエンジンで処理します。Maguyvaはエンジンを固定しません。あなたがどんな種類の問いを立てたのかを見極め、その問いにふさわしい比率で4つの検索エンジンをブレンドします。

4つのモダリティ

内部には、コードを見つけるための4つの独立した方法があります:

semantic(意味検索) ―― Voyageのバイナリ埋め込みによるベクトル検索。意味でコードを見つける。
text(テキスト検索) ―― トライグラムマッチング。リテラル、エラー文字列、正確な識別子を見つける。
structural(構造検索) ―― ASTクエリ。定義、シグネチャ、言語構文を見つける。
graph(グラフ検索) ―― 依存関係グラフ。呼び出し元、呼び出し先、影響範囲を見つける。

それぞれが異なる種類の問いに強みを持っています。肝心なのは、目の前のクエリに対してそれぞれをどれだけ信頼するかを見極めることです。

意図分類

検索を実行する前に、軽量な分類器がクエリを6つの意図のいずれかに振り分け、確信度スコアを付けます。これはホットパス上で動作し、加わる遅延はわずか1〜2ミリ秒程度であるべきなので、意図的に軽量に作られています ―― 順序付きのヒューリスティクスで、最初に一致したものが採用されます:

def 、class 、func 、import …で始まる → find_definition(確信度0.95)
「who calls」「usages of」「references to」→ find_references(0.90)
「impact」「blast radius」「what depends on」→ impact_analysis(0.90)
引用符付きの"string"やtracebackのようなエラートークン → exact_match(0.85〜0.90)
CamelCaseやsnake_case形式の識別子 → find_definition(0.60〜0.80)
「how」「why」「explain」「architecture」→ understand_code(0.75)
何も一致しない → understand_code、低確信度(0.40)

それぞれの意図は、4つのモダリティにまたがる重みプロファイルを持っています。これが実際の数値です:

意図	semantic	text	structural(AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

つまり「parseConfigはどこで定義されているか」はASTに大きく傾きます(0.6)。「認証はどう動いているか」は意味ベクトルに傾きます(0.5)。「これに依存しているのは何か」はほぼグラフだけです(0.7)。「ECONNREFUSEDを見つけて」はほぼトライグラムだけで(0.9)、埋め込みモデルは完全にオフになります ―― 正確な文字列に対して、意味的類似度はまさに誤ったツールだからです。

高速経路と、統合された経路

分類器の確信度が高く(スコア0.85以上)、クエリが通常のものであれば、Maguyvaは統合(フュージョン)を完全にスキップし、単一の支配的なモダリティへ直接ルーティングします。「Xはどこで定義されているか」には4つの検索エンジンは不要で、今すぐASTインデックスが必要なだけです。この直接経路はfusion_strategy: "direct"として返されます。

あいまいなクエリはすべて統合を経由します。4つ(デフォルトのプリセットでは3つ)のモダリティが並列に実行され、それぞれが独自のランク付けされたリストを返し、私たちはそれらを結合します。

重み付き相互順位融合

性質の異なる検索エンジンを統合するのは、見た目以上に難しい作業です。コサイン類似度0.82と、トライグラムスコア137と、グラフ中心性0.004は同じスケール上にないため、単純に足し合わせることはできません。相互順位融合は、生のスコアを捨て、各エンジンが割り当てた順位だけを残すことで、この問題を回避します。あるモダリティからの結果の寄与度は次の通りです:

contribution = weight × 1 / (k + rank + 1)

ここでrankはそのモダリティのリストにおける順位、kは平滑化定数です。複数のエンジンが見つけた結果については、寄与度がモダリティをまたいで合算されます ―― 検索エンジン同士の一致は、自然と上位に浮かび上がります。デフォルトのプリセットではk = 40を、thoroughでは60を使用しています(quickはセマンティックのみで動作するため、そこでは統合は発生しません)。RRFのオリジナルの研究では、汎用検索においてk = 60に落ち着いていますが、私たちのデフォルトはやや鋭めに設定しており、これによりモダリティ間で上位に一致する結果にわずかに大きな重みを与えています ―― そしてこれを手動でチューニングすることはお勧めしません。

さらに、結果にはグラフ重要度ブーストが加わります。ハブ ―― コードベース全体が頼りにしている関数 ―― は、テキスト上の関連度が同じであっても、目立たない末端の関数より上位に来るべきです。そこで各寄与度に次を乗じます:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

中心性は、パイプラインが事前計算したPageRank/次数メトリクスから得られ、ブーストは1.5倍で頭打ちになります。これにより、人気のある関数が、より関連性の高い目立たない関数を完全に埋もれさせてしまうことはありません。最後に、vendor・build・archiveパス配下の結果を格下げし、ファイルごとに最良のチャンクへ重複排除します。

まだ不完全な部分

意図分類器は正規表現の集合であり、学習済みモデルではありません。よくあるクエリの形をヒューリスティックで処理し、曖昧なクエリは understand_code とセマンティック寄りの組み合わせにフォールバックします。この記事の以前の版では、検索結果ゼロの割合が約15%から5%未満に低下したことを、達成済みの改善として説明していました。実際には、2025年12月の提案に記載されていたのは推定の初期値と目標であり、裏付けとなるクエリ集合や測定記録は提示されていません。改善を達成したというその主張を撤回します。出典の根拠資料と訂正をご覧ください。分類器を学習済みモデルに置き換えていないのは、安価な現行版が高速で、想定するルーティングの役割には十分であり、自信を持って間違える分類器より、正直なフォールバックのほうがよいからです。重み自体も手作業で選んだ事前設定値であり、収集していないクリックデータから学習したものではありません。

ツールにではなく、問いに語らせる

エージェントは、grepと埋め込みとコールグラフのどれに手を伸ばすべきかを知っている必要はありません ―― ただ平易な言葉で問いを立て、正しい答えを得られればよいのです。マルチモーダル・フュージョンこそが、find_symbol、セマンティック検索、依存関係分析を1つのクエリ入口の裏側に置くことを可能にしています。システムが問いの形を読み取り、それにふさわしい検索エンジンを静かに組み立てます。埋め込みをスコアリングするモデルも重要ですが、それを使わないべきタイミングを知っていることも同じくらい重要です。クエリごとに正しいツールを選ぶこと自体が1つの品質であり、私たちはそれを呼び出し側に押し付けるのではなく、自分たちで引き受けたいと考えています。

// you bring the question. it brings the tools.

エージェントオブザーバビリティ:フック、Alloy、Grafana

Tue, 24 Mar 2026 00:00:00 GMT

エージェントシステムは、思いもよらない形で壊れます。

モデルが原因のこともあれば、ツールが原因のこともあります。MCPサーバー自体は正常なのに、エージェントが誤った専門エージェントを選んでしまったり、想定外のシェル作業にセッションの半分を費やしていたり、外からは順調に見えるループの中で静かにコストを溶かしていたりすることもあります。

その違いを見分けられないなら、あなたはエージェントシステムを運用しているのではなく、ただ推測しているだけです。

そこで私たちは、自分たちのワークフロー向けにオブザーバビリティスタックを構築しました。Claude Code、Codex、Claudeのフックイベント、Codexの通知イベント、ネイティブのOpenTelemetry、Grafana Alloy、そしてその先にあるGrafana Cloudです。

興味深いのは「ダッシュボードを作った」という点ではありません。興味深いのは、単一のフィードでは全体像がつかめなかったため、テレメトリを2つの異なるストリームに分割せざるを得なかったという点です。

問題:エージェントのテレメトリは断片化している

現代のコーディングエージェントは、すでにある程度のテレメトリを出力しています。それは助けにはなりますが、十分ではありません。

ネイティブのOTELは、次のような問いに答えるのは得意です:

いくつリクエストを送ったか?
セッションのコストはいくらだったか?
スパンやトレースはどこにあるか?
レイテンシは急増したか?

一方で、次のような問いに答えるのはかなり苦手です:

エージェントはどのMCPサーバーに依存していたか?
この失敗はBash、組み込みのファイルツール、それともMCP呼び出しのどれで起きたのか?
実際にどのスキルが発動したのか?
どのタイプのサブエージェントがディスパッチされたのか?
そのセッションは有益な作業をしていたのか、それとも空回りしていただけなのか?

この2つ目のカテゴリーの問いは、トレースよりもフックに近いところにあります。

しかし逆もまた真です。もっとも重要なパフォーマンスに関する問いのいくつかは、フックよりもトレースに近いところにあります。

実際にどこでレイテンシが積み上がったのか、どのスパンが遅かったのか、あるいはセッションがモデル呼び出しとツール実行のどちらに時間を費やしていたのかを知りたいなら、意味的なイベントに加えてトレースデータも必要になります。

最終的に行き着いたアーキテクチャ

私たちは2つのテレメトリ経路を並行して運用しています。

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

この分割は意図的なものです。

また、この構成は非対称でもあります。Claude Codeははるかに豊富なライフサイクルフックのインターフェースを提供してくれます。Codexはネイティブ OTEL に加えて通知(notify)のインターフェースを提供してくれるので、両方のランタイムが同じ制御機構を持っているかのように装うのではなく、情報量の少ないターン完了イベントを同じログスキーマへ正規化しています。

ネイティブOTELはベースラインとなるストリームを提供します。ランタイム自体からのログとトレース、そしてランタイムが実際にメトリクスを出力している場合はそのメトリクスです。

フックと通知イベントは意味的なレイヤーを提供します。PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、SubagentStop、SkillActivatedといったもの、そしてエージェントの挙動をデバッグする際に本当に必要となる分類済みメタデータです。ここではClaude Codeがより豊富なイベントストリームを提供し、Codexは情報量こそ少ないものの、有用な正規化済みストリームを提供します。

そもそもなぜフックが必要なのか

私たちのフックパイプラインは、イベントがLokiに到達する前にそれを拡充(エンリッチ)します。

単に「ツールが実行された」と記録するのではなく、イベントを次のようなフィールドに分類します:

tool_type: builtin、mcp、skill、agent、bash
mcp_server: どのMCPバックエンドが呼び出しを処理したか
bash_cli: シェルコマンドのファミリー
subagent_type: どの種類の専門エージェントがディスパッチされたか
agent_tool: ソースがClaude CodeかCodexか

つまり、運用上意味のある問いを立てられるようになります:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

これらは見せかけのフィールドではありません。「エージェントが遅く感じた」という感覚と、「エージェントは直近10分間、失敗率の高いシェル中心のgit操作に費やしていた」という事実との違いを生み出すものです。

実装の細部として、見た目ほど奇妙ではないものが1つあります。共有のLokiストリームは、イベントの発生元がCodexであってもservice_name="claude-code-hooks"というラベルを使い続けます。ランタイム間の本当の区別はagent_toolの側で行われます。

なぜAlloyが中間に位置するのか

この構成において、Grafana Alloyは単なるフォワーダーではありません。ポリシーの境界線です。

Claude CodeとCodexからのネイティブOTELストリームを、localhost:4318上のローカルAlloyプロキシに向け、Grafana Cloudへ転送する前にAlloyにペイロードを整理させています。

これが重要なのは、生のエージェントテレメトリには、分析には有用だがインデックス済みラベルとしては最悪な、高カーディナリティのフィールドが大量に含まれているからです:

session_id
prompt_id
トークン数
所要時間
ツールパラメータのblob

すべてをインデックスすると、ラベルの爆発的増加と、ろくでもない1日が待っています。

そのためAlloyには次の3つを担わせています:

低カーディナリティのラベルをごく少数だけインデックス化する。
ノイズが多いが有用なフィールドを構造化メタデータへ移す。
純粋なノイズは完全に破棄する。

重要な考え方はシンプルです。観測は多く、インデックスは少なく。

なぜフックストリームはAlloyを迂回するのか

フックストリームはすでにLoki向けに整形済みです。

send_event.pyがイベントをプッシュする時点で、どのフィールドをラベルとして扱い、どのフィールドを構造化されたJSON本文に含めるかはすでに決まっています。このストリームはAlloyをもう一度経由することなく、Grafana CloudのOTLPゲートウェイへ直接送られます。

つまり、このシステムには明確な役割分担があります:

Alloyは生のネイティブOTELストリームを飼いならします。
フックによる拡充は意味的なイベントをクエリ可能にします。

これにより、すべてを1本の経路に無理やり通そうとするよりも、アーキテクチャがシンプルに保たれます。

ダッシュボードが実際に示しているもの

下のスクリーンショットは、私たちのエージェントワークフローを支えるオブザーバビリティダッシュボードの1つです。これはベンチマークではなく、数値はあくまである時点の断面にすぎません。重要なのはデータの形です。アクティビティフィード、ツール呼び出し、失敗、プロンプト、そしてエージェント別・組み込みツール別・MCP利用状況別・シェルコマンド別・スキル別の内訳です。

有用なのは、このダッシュボードが他のエージェントテレメトリと同じGrafanaスタック上に存在している点です。ソースとなるエージェントやツールファミリーでフィルタリングでき、システムごとに別々のオブザーバビリティの物語を作ることなく、ランタイムをまたいで俯瞰できます。

私たちのエージェントワークフローを支えるライブダッシュボードの1つ。このスクリーンショットは、他のエージェントランタイムやシステムからのテレメトリも受け取っている共有Grafanaスタックの、ほんの一断面にすぎません。画像をクリックするとフル解像度版を表示します。

トレースが見た目以上に重要な理由

ログはどのカテゴリーの作業が行われたかを教えてくれます。トレースは、その作業が時間の経過とともにどう展開したかを教えてくれます。

この区別はエージェントシステムにおいて重要です。「遅い」という言葉だけでは、あまりに大雑把で役に立たないからです。

トレースを見れば、問題がどこから来ているのかがわかります:

モデルのレイテンシ
ツール実行時間
繰り返されるリトライ
特別にコストの高い1回のMCPインタラクション
個別に見れば無害に見える、小さな操作のロングテール

実際には、フックストリームとTempoのトレースを組み合わせて使っています。

フックログが答えるのは:何が起きたか?
トレースが答えるのは:時間はどこへ消えたか?

この組み合わせこそが、オブザーバビリティを単なるダッシュボードから「説明」へと変えるものです。

Codexの位置づけ

Codexは同じスタックの一部ですが、Claude Codeと同一というわけではありません。

Codexについては、次の2つを組み込んでいます:

CodexのネイティブOTELをAlloyへ
通知webhookをcodex_notify.pyへ。これはターン完了をフックイベントで使っているのと同じLokiスキーマへマッピングします

これにより、同一のログストリーム内でagent_tool="codex-cli"のような統一フィルタが使えるようになります。

正直に言うと注意点もあります。Codexの通知ペイロードは、統合の性質そのものが異なるため、現時点ではClaude Codeのフックペイロードよりも薄いものです。現在の私たちの構成では、Codexのターン完了は共通スキーマへ正規化できますが、ツールごとの詳細な抽出については、通知ブリッジよりもネイティブOTELストリームの方が依然として優れています。

だからといってこの記事を書かない理由にはなりません。むしろそれこそがこの記事の要点です。本物のオブザーバビリティシステムは、不完全なシグナルを組み合わせて作られるものなのです。

MCP経由のGrafanaがゲームを変える

より大きな変化は、Grafanaが人間がブラウザで訪れるだけの場所ではなくなったという点です。

このリポジトリでは、GrafanaもMCP経由で公開しています。つまり、人間がまずダッシュボードを手動で確認するのを待つことなく、エージェントが直接Loki、Prometheus、Tempoへクエリを投げられるということです。

これにより、オブザーバビリティはワークフローへの受動的な報告手段ではなく、能動的な入力へと変わります。

エージェントは、次のような問いを立てられます:

直近1時間で最も失敗の多かったツールファミリーはどれか?
どのMCPサーバーがセッションを支配していたか?
最近の変更はツールの失敗を減らしたのか、それとも同じミスをより多くのシェル中心の経路へ移しただけなのか?
もっともレイテンシが高い、あるいはリトライが繰り返されているトレースはどれか?

ここまでくれば、自己改善ループはすぐ目の前です。

ダッシュボードからフィードバックループへ

ここが私たちにとって最も興味深い部分です。

オブザーバビリティスタックがエージェントレイヤーからクエリ可能になった瞬間、テレメトリは受動的な報告手段であることをやめ、制御シグナルになります。

ループは次のような形になります:

エージェントの活動が、トレース、メトリクス、拡充されたフックログを生成する。
Grafanaがその証拠をLoki、Tempo、そしてメトリクスが存在する場合はPrometheusに保存する。
エージェントがGrafana MCP経由でその証拠にクエリを投げる。
システムが、悪いツールの組み合わせ、壊れやすいスキル、弱いルーティング、あるいは避けられるはずのミスを繰り返し生むシェル中心のワークフローを特定する。
エージェントやオペレーターが、プロンプト、エージェント設定、スキルの説明、ルーティングルール、ツールアクセスを調整する。
次のセッションが新しいテレメトリの形を生み出し、サイクルが繰り返される。

こうして「興味深いダッシュボード」から「測定可能な改善システム」へと移行していくのです。

目標は特定のツールカテゴリーを最大化することではありません。実際に行われている作業に対して、CLI、組み込みツール、MCP呼び出し、スキルの適切な組み合わせに落ち着くことです。

これによって何がわかるようになるか

両方のランタイムが同じGrafanaスタックに収まると、運用上の問いにはるかに速く答えられるようになります:

失敗は特定のツールファミリーに集中しているか?
より高レベルなツールがあるべき場面で、シェル中心のワークフローが避けられるはずのミスを生んでいないか?
どのMCPサーバーが作業負荷を担っているか?
意味のある進捗を生んでいないエージェントの活動に対価を払っていないか?
セッションが不健全なのは、モデルのせいか、ツールのせいか、それともオーケストレーション層のせいか?

これはマルチエージェントのワークフローにおいて特に有用です。「エージェントが忙しかった」という説明では、ほとんど何もわからないからです。

特定の専門エージェントが繰り返しディスパッチされ、高い失敗率を出し続けているなら、それはルーティングかプロンプト設計の問題です。

1つのMCPサーバーがすべての呼び出しを占めているなら、それは優れたアーキテクチャの証かもしれませんし、他のすべてが無駄な重荷になっているサインかもしれません。

コストが高止まりしたままツールの失敗が急増しているなら、それは品質の問題ではなく運用上の問題です。

より高レベルなツールがあるべき場面で、シェル作業が予測可能かつ避けられる形で失敗し続けているなら、それはプロダクトへのシグナルです。

特定のスキルが常に発動しているのに成果が改善しないなら、それはプロンプトかルーティングへのシグナルです。

本当の教訓

ここでのより深い教訓は、エージェントのオブザーバビリティにはランタイムテレメトリとワークフローテレメトリの両方が必要だということです。

ランタイムテレメトリは、システムが何をしたかを教えてくれます。

ワークフローテレメトリは、エージェント自身が何をしているつもりだったかを教えてくれます。

その両方が必要です。

トレースとカウンターだけを残していると、意味的なレイヤーを見逃します。フックイベントだけを残していると、レイテンシやスパン、そしてより広いランタイム全体の姿を見逃します。

そして両方を残していても、それをエージェントレイヤーへフィードバックしなければ、それは「適応」ではなく単なる「監視」でしかありません。

この組み合わせこそが、システムを運用できるだけ説明可能にし、改善できるだけ調整可能にするものです。

まだ不完全な部分

まだ粗削りな部分は残っています。

すべてのフックイベントに、欲しいだけの所要時間やトークンのデータが含まれているわけではない。
タイミングに関する最良のビューの一部は、フックログではなく依然としてTempoのトレースから得られる。
拡充されたイベントストリームにおいて、現時点のCodexはClaude Codeほど意味的に豊かではない。
ダッシュボードのスクリーンショットは、磨き上げられたマーケティング素材ではなく、実際の運用画面である。

最後の点は意図的なものです。エージェントシステムがまるで魔法のように自明であるかのように装うより、本物の計器パネルを見せる方を私たちは選びます。

これがMaguyvaにとって重要な理由

Maguyvaは、エージェントによりよいコードインテリジェンスを与えることを目的としています。しかし、エージェントが実際に有益な作業をこなし始めた瞬間、新たな要件が即座に浮かび上がります。それは、エージェントがどう振る舞っているかを可視化する必要がある、ということです。

検索の質、ルーティングの質、ツール選択、コンテキストの効率性は、すべて観測可能な問題になります。

だからこそ、これは書く価値があると私たちは考えています。未来のエージェントスタックは、プロンプトとツールだけでは成り立ちません。プロンプトとツール、そして全体が機能しているかどうかを教えてくれる計測レイヤーがあって初めて成り立つのです。

本気でエージェントワークフローを構築しているなら、オブザーバビリティはあってもなくてもいいインフラではありません。それはプロダクトの一部です。

ループを掘り起こす:変更はいかにして組織の記憶になるか

Tue, 03 Feb 2026 00:00:00 GMT

この記事の数値は公開時点(2026年2月)のシステムを反映しています。最新の数値はチームページをご覧ください。

どのエンジニアリングチームも同じ課題に直面します。変更は絶えず起こりますが、その変更の背後にある理由は消え去っていきます。半年後、誰かが「なぜパイプラインのステージにDuckDBを採用したのか?」と尋ねたとき、その答えはその判断を下した本人の頭の中にしか存在しません ―― しかもその人がまだ在籍していればの話です。

私たちは、このループを閉じるためのマイニングワークフローを構築しました。変更はgitのコミットとして流れ込み、私たちのマイニングパイプラインで処理され、構造化された変更履歴やアーキテクチャ上の意思決定記録になり、そしてCLIクエリを通じて私たちのAIエージェントへとフィードバックされます。結果として得られるのは、人間とAIの両方がアクセスできる組織の記憶です。

問題:意思決定は蒸発する

典型的なシナリオを考えてみましょう。ある開発者が次のようにコミットします:

feat(canonical): add DuckDB runtime for pipeline stages

このコミットは、重要なアーキテクチャ上の選択を表しています。チームは選択肢を評価し、トレードオフを検討し、特定の理由からDuckDBに落ち着きました。しかしそのコンテキストはすべて、次のような場所に存在しています:

Slackのスレッド(おそらく削除済み)
誰かの記憶(確実に薄れつつある)
コード中のコメント(運が良ければ、もしかしたら)

3か月後、新しいチームメンバーがこう尋ねます。「この新しいステージには、DuckDBとSQLiteのどちらを使うべきですか?」組織の記憶がなければ、彼らは車輪の再発明をするか、一貫性のない選択をすることになります。

ループ:コミットからコンテキストへ

私たちのマイニングワークフローは、git履歴をクエリ可能な知識へと変換します:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

ここでの重要な洞察は、変更履歴とアーキテクチャ上の意思決定の両方が、同じgit履歴から、統一されたパイプラインを通じて流れ出すということです。これにより、何かが見落とされることがなくなります。

マイニングの仕組み

ステップ1:インデックスを同期する

uv run orkestra mine sync

このコマンドはgit履歴をスキャンし、すべてのコミットのインデックスを構築します。各コミットから構造化されたシグナルを抽出します:

Conventional Commitsのタイプ(feat、fix、chore、docs)
スコープ(どのパッケージまたは領域か)
破壊的変更のマーカー
変更されたファイルと複雑度のメトリクス

ステップ2:カバレッジ状況を確認する

uv run orkestra mine status

現在の状況は次のようになっています:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637件のコミットを処理済み。うち476件がアーキテクチャ上の意思決定になり、6,799件が変更履歴のエントリになりました。すべてのコミットが分類済みです。

ステップ3:レビュー対象の候補を取得する

uv run orkestra mine candidates --limit 50 --full

これにより、まだ処理されていないコミットが、分類に必要な完全なコンテキストとともに表示されます:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

これらのシグナルは分類の指針になります。is_releasable_type: trueは、これが変更履歴に載るべきものであることを示唆しています。挿入行数の多さとインフラ関連ファイルの存在は、これがアーキテクチャ上の意思決定でもある可能性を示唆しています。

ステップ4:コミットを分類する

ここで2つの経路に分岐します。変更履歴のエントリと、アーキテクチャ上の意思決定です。

変更履歴のエントリの場合:

uv run orkestra mine classify abc123 --changelog added

これにより、コミットabc123が変更履歴の「Added」カテゴリーに載るべきものとして記録されます。

アーキテクチャ上の意思決定の場合:

まず、実際の意思決定IDを取得します:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

続いて、その意思決定IDを使って分類します:

uv run orkestra mine classify abc123 --decision DEC-PL-143

これにより、コミットが、作成または更新されることになる意思決定レコードに紐づけられます。

バッチ処理の場合(私たちが実際に行っている方法):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL形式なら、1回のパスで両方のドメインに対応できます:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

ステップ5:出力をレンダリングする

uv run orkestra registry changelog render --package <pkg>

これにより、台帳からパッケージごとのCHANGELOG.mdファイルが生成されます。変更履歴は派生成果物です ―― 削除しても、元の台帳から完璧に再生成されます。

意思決定レコードの構造

抽出された意思決定は、豊富なメタデータを持つYAMLファイルになります:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

すべての意思決定は、元となったコミットへリンクバックしています。すべての意思決定は、どのファイルに影響するかを明記しています。意思決定同士の関係も明示的です。

CLIとの統合:組織の記憶へのクエリ

ここでループが閉じます。エージェントはCLIを通じて意思決定にクエリを投げられます:

# Search by topic
uv run orkestra registry decisions search --query "retry"

リトライロジック、エラーハンドリング、リカバリーパターンに関する意思決定を返します。

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

コンテキスト、根拠、影響を含む完全な意思決定レコードを返します。

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

最近どのようなアーキテクチャ上の選択が行われたかを表示します。

エージェントはこれをどう使うか

私たちのオーケストレーターのベースライン指示には、次のような内容が含まれています:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

エージェントがDuckDBに関連する何かの実装を依頼されたとき、まず次のように確認できます:

uv run orkestra registry decisions search --query "DuckDB"

そしてDEC-PL-142を発見し、次のことを学びます:

なぜDuckDBを選んだのか(コンテキスト)
正しい使い方(agent_guidance)
どのファイルを見ればよいか(files)
どんな関連する意思決定が存在するか(related)

エージェントは車輪の再発明をしません。確立されたパターンの上に積み上げていきます。

3つの質問テスト

すべてのコミットが意思決定レコードに値するわけではありません。私たちは3つの質問テストでふるいにかけています:

判断が難しかったか? 大きな分析、トレードオフの検討、あるいは議論を要したか?
変更のコストは高いか? この決定を覆すには大幅な作り直しが必要か?
システム全体に影響するか? 複数のパッケージに影響を与えるか、他が従うことになるパターンを確立するか?

これらの質問のうち少なくとも1つに「はい」と答えられるコミットは、意思決定抽出の候補になります。私たちの典型的な割合は、100コミットあたり1〜4件の意思決定(約1〜4%)です。

変更履歴のエントリについては、基準はもっと低めです。ユーザーに見える変更(機能、修正、改善)であれば何でも記録されます。内部的な雑務、ドキュメント更新、リファクタリングは通常スキップされます。私たちの典型的な割合は、100コミットあたり30〜50件の変更履歴エントリです。

データストレージ:追記専用台帳

マイニングシステムは、マルチエージェントによる運用で競合が起きないよう、追記専用のJSONL台帳を使用します:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

.gitattributesにおけるmerge=unionを伴うJSONL形式のおかげで、複数のエージェントがマージコンフリクトを起こすことなく同時にコミットを分類できます。各行は独立しています。

バリデーションゲート

マイニングセッションを行う前には、必ずバリデーションを実行します:

uv run orkestra mine validate --quick

これは次を確認します:

SHA形式の妥当性
意思決定IDの形式準拠
同一SHAに対する重複エントリがないこと
参照されている意思決定が実際に存在すること

分類後、変更をコミットする前にもう一度バリデーションを行います。

これが重要な理由

私たちが構築したフィードバックループは、いくつかの問題を解決します:

新しいチームメンバーにとって: 「なぜXをしたのか?」と尋ねる代わりに、意思決定レジストリを検索できます。コンテキストは保存されています。

AIエージェントにとって: 真空の中で動作しているわけではありません。提案を行う前に、組織的な知識にクエリを投げられます。新しいパイプラインステージの追加を依頼されたとき、DuckDBのパターンを発見し、それに従うことができます。

アーキテクチャの一貫性にとって: 意思決定は明示的で検索可能です。誰かが既存の意思決定と矛盾するアプローチを提案したとき、システムはその衝突を表面化できます。

変更履歴の生成にとって: リリースノートは土壇場でのドタバタ作業ではなくなります。開発中に継続的に行われる分類の副産物になるのです。

オンボーディングにとって: 新しいエージェントは、コードベースの完全なコンテキストを引き継ぎます。コードを見るだけでなく、それを形作った意思決定も見ることになります。

現在の状態

現時点で:

15,637件のコミットがパイプラインで処理済み
476件のアーキテクチャ上の意思決定が抽出・文書化済み
6,799件の変更履歴エントリが記録済み
両ドメインにわたる100%のカバレッジ

開始以来のすべてのコミットが分類済みです。組織の記憶は完全であり、クエリ可能です。

はじめに

同様の仕組みを実装したい場合:

まずConventional Commitsから始める。 マイニングパイプラインは、コミットに構造化されたプレフィックス(feat:、fix:、chore:)がある場合に最もよく機能します。
ドメインを定義する。 私たちはpipeline、agent-design、observability、data-modelingのようなドメインを使っています。これらは意思決定を領域別に整理します。
分類する習慣を作る。 マイニングは、チームが定期的にコミットを分類することで機能します。LLMの支援によるバッチ処理はスケールを助けます。
意思決定をクエリ可能にする。 エージェントがCLI経由で意思決定を検索できるようになると、価値は複利的に積み上がります。出力を機械が消費しやすい形に構造化しましょう。
ループを閉じる。 意思決定は今後の作業に影響を与えるべきです。エージェントへの指示やコードレビューのチェックリストに、意思決定への参照を含めましょう。

目標は完璧なドキュメントを作ることではありません。変更の背後にある理由を、今日も半年後も、人間とAIの双方がアクセスできるようにすることです。変更が組織の記憶になるとき、チームは再発明するのではなく、確立されたパターンの上に積み上げていけるようになります。

マイニングワークフローは、私たちのオーケストレーションエンジンの一部であり、具体的にはオーケストレーションパッケージ内のコンテキストエンジンモジュールに含まれています。

スキルマイニング:3,500の候補から466の能力へ

Tue, 27 Jan 2026 00:00:00 GMT

この記事の数値は公開時点(2026年1月)のシステムを反映しています。最新の数値はチームページをご覧ください。

3,500スキル問題

エージェントオーケストレーションシステムの構築を始めたとき、私たちは興味深い課題に直面しました。AIエコシステム全体に、何千もの潜在的なスキルが散らばっているのです。GitHubのリポジトリ、ベンダーのドキュメント、コミュニティのプロジェクト、社内のパターン ―― スキルはあらゆる場所に存在します。しかしどれが重要なのか? どれが機能するのか? そして、エージェントが実際に使える一貫性のあるスキルライブラリを、どうやって維持すればいいのか?

私たちの答えは、体系的なマイニングと取り込みのループです。

今日の数字

Anthropicが2025年10月16日にAgent Skillsをローンチしてから3か月あまり。この記事が公開された2026年1月27日時点での、私たちの立ち位置は次の通りです:

指標	数
識別された候補	3,500以上
採用したスキル	466
ベンダースキル	373
社内スキル	93
アクティブなベンダー	25以上
スキルあたりの平均トークン数	2,834
参照されているツール	89
ユニークなタグ	635

私たちは3,500件を超えるスキル候補をレビューしてきました。そして466個を採用しました。採用率にして13% ―― この選別の厳しさは意図的なものです。

ナレッジティアシステム

すべてのスキルが平等に作られているわけではありません。私たちはそれらを、それぞれ異なる適用範囲を表す5つのナレッジレイヤー(K0〜K4)に整理しています:

K0:基盤(普遍的)

すべてのエージェントが持つべきスキルです。これらは、どこでも通用する「優れた思考者」としての能力を表しています。

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0のスキルは、どんなプロジェクト、どんなドメイン、どんなスタックにも持ち運べます。普遍的な認知パターンを体現しているからです。

K1:アイデンティティ(専門分野)

「優れたエンジニア」や「優れたリサーチャー」としての、ある専門分野内のプロジェクト全体に当てはまるスキルです。

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2:ドメイン(専門知識)

「優れたデータベース専門家」や「優れたセキュリティエンジニア」としての、ある分野内で持ち運べるスキルです。

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3:スタック(技術)

「優れたSupabaseユーザー」や「優れたCloudflare開発者」としての、特定の技術スタックに特化したスキルです。

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4:プロジェクト(組織)

私たちの組織とワークフローに固有のスキルです。

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

マイニングループ

フェーズ1:発見

スキルはあらゆる場所からやってきます:

ベンダーリポジトリ:AWS、Anthropic、Cloudflare、Supabase、そしてコミュニティの貢献者たちが、スキル集を公開しています。私たちは25以上のベンダーのルートを追跡しています。

コミュニティプロジェクト:GitHubには、Claude Codeのテンプレート、エージェントパターン、ワークフロー定義があふれています。

社内パターン:私たちのチームが問題を解決していく中で、パターンが浮かび上がってきます。それらはスキルとして形式化されます。

ドキュメントマイニング:技術ドキュメントには、手順、チェックリスト、意思決定ツリーといった暗黙のスキルが含まれていることがよくあります。

発見は継続的なプロセスです。正式な評価の前に候補を追跡するため、スキルのバックログを使っています。

フェーズ2:評価

すべての候補は、同じルーブリックを通過します:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

5つのプロダクト基準すべてに合格しなければなりません。これが、候補の87%が却下される理由です。

その上で、すべての候補は別途トラストレビューを通過します。私たちは、公式のベンダーリポジトリ、よく知られたコミュニティメンテナー、そして素性のわからないGitHubリポジトリを、同等の信頼できる情報源としては扱いません。

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

信頼できるベンダーは、より軽めの来歴レビューで済みますが、無条件で通過するわけではありません。信頼できない、あるいは未知の情報源は、より深い手動監査を受けます。同梱されたスクリプトは、読み込み、スコープを確認し、安全であると分類されるまでは実行しません。

ギャップ分析:採用する前に、私たちのレジストリを検索します:

uv run orkestra skills search "<capability>"

すでに持っているなら、必要ありません。近いものを持っているなら、採用ではなく統合するかもしれません。

深さと標準のスコアリング:候補がエージェントスキルモデルをどれだけ十分に活用しているかもスコアリングします。単独のSKILL.mdでも有用なことはありますが、agentskills.ioが推奨する形で指示を参照・スクリプト・アセットから分離しているような、より深いスキルの方が価値が高くなります。

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHubのスター数は信頼性スコアを多少押し上げることはありますが、浅い、あるいは安全でないスキルを救うことは決してありません。あいまいなSKILL.mdが1つだけで不透明なスクリプトを含む高スター数のリポジトリは、正確な説明、厳選されたreferences/、そしてスキルの能力を実際に活かすアトミックなヘルパーを持つ、より小さなリポジトリよりも低いスコアになります。

構造分析:スキルの品質を確認します:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

候補にスクリプトが含まれている場合、レビューはより厳格になります。優れたスキルは有用であるだけでは足りません。読みやすく、境界が明確で、エージェントに渡しても安全でなければなりません。この安全性フィルタだけで、他の点では興味深い候補のかなりの割合が失格になります。

フェーズ3:取り込み

スキルが評価を通過すると、レジストリに加わります。しかしスキルがそのままの形で採用されることは決してありません。私たちのシステムに合わせて修正されます。

採用時の修正内容:

メタデータの正規化:すべてのスキルに私たちのフロントマタースキーマを適用する
Kティアの割り当て:スキルを適切なナレッジレイヤーへ配置する
タグの拡充:発見しやすくするためタグを追加する
ツール宣言:許可されたツールを明示的に宣言する
セクションの整合:コンテンツを私たちのテンプレートに合わせて再構成する

取り込み後の典型的なスキルYAMLです:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

フェーズ4:スコープの割り当て

スキルはスコープ ―― どのエージェントがどのスキルを読み込むかを決めるカテゴリー ―― に割り当てられます:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

エージェントは自分のスコープを宣言し、スキルは自動的に割り当てられます:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

フェーズ5:実体化

本番環境では、スキルはYAMLのまま存在しているわけではありません。Claude Codeが読み込めるSKILL.mdファイルへとレンダリングされます:

uv run orkestra sync

このコマンドは:

すべてのスキルYAML定義を読み込む
Jinjaテンプレートを通じてそれらをレンダリングする
SKILL.mdファイルを.claude/skills/へ書き出す
Kティア別(foundations/、identities/、domains/、stacks/、project/)に整理する

最終的な出力構造です:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

休眠スコープパターン

私たちの最も強力なパターンの1つが、「採用済みだが読み込まれていない」スキルです。私たちはこれを休眠スコープと呼んでいます。

k-dense-scientificリポジトリ由来の科学計算スキルを考えてみましょう。私たちは、バイオインフォマティクス、化学、量子コンピューティング、臨床情報学をカバーする120以上のスキルを採用しています。しかし私たちのエージェントのほとんどは、分子ドッキングや遺伝子発現解析を必要としません。

120個すべてのスキルをすべてのエージェントに読み込ませてコンテキストウィンドウを肥大化させる代わりに、私たちは次を行います:

特定のスコープ(例:bioinformatics)付きでスキルを採用する
登録はされているが読み込まれていない、休眠状態に保つ
エージェントがそのスコープを宣言したときにのみ有効化する

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

このパターンによって、レジストリには466個のスキルを持ちながら、典型的なエージェントはそのうち関連する40〜60個だけを読み込む、ということが可能になっています。

スキルの種類

スキルには3つの認知パターンがあります:

ワークフロー

順序立った手続き的なステップです。「1. Xをする、2. 次にYをする、3. 最後にZをする」

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

規律

振る舞いのガードレールです。「常にXせよ」「決してYするな」「Zを優先せよ」

type: discipline
# Examples: test-first-discipline, evidence-based-completion

チェックリスト

検証基準です。「Xを確認せよ」「Yを検証せよ」「Zをチェックせよ」

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

品質ゲート

すべてのスキルは、出荷前にバリデーションを通過しなければなりません:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

説明文は、Claude Codeがいつ提案すればよいかを判断できるよう、トリガーフレーズ(「Use when…」「When you need…」)を含む50〜400文字でなければなりません。

私たちは継続的に検証しています:

uv run orkestra validate --show-warnings

ベンダーエコシステム

私たちの373個のベンダースキルは、次から来ています:

プロバイダー	スキル数	ドメイン
AWS Agent	19	クラウドサービス
Anthropic	12	ドキュメント生成
Cloudflare	8	エッジコンピューティング
Supabase	5	データベース
k-dense	100+	科学計算
silvainfm	4	データサイエンス
Java Developer Kit	45+	Spring/Java
Vercel	1	ブラウザ自動化

各ベンダーのルートはmetadata.yamlで宣言されます:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

orkestra syncが実行されると、ベンダースキルはそれぞれのプロバイダー名前空間つきで.claude/skills/vendor/へシンボリックリンクされます。

私たちが学んだこと

選別の厳しさは報われる。 有用そうに見えるものすべてを採用したくなる誘惑はあります。しかしどのスキルにもトークンのコストがかかります。スキルあたり平均2,834トークンともなれば、肥大化はすぐに痛手になります。13%という採用率が、エージェントを軽量に保っています。

構造が発見を可能にする。 Kティアシステムは単なる整理ではなく、持ち運びやすさに関わるものです。K0のスキルはどこでも再利用できます。K4のスキルは意図的にプロジェクト固有です。この明確さが、人間とエージェントの双方が必要なものを見つける助けになります。

休眠スコープはスケールする。 すべてを読み込ませることなく、何百ものスキルを採用できます。スコープによって、個々のエージェントのコンテキストウィンドウを扱いやすいサイズに保ちながら、包括的なレジストリを構築できます。

採用時の修正は不可欠である。 生のままのベンダースキルが、自分たちのシステムに合うことはめったにありません。メタデータの追加、ティアの割り当て、タグの拡充といった取り込みプロセスが、外部のスキルを社内で機能させます。

マイニングは継続的である。 3,500という数字は増え続けています。新しいベンダーリポジトリが現れます。コミュニティのパターンが生まれます。社内のワークフローが固まっていきます。このループが止まることはありません。

次にやること

私たちはいくつかの改善に取り組んでいます:

自動ギャップ検出:未採用のスキルによってよくあるエージェントの失敗が解決できそうな場合にアラートを出す
スキルの非推奨化ワークフロー:置き換えられた、あるいは使われていないスキルを引退させるための正式なプロセス
スキル間の依存関係:スキルの前提条件を明示的に宣言する
利用状況の分析:エージェントが実際に呼び出しているスキルと、単に読み込んでいるだけのスキルを追跡する

スキルマイニングループはインフラです。華やかではありません。しかしこれこそが、41体のエージェントが466個の能力とともに、コンテキストの上限内に収まりながら一貫して機能する理由です。

これが、3,500が466になった経緯です。3,000を無視したのではなく、体系的に評価し、機能するものだけを採用した結果です。

スキルシステムの実際の動きを見てみたいですか? uv run orkestra skills listをチェックして、私たちの現在のレジストリを探索してみてください。

プログレッシブディスクロージャー:エージェントシステムを覗き込むCLIという窓

Tue, 20 Jan 2026 00:00:00 GMT

この記事の数値は公開時点(2026年1月)のシステムを反映しています。最新の数値はチームページをご覧ください。

エージェントシステムは、設計上不透明です。意思決定を行い、ツールを呼び出し、数十体の専門エージェントにまたがる作業を調整します。しかし何かがうまくいかないとき ―― あるいは単に今何が起きているのかを理解したいとき ―― どこを見ればよいのでしょうか?

その答えがプログレッシブディスクロージャーです。必要なときに、必要な分だけ複雑さを見せる、階層化されたインターフェースです。

不透明性という問題

現代的なエージェントオーケストレーションシステムには、次のようなものが存在するかもしれません:

それぞれ異なる能力を持つ、40体以上の専門エージェント
内部の自動化からベンダー連携までにまたがる、700個以上のスキル
振る舞いを形作る、470件以上のアーキテクチャ上の意思決定
外部機能を提供する、数十のMCPツールサーバー

この複雑さは意図的なものです。エージェントは、良い意思決定を下すために、ドメイン知識、コードインテリジェンス、データベーススキーマといった豊富なコンテキストへのアクセスを必要とします。しかしその同じ豊かさが、可視性の問題を生み出します。

どのエージェントがデータベースマイグレーションを担当しているかを、どうやって知ればいいのでしょうか? どんな意思決定が検索システムのランキングの挙動を形作ったのでしょうか? アーキテクチャアドバイザーはどんなツールにアクセスできるのでしょうか?

構造化されたアクセス手段がなければ、ソースコードを読むか、ドキュメントが最新であることを祈るしかありません。

アーキテクチャとしてのプログレッシブディスクロージャー

プログレッシブディスクロージャーは、単なるUIパターンではありません。アーキテクチャ上の原則です。情報を、それぞれ前の層より深い階層に整理することで、ユーザーは自分の疑問に答えてくれる階層で立ち止まることができます。

エージェントシステムにおいて、これは深さを増していくCLIコマンド群として実現されます:

レベル	コマンド	答えてくれる問い
1	`orkestra system status`	すべて健全か?
2	`orkestra agents list`	どんなエージェントが存在するか?
3	`orkestra agents info <name>`	このエージェントは何をするか?
4	`orkestra decisions search`	なぜこのように動くのか?
5	Maguyva MCPツール	コードを見せて。

各レベルは、自然な追加の疑問に答えてくれます。いきなりレベル5まで飛ぶ必要はめったにありません。

レベル1:システムの健全性

最初の問いはいつも同じです。すべて正常に動いているか?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

コマンド1つ。数字4つ。システムが正しく設定され、レジストリにデータが入っていることを知るには、それで十分です。

エージェント数が予期せず減ったり、スキルの読み込みに失敗したりすれば、まずここで気づきます。ログに潜る必要はありません。

レベル2:エージェントの棚卸し

システムが健全だとわかったら、次の問いは「何が使えるか?」です。

$ orkestra agents list

これは構造化データ ―― エージェント名、説明、モデルの優先設定、ドメインのカバー範囲 ―― を返します。出力はデフォルトでJSONなので、jqへパイプしてフィルタリングするのも簡単です:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

データベース関連の作業を扱うエージェントが欲しいですか? searchコマンドで絞り込めます:

$ orkestra agents search "database"

これは名前、説明、能力をスキャンします。40体分のエージェント定義を読まなくても、適切な専門家を見つけられます。

レベル3:エージェントの深掘り

関係がありそうなエージェントを見つけましたか? infoコマンドがすべてを明らかにします:

$ orkestra agents info architecture-advisor

出力には次が含まれます:

メタデータ:名前、カテゴリー、モデルの優先設定、説明
ドメイン:このエージェントがカバーする知識領域
アイデンティティ:キャラクター特性(アーキテクト、ストラテジスト、ナレッジアーキテクトなど)
ツールガイド:コンテキストに注入されるツールドキュメント
ツール:このエージェントが利用できるMCPツールの完全な一覧

実際に表示される内容の一部です:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

これにより、そのエージェントが何をできるのかが正確にわかります。ソースコードを読む必要はありません。

レベル4:意思決定の考古学

エージェントは、文書化された意思決定に従って振る舞います。何かが特定の形で動く理由を理解する必要があるとき、意思決定レジストリが信頼できる情報源になります。

$ orkestra decisions search "agent"

これにより、一致するアーキテクチャ上の意思決定が返されます:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

それぞれの意思決定には完全な来歴があります ―― いつ下されたのか、なぜか、どんなトレードオフが検討されたのか、どのコミットで実装されたのか:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

これは、手作業で維持されるのではなくコミットからマイニングされているため、常に最新であり続けるアーキテクチャドキュメントです。

レベル5:直接的なコードインテリジェンス

実装に関するメタデータではなく、実際の実装そのものを見る必要があるとき、MaguyvaのMCPツールが直接的なアクセスを提供します。

エージェントセッションの内部からは:

mcp__maguyva__intelligent_search
  query: "agent context loading"

これは、関連コードを見つけるためにセマンティック検索、テキスト検索、AST検索を自動的に振り分けます。特定のシンボルについては:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

依存関係分析については:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

これらは単なるgrepの代替品ではありません。グラフを意識し、意味的にインデックス化され、エージェント自身を動かしているのと同じコードインテリジェンスと統合されています。

レジストリを横断した統合検索

どのレジストリに答えがあるのか、わからないこともあります。統合検索はすべてを横断します:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

5つのレジストリにまたがる254件の一致。サマリーが、どこを深掘りすべきかを教えてくれます。詳細な結果が欲しければ--summaryを外し、出力を扱いやすく保ちたければ--limit 5を加えましょう。

これが重要な理由

プログレッシブディスクロージャーは、単なる利便性の話ではありません。複雑なシステムとの向き合い方そのものを変えます。

デバッグが手に負えるものになる。 エージェントが予期しない意思決定をしたとき、ログをgrepする必要はありません。そのエージェントがどんなツールにアクセスできるか(agents info)、どんな意思決定がその振る舞いを形作っているか(decisions search)を確認し、必要なら実装をたどります(intelligent_search)。

オンボーディングが加速する。 新しいチームメンバーは、コードベース全体を読む必要はありません。system statusから始め、agents listで探索し、理解できない何かにぶつかったときだけ、より深く掘り下げます。

ドキュメントが常に最新であり続ける。 CLIはエージェントを構成しているのと同じレジストリから読み込むため、出力は常に正確です。ドキュメントの記述とシステムの実際の挙動の間にズレは生まれません。

インターフェースとしてのCLI

Webダッシュボードを構築することもできました。膨大なドキュメントを書くこともできました。その代わりに私たちは、信頼できる情報源から直接読み込むCLIを構築しました。

CLIには次のような利点があります:

合成可能:出力をjqへパイプし、スクリプトと統合できる
スクリプト化可能:チェックを自動化し、レポートを生成できる
高速:ページ読み込みも認証フローも不要
正確:キャッシュされた表現ではなく、実際の設定を読み込む

見た目より正しさが重要なシステムにおいては、CLIに軍配が上がります。

自分たちのプログレッシブディスクロージャーを構築する

エージェントシステムを構築しているなら、ユーザーがそれをどう検査するかを考えてみましょう:

ヘルスチェックから始める。 すべてが動いているかを教えてくれる1つのコマンド。
棚卸しビューを提供する。 何をするかを説明する前に、何が存在するかを一覧化する。
狙い撃ちのクエリを可能にする。 大規模になれば、検索は閲覧に勝る。
来歴を公開する。 ユーザーが意思決定をその起源までたどれるようにする。
コードインテリジェンスへつなぐ。 最終的に、ユーザーは実装そのものを見る必要がある。

それぞれの層が、追加の疑問に答えます。頻度順に構築しましょう ―― ほとんどのユーザーは層2か3で止まります。層5に到達するのはパワーユーザーだけです。

目標はすべてを公開することではありません。必要なときに、必要なものだけを、正確に公開することです。それこそが、エージェントアーキテクチャに適用されたプログレッシブディスクロージャーです。

グラウンドトゥルース: AIエージェントを現実につなぎとめる

Tue, 13 Jan 2026 00:00:00 GMT

この記事の数値は公開時点(2026年1月)のシステムを反映しています。最新の数値はチームページをご覧ください。

AIエージェントは驚くほど高い能力を持っています。推論し、統合し、生成することができます。しかし根本的な弱点が1つあります。事実を作り出してしまうのです。悪意からではなく、自信満々に。エージェントは、存在しないAPIパラメータをでっち上げたり、一度も定義されたことのない設定を参照したり、実際のアーキテクチャと矛盾する、学習データ由来のパターンを適用したりすることがあります。

定番の対策は「エージェントにもっとコンテキストを与える」ことです。しかしコンテキスト自体が矛盾していることもあります。ドキュメントは実装から乖離していきます。コメントは嘘をつきます。コードでさえ、意図を理解せずに読めば誤解を招くことがあります。

私たちには、もっと明示的な何かが必要でした。無視することも誤解することもできない何か。エージェントを検証可能な現実につなぎとめる何かです。

私たちはそれをグラウンドトゥルースと呼んでいます。

グラウンドトゥルースとは何か

グラウンドトゥルースとは、エージェントが尊重しなければならない、明示的かつバージョン管理された事実の記述です。ドキュメントではありません。コメントでもありません。システムにおける第一級のエンティティであり、次の要素を備えています:

一意の識別子(GT-MAG-015やGT-MAG-036のような)
ライフサイクルステータス(current、tentative、deprecatedのいずれか)
スコープ(プラットフォーム全体、パッケージ固有、ドメイン限定のいずれか)
エビデンス(その記述を裏付けるファイルパス、URL、参照)
エージェント向けガイダンス(明示的な「すべきこと/避けるべきこと」の指示)

私たちのコードインテリジェンスプラットフォームMaguyvaからの例を示します:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

これは文章ではありません。契約です。エージェントがこのグラウンドトゥルースに遭遇したとき、次のことがわかります:

デフォルトの挙動は決定論的である(あいまいな推測ではなく、空の結果を返す)
定義済みの挙動を持つ特定のパラメータ(find_similar、exact_match)が存在する
検証可能な特定のファイルにエビデンスが存在する
この記述は特定の日付に検証済みである

グラウンドトゥルースレジストリの構造

グラウンドトゥルースは、ai_assets/reference/ground_truths.yaml配下のYAMLレジストリに格納されます。各パッケージやドメインは、それぞれ独自のレジストリを持つことができます。その構造は次の通りです:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

レジストリには、コレクション自体に関するメタデータ、ドキュメント生成のためのレンダー設定、そして記述そのものが含まれます。それぞれの記述は、Pydanticモデルによって検証される厳格なスキーマに従います:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

エージェントはグラウンドトゥルースにどうアクセスするか

グラウンドトゥルースは複数のチャネルを通じて公開されています:

1. レンダリングされたドキュメント

orkestra syncコマンドは、YAMLレジストリを読みやすいMarkdownへ変換します:

uv run orkestra sync

これにより、エージェントのコンテキストに組み込まれるGROUND_TRUTHS.mdファイルが生成されます。レンダリングされた出力は、記述をステータスとカテゴリー別にグループ化します:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI検索

シェルアクセスを持つエージェントは、グラウンドトゥルースをプログラム的に検索できます:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

検索機能は、複数のフィールドにまたがるマッチを重み付きの関連度でスコアリングします:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. コンテキストの構成

エージェントがYAML定義からレンダリングされる際、そのコンテキストはグラウンドトゥルースレジストリを参照できます:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

これにより、エージェントが作業を始める前に、関連するグラウンドトゥルースが確実に読み込まれます。

グラウンドトゥルースの分類

私たちのレジストリ全体を見渡すと、グラウンドトゥルースはいくつかのパターンにまとまっていきます:

プロダクト原則

プロダクトが何であり、何でないかについての制約です:

「Maguyvaはユーザーのリポジトリに対して読み取り専用である。再構築不可能な唯一のアセットは、有料の埋め込みキャッシュである。」(GT-MAG-001)

アーキテクチャの境界

責務がどこにあり、なぜそこにあるのかです:

「パイプラインとMaguyvaの境界は意図的なものである。パイプラインは再利用可能であり、Maguyvaはコード固有のロジックを保持し、CQRSはステージの書き込みとサーバーの読み取りを分離する。」(GT-MAG-006)

ハルシネーション防止ルール

ツールの契約を、推測ではなく決定論的なものに保つための明示的な規定です:

「あいまいなシンボルマッチングはfind_similar=trueを介したオプトインである。デフォルトの挙動は、存在しないシンボルに対して空の結果を返す。exact_match=trueは厳格なマッチングを強制し、あいまいなフォールバックをすべて無効化する。」(GT-MAG-015)

品質ゲート

維持されなければならない基準です:

「共有インフラ(post_filters.py、関係抽出器、共有ハンドラー)への変更は、コミット前にフルマニフェスト生成を通じて、サポートするすべての言語に対して検証されなければならない。共有コードに対して単一言語での検証だけでは不十分である。」(GT-MAG-036)

コードパターン

実装上の要件です:

「非同期コンテキストにおけるCPUバウンドな処理にはasyncio.to_thread()を使用する。非推奨のloop.run_in_executor()パターンは新規コードで使用してはならない。」(GT-MAG-018)

グラウンドトゥルースのライフサイクル

グラウンドトゥルースは静的なものではありません。定義されたライフサイクルを通じて進化していきます:

Tentative(暫定)

評価中の、提案された真実です。記述は記録されますが、変更される可能性があります:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current(有効)

エージェントが尊重しなければならない、検証済みの真実です。エビデンスは検証済みです:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated(廃止)

もはや適用されない真実です。何に置き換えられたかへのポインタとともに、歴史的な参照として保持されます:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

なぜドキュメントだけではだめなのか

ドキュメントは異なる目的に奉仕します。説明します。教えます。あいまいであってもよく、「一般的に」や「通常は」といった限定語を使うこともできます。

グラウンドトゥルースはあいまいであってはなりません。それは断定です。適用されるか、されないかのどちらかです。

その違いを見てみましょう:

ドキュメント: 「APIは、シンボルが見つからない場合、一般的には空の結果を返しますが、設定によってはあいまいマッチングが有効になっている場合もあります。」

グラウンドトゥルース: 「デフォルトの挙動は、存在しないシンボルに対して空の結果を返す。exact_match=trueは厳格なマッチングを強制し、あいまいなフォールバックをすべて無効化する。」

前者はシステムを学ぼうとする人間にとって有用です。後者は、判断を下すエージェントにとって実行可能なものです。

エージェント向けガイダンス:すべきこと・避けるべきこと

一部のグラウンドトゥルースには、明示的なエージェント向けガイダンスが含まれています:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

これによりあいまいさが排除されます。これを読んだエージェントは、何が真実であるかだけでなく、その真実がどのような行動を意味するのかも理解できます。

検証とメンテナンス

グラウンドトゥルースにはメンテナンスが必要です。私たちは次を追跡しています:

last_verified:誰かがその記述が今も成り立っていることを確認した日時
evidence:その記述を裏付けるファイル(存在確認が可能)
source:その真実がどこから生まれたか(CLIによる調査、アーキテクチャレビュー、インシデント後の学び)

検証日が古くなっていたり、エビデンスへのリンクが壊れていたりするグラウンドトゥルースは、調査すべきサインです。その真実がまだ有効で再検証が必要なのか、それとも現実が変わってしまいその真実を更新する必要があるのか、どちらかです。

本番環境からの実例

セキュリティ境界

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

このグラウンドトゥルースは、プロダクトを壊してしまうであろう、見当違いの「セキュリティ改善」の一群を未然に防ぎます。

抽出時点での精度

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

これは痛い経験から生まれたルールです。エージェントは、失敗している言語パックに対して、テストハーネスをより「グリーン」に見せかけるだけのバリデータ限定フィルタを追加してパッチを当てていました。その一方で、実際に稼働しているMaguyvaの抽出器は、依然として誤ったエッジを出力し続けていたのです。このルールは、修正を本来あるべき本物の経路 ―― YAML設定、クエリ、あるいはハンドラー ―― へ強制的に差し戻します。

多層フィルタリング

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

これにより、エージェントが誤った場所にフィルタを追加してしまうという、精度の退行を引き起こしがちなよくあるミスを防ぎます。

オーケストレーションシステムとの統合

グラウンドトゥルースは、より広いコンテキストシステムにおける1つのレイヤーです:

アーキテクチャ上の意思決定(ADR) ―― なぜアプローチAをBより選んだのかを記録する
グラウンドトゥルース ―― 今この瞬間、確定的に真実であることを述べる
ドメインパターン ―― 正しい進め方を説明する
アンチパターン ―― 何を避けるべきか、なぜかを説明する

このシステムの中で作業するエージェントは、この4つすべてにアクセスできます。グラウンドトゥルースが事実の錨(いかり)を提供し、意思決定が歴史を説明し、パターンが実装を導き、アンチパターンが落とし穴を警告します。

効果の測定

グラウンドトゥルースを導入して以来、私たちは次のような変化を観測しています:

「ハルシネーションによる修正を、さらに修正する」サイクルの減少
事実が明確なときの、エージェントによるより自信を持った意思決定
期待値が明示的であることによる、PRレビューの質の向上
新しいエージェント(そして人間)のオンボーディング時間の短縮

グラウンドトゥルースを維持するための投資は、デバッグ時間の削減と、より明確なシステム境界という形で報われます。

はじめに

あなたのシステムにグラウンドトゥルースを追加するには:

パッケージのai_assets/reference/ディレクトリにground_truths.yamlを作成する
メタデータとレンダー設定を定義する
スキーマに従って記述を追加する
uv run orkestra syncを実行してドキュメントを生成する
エージェントのコンテキスト構成にレジストリを組み込む

もっとも混乱を招く事実や、もっとも頻繁に破られる制約から始めましょう。それらが、あなたにとって最も価値の高いグラウンドトゥルースです。

結論

AIエージェントはハルシネーションを起こします。それがその本質です。しかし私たちは、ハルシネーションが制約された環境、特定の事実が交渉の余地なく確定している環境、エージェントが自らの前提を検証済みの現実と照らし合わせて確認できる環境を作ることができます。

グラウンドトゥルースは完全な解決策ではありません。メンテナンスが必要です。古くなることもあります。開発プロセスにオーバーヘッドを加えます。

しかし、価値あるものを提供してくれます。人間とエージェントの両方が信頼できる、事実についての共有語彙です。エージェントがソフトウェア開発にますます参加するようになる世界において、その共有された基盤は不可欠なものになっていきます。

その代替案は、エージェントが自信満々に間違いを犯し、人間がそれを訂正し続けるという終わりのないサイクルです。グラウンドトゥルースは、その訂正を明示的かつ永続的なものにすることで、そのサイクルを断ち切ります。

あなたのエージェントには、何が真実かを知る資格があります。それを、教えてあげましょう。

Orkestra:AIエージェントを大規模にオーケストレーションする

Tue, 06 Jan 2026 00:00:00 GMT

この記事の数値は公開時点(2026年1月)のシステムを反映しています。最新の数値はチームページをご覧ください。

Claude Codeでの構築を始めたとき、AIコーディングアシスタントを使うあらゆるチームがいずれ直面する問題にぶつかりました。単一のエージェントでは、すべてをうまくこなすことはできないのです。

エージェントにデータベース専門家であるようプロンプトすることはできます。あるいはセキュリティ監査官として。あるいはフロントエンドエンジニアとして。しかしその3つすべてを同時にこなすよう求めた瞬間、品質は損なわれます。コンテキストは薄まります。指示は衝突します。エージェントは、何をやらせても平凡なジェネラリストになってしまいます。

そこで私たちはOrkestraを構築しました。

Orkestraとは何か

OrkestraはClaude Codeや類似のAIコーディングツール向けのエージェントオーケストレーションシステムです。それぞれ異なる専門知識を持つ複数の専門エージェントを、適切な専門家へ作業を振り分ける単一のオーケストレーターのもとで調整します。

AIエージェント向けの人材派遣会社だと思ってください。オーケストレーターがタスクを受け取り、どの専門家が担当すべきかを見極め、適切なコンテキストとともに委任します。作業が終わると、結果はオーケストレーターへ戻り、そこで統合されます。

数字がその実態を物語っています:

構成要素	数
専門エージェント	46
再利用可能なスキル	466
アイデンティティのアーキタイプ	27
マインドセット	11
コミュニケーションスタイル	10
知識ドメイン	21

キャラクターシステム:エージェント版のD&D

Orkestraの中核にある洞察は、エージェントの振る舞いが3つの組み合わせ可能なプリミティブから生まれるということです。

アイデンティティは、そのエージェントが何であるかを定義します。アーキテクトはシステム構造を設計します。デバッガーは障害を根本原因までたどります。ガーディアンはコンプライアンスとセキュリティ境界を守ります。私たちには、組み合わせ可能な27のアイデンティティのアーキタイプがあります。

マインドセットは、そのエージェントがどう考えるかを定義します。分析的なマインドセットは、エビデンスに根ざした主張を行い、不確実性を定量化します。懐疑的なマインドセットは前提を疑い、反証となる証拠を積極的に探します。探索的なマインドセットはあいまいさを受け入れ、複数のアプローチを試みます。

スタイルは、そのエージェントがどうコミュニケートするかを定義します。技術的なスタイルは、正確な値と具体的なファイルへの参照を含みます。簡潔なスタイルは無駄をそぎ落とし、結論から述べます。外交的なスタイルは正直さと配慮のバランスを取ります。

エージェントは、これらのプリミティブを組み合わせます:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

この組み合わせは、システムを設計し(アーキテクト)、ドメインをまたいで知識をつなぎ(ナレッジアーキテクト)、戦略的な方向性を定め(ストラテジスト)、エビデンスとデータで考え(分析的)、無駄なく伝える(簡潔)、そんなエージェントを生み出します。

その力は、組み合わせ爆発にあります。27のアイデンティティ×11のマインドセット×10のスタイルで、およそ3,000通りのエージェント人格が生まれます。しかし、実際に定義するのは自分たちの作業にとって意味のある組み合わせだけです。

スキル:再利用可能な能力モジュール

スキルは、エージェントが呼び出せる知識とワークフローです。スコープに基づく階層システムに従います:

ティア	名称	スコープ	例
K0	基盤	普遍的な方法論	テストファースト規律、エビデンスに基づく完了判断
K1	アイデンティティ	役割ベースのワークフロー	CLIインターフェース標準、パフォーマンスプレイブック
K2	ドメイン	ドメイン固有の知識	データベースマイグレーションパターン、認証の検証
K3	スタック	技術固有	Cloudflareデプロイ、Supabase運用
K4	プロジェクト	このコードベース限定	プロジェクト固有のワークフローと規約

スキルは遅延ロードされます。エージェントは起動時にスキルの名前と説明を目にしますが、実際に発動したときにのみ完全な内容が読み込まれます。これにより、何百ものスキルを発見可能にしながら、コンテキストを軽量に保てます。

各スキルには次が含まれます:

明確な発動条件(「データベーススキーマを移行するときに使う」)
ステップバイステップのガイダンス
そのワークフローで許可されるツール
成功基準と失敗時のリカバリー経路

私たちのレジストリにある466のスキルは、gitのworktree分離からWebリサーチのワークフロー、デプロイの健全性検証まで、あらゆるものをカバーしています。

なぜオーケストレーションが重要なのか

単一エージェントのアーキテクチャは、すぐに壁にぶつかります:

コンテキストの希釈。 20万トークンのコンテキストウィンドウは、データベーススキーマ、APIドキュメント、テストフィクスチャ、ドメイン知識を読み込むまでは大きく感じられます。専門エージェントであれば、絞り込んだコンテキストで作業できます。

指示の衝突。 エージェントに「徹底的に、しかし速く」「すべて検証せよ、しかし過剰設計はするな」と伝えると、緊張が生まれます。専門エージェントは明確なスコープを持つことでこれを解決します。

専門性の深さ。 ジェネラリストのエージェントは、何についても少しずつ知っています。適切なアイデンティティとスキルで構成された専門エージェントは、自分のドメインを深く知っています。

Orkestraはフラットなオーケストレーションを実装しています。1つのオーケストレーターが複数の専門エージェントを調整します。専門エージェントはサブ専門エージェントを生成できません。これにより、複雑性の爆発を防ぎながら並行作業を可能にしています。

オーケストレーターは、実質220万トークンの容量にアクセスできます。自身の20万トークンのウィンドウに加え、それぞれ20万トークンを持つ10体の同時実行サブエージェントです。単一のエージェントなら使い果たしてしまうような作業も、この編隊なら余裕をもってこなせます。

レンダリングパイプライン

エージェント定義はYAMLで存在します。Claude CodeはMarkdownを読みます。Orkestraは、決定論的なレンダリングパイプラインでこのギャップを橋渡しします:

YAML Registries → Jinja Templates → .claude/agents/*.md

オペレーターはYAMLソースを編集します。orkestra syncを実行します。レンダリングされたMarkdownは.claude/agents/に現れます。Claude Codeがその変更を取り込みます。

この分離は、異なる読み手に対応しています:

YAMLソースには、ツール連携のためのライフサイクルメタデータ、タグ、検証ルール、非推奨の注記が含まれます
レンダリングされたMarkdownには、モデルが必要とするものだけが含まれます。説明、ツール、スキル、振る舞いに関するガイダンスです

このパイプラインは、アイデンティティ、マインドセット、スタイル、スキルを1つの一貫したプロンプトへと合成します。アーキテクト×分析的×簡潔なエージェントは、いくつかの基盤スキルを共有していたとしても、デバッガー×懐疑的×技術的なエージェントとはまったく異なるシステムプロンプトを持つことになります。

ドメイン知識:4ファイルパターン

すべての知識ドメインは、一貫した構造に従います:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

この構造は、エージェントのコンテキスト読み込みに役立ちます。認証まわりの作業をしているエージェントは、ガイダンスのためにauthentication/patterns.mdを、既知の落とし穴を避けるためにauthentication/anti-patterns.mdを読み込みます。ファイルは効率的なコンテキスト読み込みのためにサイズ調整されています。有用であるために十分に絞り込まれており、権威あるものであるために十分に包括的です。

私たちは、分析、認証、データサイエンス、インフラ、機械学習、パフォーマンス、セキュリティなどを含む21のトップレベルドメインを維持しています。各ドメインは、より細かい粒度のためのサブドメインを持つことができます。

価値観:オペレーティングシステム

すべてのエージェントは、その動作を定義する共通の価値観のベースレイヤーを共有しています:

シンプルさを最優先。 機能する最もシンプルな解決策を使う。複雑さは正当化される場合にのみ加える。

根本原因を直す。 失敗を回避するパッチを当てない。パイプラインが失敗したらパイプラインをデバッグする。テストが失敗したらコードかテストを直す。

エビデンスに基づく。 主張には「検証済み」(ベンチマーク付き)か「推定」(前提条件付き)のラベルを付ける。パターンの検出は、問題の確定を意味しない。

コンテキストの経済学。 MCPツールのコストはコンテキストの0.1%。ファイル読み込みは1回あたり2%。コードを探索する前にドメインの専門知識を適用する。

これらの価値観は、レンダリングパイプラインを通じてすべての専門エージェントへ伝播します。エージェントは組み合わせによってこれを迂回することはできません。

CLI:コントロールプレーン

Orkestraには、エージェントエコシステムを管理するためのCLIが付属しています:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

このCLIは、どんなエージェントが存在し、どんなスキルを持ち、システムが健全かどうかを知るための信頼できる情報源です。問題を早期に発見するため、同期前にバリデーションを実行します。

オープンソースについての検討

私たちがOrkestraを構築したのは、自分たち自身の問題 ―― 複雑なコードベースに対して、大規模にAIエージェントを調整すること ―― を解決するためでした。そこで発見したパターンは、私たちのドメインに特有のものではありません。

キャラクター合成システム(アイデンティティ+マインドセット+スタイル)は、エージェントの人格を定義するどんなチームにも当てはまります。

スキルティアシステム(K0〜K4)は、再利用可能な能力をスコープ別に整理するためのメンタルモデルを提供します。

レンダリングパイプラインのパターン(YAMLソース+テンプレート+生成された成果物)は、ツール連携とモデルによる読み込みとを分離します。

フラットなオーケストレーションモデル(1つのコーディネーター、多数の専門エージェント)は、並行性を可能にしながら複雑さを回避します。

Orkestraがオープンソースになるかどうかは、これらのパターンが、Claude Codeで構築している他の人々にとっても価値があるかどうかにかかっています。もしあなたが私たちの説明したのと同じ壁にぶつかっているなら、このアーキテクチャは助けになるかもしれません。

私たちが学んだこと

Orkestraを構築して学んだのは、オーケストレーションはエージェントを賢くすることではない、ということです。エージェントをより集中させることなのです。

完璧な指示を持つ単一のエージェントでも、いずれコンテキストは尽きます。すべてのスキルを持つ単一のエージェントでも、どれを適用すべきか混乱します。すべてになろうとする単一のエージェントは、あらゆる場面で平凡な結果しか出せません。

それぞれの領域で卓越した40体の専門エージェントを、いつ委任すべきかを知るオーケストレーターが調整する ―― それが私たちの出荷の仕方です。

数字よりも重要なのはアーキテクチャです。必要なのは5体のエージェントかもしれませんし、50体かもしれません。原則は変わりません。能力より合成を、汎用化より専門化を、個人技より協調を。

Orkestraは、私たちのコードインテリジェンスプラットフォームMaguyvaを支えるエージェントエコシステムの原動力です。もっと知りたいですか? チームまでお問い合わせください。