SpiderBrain: リポジトリのための理解レイヤー

リポジトリはAIエージェントにコードが何であるかを伝えます。しかし、何が重要で、変更がどこに影響を及ぼすのか、あるいはなぜ何かがそのように作られたのかという理由は決して伝えません。そのため、すべてのエージェントは毎セッション、ゼロから構造を再導出し、少し間違った結果を得ることになります。

SpiderBrainはリポジトリに、コミットされたソースフリーの理解レイヤーを与えます。つまり、構造・依存関係・影響範囲の決定的なマップであり、あらゆるAIコーディングエージェントがセットアップ不要で読むことができます。このリポジトリは、そのレイヤーのオープンでMITライセンスの部分、すなわちリーダーとフォーマット仕様です。

• ウェブサイト: https://spiderbrain.ai

• 決定性ベンチマーク: https://contextbenchmark.com

1行で使う

リポジトリが.spiderbrain/フォルダを保持している場合、リーダーをそこに向けます:

npx spiderbrain mcp --root .

MCPクライアントの作業ディレクトリは通常あなたのリポジトリではないため、--root <path>、--root=<path>、またはSPIDERBRAIN_ROOT環境変数でリポジトリを明示的に渡してください。これがないと、サーバーは作業ディレクトリを提供し、理解レイヤーが見つからなかったと報告します。これはエラーではなく誤った回答です。

これで、コーディングエージェント(Claude Code、Cursor、または任意のMCPクライアント)がクエリできるMCPサーバーが起動します。ツール: sb_blast、sb_impact、sb_path、sb_keystones、sb_map、sb_ask。アカウント不要、SpiderBrainのインストール不要、設定不要です。実際のセッションのトランスクリプトはexamples/agent-session.mdにあります。

ターミナルがお好みなら:

npx spiderbrain blast src/server/health.ts   # what a change here reaches
npx spiderbrain impact                        # what YOUR CURRENT DIFF reaches
npx spiderbrain keystones                     # the load-bearing files
npx spiderbrain map src/auth/session.ts       # what a file is + touches
npx spiderbrain path src/a.ts src/b.ts        # how one file reaches another
npx spiderbrain verify --allow-stale          # folder untampered? see note below

コミットされたブレインに--allow-staleを使う理由。 verifyは2つのことをチェックします: structure.ndjsonが記録されたフィンガープリントと一致すること、そしてブレインが現在のHEADでスコアリングされたことです。フォルダをコミットすること自体がコミットであるため、リポジトリにコミットされたブレインは常に少なくとも1コミット遅れており、2番目のチェックは新しいクローンでは決して成功しません。--allow-staleは整合性チェックを厳格に保ち、その遅れのみを許容します。テスト対象のコミットでCI内にブレインを構築する場合は、このフラグを外してください。その場合、最新性は実際に保たれます。

Related MCP server: mcp-codebase-intelligence

エージェントが第一級市民

すべてのコマンドは--jsonを受け取り、機械可読な単一のオブジェクトを出力します。終了コードも契約の一部です: 0はOK、1はチェック失敗、2は使用方法の誤り、3は理解レイヤーなし。CIはこれらでゲートをかけることができます:

npx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files
npx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)

すぐに使えるワークフロー(PRの影響範囲コメントと鮮度ゲート)はexamples/にあります。

フォルダがない場合? レジストリへのフォールバック

リポジトリが.spiderbrain/フォルダを保持していない場合、リーダーは公開SpiderBrainレジストリで同じリポジトリの非公式ブレインをチェックします(originリモートで照合され、明確にラベル付けされ、フィンガープリント検証済み)。コミットされたフォルダが存在する場合は常に優先されます。メンテナーはnpx spiderbrain createで公式のものを公開できます。

このリポジトリは自分自身のドッグフードを食べる

このリポジトリは、実際のインポートグラフから導出された、自身のコミット済み.spiderbrain/フォルダを保持しています(node scripts/build-own-brain.mjsで生成され、決定論的に再生成され、CIで検証されます)。クローンして、それ自身について質問できます:

npx spiderbrain keystones      # read/src/core.mjs is the load-bearing file
npx spiderbrain verify --allow-stale   # the committed fingerprint matches the bytes

自分のリポジトリに理解を与える

export SPIDERBRAIN_API_KEY=sb_live_...     # https://spiderbrain.ai/dashboard?tab=keys
npx spiderbrain create

スコアリング済みのブレインを取得し、ソースフリーの.spiderbrain/フォルダとAGENTS.mdブロックを書き出します。両方をコミットすれば、その後リポジトリに触れるすべてのエージェントがそれを読み取ります。

オフラインとクラウド

• オフライン(無料、決定論的、コミットされたバイトから): 構造、依存関係、影響範囲、キーストーン。同じリポジトリ、同じ質問、同じ回答、バイト単位で同一。

• クラウド(SPIDERBRAIN_API_KEYを設定): ファイルの背後にある理由(記録された決定とその根拠)、常に最新のスコア、セマンティック検索。キーはhttps://spiderbrain.ai/dashboard?tab=keysで取得できます。

export SPIDERBRAIN_API_KEY=sb_live_...
npx spiderbrain why src/billing/charge.ts

フォルダの中身

コミットされた.spiderbrain/フォルダはソースフリーです: ファイルパス、構造、エッジから導出可能な影響範囲のみ。あなたのソースコードは決して含まれません。スコアリングの重みも決して含まれません。正確な内容と決定性の保証はSPEC.mdに文書化されています。

すべてのフォルダはmanifest.jsonにフィンガープリントを保持しています。リーダーはロード時にそれを再計算するため、手編集や破損したフォルダはフラグが立てられ、クエリするマップは公開されたマップそのものです。

このリポジトリ(3つのMITパッケージ+仕様)

• spiderbrain/ — spiderbrain、単一のコマンド。以下の2つを束ねる薄いディスパッチャー。

• read/ — @spiderbrain/read、消費: フォルダローダー、影響範囲トラバーサル、CLI、MCPサーバー、クラウドクライアント。依存関係ゼロ。

• create/ — @spiderbrain/create、生成: スコアリング済みブレインを取得し、理解セット+AGENTS.mdを書き出します。

• SPEC.md — .spiderbrain/公開フォルダフォーマット。

各スコープパッケージは独立してインストール可能です: 理解を公開するだけのCIジョブは@spiderbrain/createだけで十分です。読み取りだけのMCP設定は@spiderbrain/readを指します。spiderbrainは、ただその機能が欲しいときにタイプするものです。

ブレインをスコアリングするエンジン(パースとスコアリングモデル)はプロプライエタリで、SpiderBrainにあります。ここでオープンにされているのは、フォーマット、リーダー、プロデューサークライアントです。つまり、誰でも公開された理解レイヤーを読み書きしたり、それを行うツールを構築したりできます。

ライセンス

MIT。 LICENSEを参照してください。