Sourcebook

sourcebook

AI エージェントが変更し忘れたファイルを検出します。

コード変更のためのセーフティレイヤーです。sourcebook は git の差分を分析して変更漏れを検出し、変更されるべきなのに変更されていないファイルにフラグを立てます。ルールベースの構造検出と AI によるセマンティック分析を組み合わせています。問題のない差分で誤検出はゼロです。

npx sourcebook init          # sets up Claude Code hooks + generates CLAUDE.md
npx sourcebook check         # check your current diff for missing files
npx sourcebook scan-history  # see what you've been missing

検出できるもの

AI エージェントはハンドラーを変更しました。テストも更新しましたか？関連モジュールは？古い値を参照している設定は？

sourcebook は、リポジトリの実際の構造に照らして差分をチェックします。

• 不足しているテストファイル — ソースファイルは変更されたが、テストファイルは変更されていない
• 関連モジュール — 変更したファイルをインポートする、または変更したファイルからインポートされるファイル
• 共変更ファイル — git のコミットで過去に一緒に変更されたファイル
• ハブファイルの影響範囲 — 依存ファイルが 50 個以上あるファイルを変更した場合

--ai を指定すると、モジュールをまたぐセマンティックな関係、マイグレーションが必要なフィールド名の変更、古いままの検証ロジックも検出します。

主な統計

指標	結果
変更漏れ検出	100% の精度（30/30 件の差分）
誤検出率	問題のない差分では 0%
テストファイルの検出率	73%
関連モジュールの検出率	71%
AI 分析のコスト	1 回あたり約 $0.012

4 つの利用方法

1. CLI

セットアップ不要で、あらゆる差分に対して実行できます。

npx sourcebook check              # check staged/unstaged changes
npx sourcebook check --ai         # add AI semantic analysis (requires ANTHROPIC_API_KEY)
npx sourcebook check --quiet      # exit code only (for CI/scripts)
npx sourcebook check --branch main  # compare vs a branch

2. Claude Code フック

1 つのコマンドでコミット前フックを設定できます。エージェントがファイルを編集すると、sourcebook が差分をチェックし、不足しているものをエージェントに知らせます。すべてコミット前に行われます。

npx sourcebook init   # generates CLAUDE.md + installs hooks

3. MCP サーバー

公式 MCP レジストリで公開されています。エージェントは必要に応じて、リポジトリの構造、影響範囲、規約、共変更データを照会できます。

npx sourcebook serve

MCP クライアントに追加します。

{
  "mcpServers": {
    "sourcebook": {
      "command": "npx",
      "args": ["-y", "sourcebook", "serve", "--dir", "/path/to/your/project"]
    }
  }
}

4. GitHub アプリ（近日公開）

すべてのプルリクエストで変更漏れを自動チェックします。ウェイトリストに登録。

コマンド

コマンド	説明
sourcebook check	現在の差分を分析して変更漏れを検出
sourcebook check --ai	AI によるセマンティック分析を追加（ANTHROPIC_API_KEY が必要）
sourcebook check --quiet	終了コードのみを返す — 検出結果があれば 1、問題がなければ 0
sourcebook check --json	構造化された JSON 出力
sourcebook check --branch main	HEAD とブランチを比較
sourcebook check --threshold 0.9	共変更の結合しきい値をカスタマイズ（0-1）
sourcebook init	Claude Code フックをセットアップし、CLAUDE.md/AGENTS.md を生成
sourcebook scan-history	最近のコミットを遡ってスキャン
sourcebook hooks	Claude Code フックをインストール、または状態を確認
sourcebook truth	Repo Truth Map（2.5D 可視化）を生成
sourcebook serve	MCP サーバーを起動
sourcebook update	手動編集を保持しながら再分析
sourcebook diff	変更される内容を表示（変更が見つかった場合、終了コードは 1）
sourcebook watch	ソースの変更時にコンテキストファイルを自動再生成
sourcebook ask <query>	自然言語でコードベースのナレッジを照会

仕組み

レイヤー A — ルールベース（LLM 不使用、1 秒未満）

1. 共変更分析 — git の履歴を調べ、一緒に変更されるファイルを特定します。auth.ts を変更し、それがコミットの 88% で session.ts と一緒に変更されている場合、sourcebook は session.ts にフラグを立てます。
2. テストファイルの検出 — 命名規則と共変更履歴を使って、ソースファイルとテストファイルを対応付けます。
3. インポートグラフ — 依存関係グラフを構築し、変更したファイルをインポートする（または変更したファイルからインポートされる）ファイルにも更新が必要かどうかを確認します。
4. ハブの検出 — 多くのファイルに依存されている（被依存数が多い）ファイルを変更した場合にフラグを立てます。このような変更は影響範囲が広くなります。

レイヤー B — AI 活用（約 $0.012/run）

差分と依存関係のコンテキストを Claude Sonnet に送信します。レイヤー A では検出できない意味的な関係性を検出します。たとえば、マイグレーションが必要なフィールド名の変更、古いスキーマを前提とするバリデーションロジック、インポートによるつながりのないモジュール間の依存関係などです。

AI による提案には、すべて依存関係の引用が必要です。幻覚によるファイルパスは除外されます。完全性ゲートにより誤検知をゼロにします。差分が実際に完全であれば、レイヤー B は何も通知しません。

設定

# Required for --ai flag only
export ANTHROPIC_API_KEY=sk-ant-...

ほかに必要な設定はありません。sourcebook はリポジトリの Git 履歴とファイル構造を直接読み取ります。

言語サポート

言語	インポートグラフ	Git 分析	規約の検出
TypeScript / JavaScript	完全	完全	完全
Python	完全	完全	完全
Go	完全	完全	完全
Rust	完全	完全	部分的

研究

雰囲気ではなく、実際のベンチマークに基づいています。

• 検証結果を確認 — 手法と精度データ
• ベンチマーク：19 個のタスク、10 個のリポジトリ、4 つの言語 — エージェントのパフォーマンスを制御条件下でテスト
• 自動生成されたコンテキストがエージェントの性能を低下させる理由 — アプローチの形成に影響を与えた ETH Zurich の知見

ライセンス

BSL-1.1 — ソースコードを利用可能で、無料で使用できますが、ホステッドサービスとして提供することはできません。2030-03-25 に MIT ライセンスへ移行します。詳細は LICENSE をご覧ください。

---

sourcebook.run · GitHub · npm · @maroond_