Span

コーディングエージェントのための、コードベースに関する持続的な理解。

Span はローカル MCP サーバーです。エージェントがリポジトリについて学んだ内容を、その根拠となったコードにひも付けて保持し、根拠が変わると古くなったことを示します。

クイックスタート · 仕組み · ドキュメント

問題

コーディングエージェントは、リポジトリの現状と合わなくなっている可能性のあるドキュメントや記憶を信頼するか、セッションのたびに同じソース、テスト、コントラクト、設定を読み直し、同じ理解を再構築することになります。

メモが誤った内容になっても、通常は何も起こりません。ファイルは有効に見えたままで、エージェントはそれを読み続け、次のセッションも同じ不確かな状態から始まります。

Span はエージェントに第3の選択肢を提供します。確立された理解を、その根拠とともに保存し、その根拠が今も有効かどうかを明確に示します。

動作を見る

これは、現在のビルドで2つのファイルを使ったフィクスチャに対して行った、実際のやり取りです。クライアントはスクリプト化された MCP クライアントであり、モデルではありません。ここではワイヤー上のやり取りと鮮度の挙動を示しており、モデルによる判断は示していません。生のレコードはこちらです： 現在の MCP 受け入れテストの証跡。

> explain src/alpha.py
Pending cont-1  CQ-01
  "VALUE = 1"

> submit_interpretation cont-1
PURPOSE  alpha computes the value
  CURRENT

> explain src/alpha.py
PURPOSE  alpha computes the value
  CURRENT

# edit src/alpha.py

> status src/alpha.py
PURPOSE  alpha computes the value
  STALE
  evidence changed
  scope: src/alpha.py

> refresh src/alpha.py
Pending cont-6  CQ-01
  "VALUE = 1 # touched"

> submit_interpretation cont-6
PURPOSE  alpha computes the value
  CURRENT
predecessor  STALE

最初の呼び出しは、上限のあるタスクを保留します。送信によって目的が確立され、次の explain でそれが現在も有効なものとして読み返されます。ファイルの変更後、status は目的が古くなったことと、変更されたファイル、および再確認が必要な範囲を報告します。refresh はその範囲だけを再確認し、新しい結果は現在も有効なものになります。一方、前の記録は古いものとして残ります。

古くなったということは、根拠となる情報が変わったという意味です。Span が以前の結論が誤りだと証明した、という意味ではありません。

編集によってリポジトリ全体が無効になったわけではなく、以前の結論が現在も有効であるかのように残ることもありません。Span は最初の調査を削除せず、セッション終了時にその作業が破棄されないよう保持します。

仕組み

テストがコードにフィードバックループをもたらすように、Span はコードベースの理解にフィードバックループをもたらします。

1. 確立。 エージェントが対象範囲を限定して調査します。Span は、結論と、それを裏付ける証拠および使用した権威情報を一緒に保持します。
2. 再利用。 後続のエージェントは、裏付けがまだ有効なうちに確立された理解を利用できます。
3. 範囲を絞って無効化。 裏付けとなる証拠が変わると、それに依存していた理解だけが STALE になります。
4. 再確認。 エージェントが影響を受けた範囲を調査し、新しい結果を提出します。影響を受けていない理解は有効なままで、前の結果は履歴として残ります。

状態	意味
CURRENT	記録された理解は、それが依存する証拠と前提によって、引き続き裏付けられています。
STALE	理解が確立された後に、関連する裏付けが変わりました。有効なものとして扱う前に、再確認してください。
UNVERIFIABLE	結論はありますが、確認に必要な裏付けを取得できませんでした。記録されたソースがインベントリに存在しない、権威情報のシードが欠落している、インベントリのフィンガープリントを取得できない、または範囲を限定した前提のたどり直しが完了しなかった場合が該当します。有効でも、古くなったことが判明している状態でもありません。プロバイダーまたはストアの障害はこの状態ではなく、操作自体が失敗します。

クイックスタート

Span の現在の動作要件は、Linux（検証済みのインストール方法）、Python 3.12 以降、および npm を含む Node.js です。

pipx install span-mcp        # or: pip install span-mcp
span-install --repo /path/to/your/repo

span-install は Span の実行環境を作成し、管理対象の構造インデクサーを準備し、Agent Skills をデプロイして、対応するホストを登録します。インストール後、コーディングエージェントを再起動するか、再読み込みしてください。

インストールを確認します。

span-install --verify-only

代わりにソースチェックアウトから作業する場合（コントリビュートする場合や、特定のコミットに固定する場合）は、リポジトリをクローンし、ルートディレクトリからインストーラーを実行します。

git clone https://github.com/pontivus-com/span.git
cd span
python3 scripts/install-span.py --repo /path/to/your/repo

インストールによって確立されるのは運用上の準備であり、リポジトリに関する理解ではありません。手動で設定する Codex コマンドと OpenCode の設定方法については、インストールと接続を参照してください。

対応環境

ホスト	設定
Claude Code	Claude Code CLI が存在する場合、インストーラーが管理します。ユーザースコープの MCP 登録、~/.claude/skills へのスキルの配置、および ~/.claude/settings.json へのレポート専用のライフサイクルフックの設定を行います。手動での登録方法は、インストールと接続を参照してください。
Codex	Codex CLI が存在する場合、インストーラーが管理します。手動での登録方法は、インストールと接続を参照してください。
OpenCode	opencode.json が存在する場合、管理対象になります。対応する手動設定については、インストールと接続を参照してください。
その他の MCP ホスト	span-mcp --data-dir <DATA_DIR> --repo <TARGET_REPO> を使用して stdio 経由で接続します。

Span はローカルで stdio 経由で動作します。LLM を呼び出したり、モデルを選択したり、プロバイダーの認証情報を保存したりすることはありません。Span の状態は、分析対象のリポジトリの外部にあるデータディレクトリに保存されます。

異なる点

ドキュメントは答えを記録します。エージェントメモリは記憶します。検索は根拠を見つけます。 Span はその間にある解釈レイヤーを維持します。結論、その根拠、その権威性、その依存関係、そして鮮度です。

アプローチ	解釈済みの理解を保持する	依然として裏付けられているかを追跡する	変更内容とその範囲を明らかにする	範囲を指定した意味的な再確認に対応する
従来のドキュメントまたは自動生成されたドキュメント	はい	本質的には対応しない	いいえ	いいえ
一般的なエージェントメモリ	はい	本質的には対応しない	いいえ	本質的には対応しない
引用検証済みのエージェントメモリ	はい	事実ごとに対応	いいえ — 未検証の項目は提示されない	いいえ
コード検索／構造グラフ	目的が異なる	ソースまたは構造のみ	構造のみ	意味的な再評価には対応しない
Span	はい	項目、前提、発見範囲ごとに対応	はい、理由も明示	はい

検証と範囲を指定した疑義の違いを含む詳しい比較は、範囲と境界をご覧ください。

該当しないもの

• ドキュメント生成ツールではありません。
• 検証の有無を問わず、一般的なエージェントメモリではありません。
• コード検索ツールでも構造グラフでもありません。
• LLM サービスではありません。モデルを呼び出したり、プロバイダーの認証情報を保存したりすることはありません。
• 自律型ではありません。コードの編集やテストの実行は行わず、古くなった理解を自動で最新の状態にすることもありません。

全項目については、範囲と境界をご覧ください。

ステータス

Span はベータ版です。現在、インストール手順の検証が完了しているのは Linux のみです。macOS と Windows の手順は用意されていますが、検証は完了していません。公開されている操作インターフェースは 11 個の MCP 操作です。詳しくは「MCP リファレンス」をご覧ください。記録済みの受け入れテストの実行結果は「受け入れテストの証跡」にあります。

Span が役に立った場合は、スターを付けていただくと、ほかの開発者にも見つけてもらいやすくなります。フィードバックや課題の報告も歓迎します。

ドキュメント

• リポジトリの概要
• インストールと接続
• Span の使い方
• MCP リファレンス
• 鮮度と更新
• 根拠、権威性、信頼
• 範囲、境界、差別化
• よくある質問
• アーキテクチャ
• ドキュメントの完全な目次
• 用語集
• 変更履歴

貢献

貢献ガイドをご覧ください。変更を加える際は、中核となる契約を維持してください。確立された理解は、それを支えるために必要な証拠が最新である間に限り、再利用できます。セキュリティに関する報告はSECURITY.mdを通じて受け付けています。サポートに関する方針はSUPPORT.mdに記載されています。

レジストリ

公式 MCP レジストリのエントリー：io.github.pontivus-com/span

mcp-name: io.github.pontivus-com/span

ライセンス

Span は Apache License 2.0（Apache-2.0）のもとでライセンスされています。LICENSEをご覧ください。

一文で言うと

Span は、気付かれないまま古くなることのないコードベースの理解をコーディングエージェントに提供します。今も有効な理解を再利用し、変更された部分だけを再確認します。