sourcebook

AIはコードを読み取れますが、あなたのプロジェクトがどのように機能しているかはまだ知りません。

sourcebookは、チームが頭の中に抱えているプロジェクトの知識（規約、パターン、落とし穴、実際の配置場所など）をキャプチャし、コーディングエージェントが利用できるコンテキストに変換します。

npx sourcebook init

RepomixのようなツールはAIにコードベース全体を渡しますが、sourcebookはプロジェクトの知識を渡します。

なぜ必要なのか

AIコーディングエージェントは、コンテキストウィンドウの大部分を「状況把握」に費やしています。つまり、実際の作業を行う前にファイルを読み込んでメンタルモデルを構築しているのです。ほとんどのコンテキストファイル（CLAUDE.md、.cursorrules）は汎用的であり、すぐに陳腐化してしまいます。

研究によると、明白な情報を再記述する自動生成コンテキストは、実際にはエージェントの性能を2〜3%低下させることが示されています。役立つ唯一のコンテキストは発見不可能な情報、つまりコードを読むだけではエージェントが把握できないプロジェクトの知識です。

sourcebookは、エージェントが見落としがちな情報だけを抽出します。それは、コード内ではなくチームの頭の中に存在する規約、隠れた依存関係、脆弱な領域、そして支配的なパターンです。

検出内容

• インポートグラフ + PageRank — 構造的な重要度でファイルをランク付けし、影響範囲が最も広いハブファイルを特定します

• Git履歴フォレンジック — リバートされたコミット（「これをしてはいけない」というシグナル）、変更の結合（目に見えない依存関係）、頻繁な再編集（修正が困難だったコード）、放棄されたアプローチによるアンチパターン

• 規約検出 — 命名パターン、エクスポートスタイル、インポートの構成、バレルエクスポート、パスエイリアス、型ヒントの使用、エラーハンドリングのスタイル

• フレームワーク検出 — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber)

• コンテキストの陳腐化を考慮したフォーマット — 重要な制約を上部に、参照情報を中央に、アクションプロンプトを下部に配置（LLMの注意パターンに最適化）

• スマートな予算管理 — コンテキストがトークン予算を超えた場合、優先度の低いセクションから順に削除（重要な制約は常に保持）

クイックスタート

# Generate CLAUDE.md + AGENTS.md for your project
npx sourcebook init

# Generate for a specific tool
npx sourcebook init --format claude,agents  # CLAUDE.md + AGENTS.md (default)
npx sourcebook init --format cursor         # .cursor/rules/sourcebook.mdc + .cursorrules
npx sourcebook init --format copilot        # .github/copilot-instructions.md
npx sourcebook init --format agents         # AGENTS.md only
npx sourcebook init --format all            # All of the above

# Re-analyze while preserving your manual edits
npx sourcebook update

# See what changed since last generation (exit code 1 = changes found)
npx sourcebook diff

# Limit output to a token budget (drops low-priority sections first)
npx sourcebook init --budget 1000

コマンド

オプション

言語サポート

GitHub Action

マージごとにコンテキストファイルを自動更新：

# .github/workflows/sourcebook.yml
name: Update context files
on:
  push:
    branches: [main]

jobs:
  sourcebook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: maroondlabs/sourcebook@main
        with:
          format: all

出力例

cal.com (10,456ファイル) で実行した場合：

sourcebook
Extracting repo truths...

✓ Scanned project structure
  10,456 files, 3 frameworks detected
✓ Extracted 11 findings

  ● Core modules: types.ts imported by 183 files — widest blast radius
  ● Circular deps: bookingScenario.ts ↔ getMockRequestData.ts
  ● Co-change: auth/provider.ts ↔ middleware/session.ts (88% correlation)
  ● Dead code: 1,907 orphan files detected
  ● Conventions: named exports preferred (26:2 ratio)
  ● Barrel exports: 40 index.ts re-export files
  ● Commit style: Conventional Commits (feat/fix/docs)

✓ Wrote CLAUDE.md
✓ Wrote AGENTS.md

仕組み

sourcebookは5つの分析パスを実行します。すべて決定的かつローカルで動作し、LLM、APIキー、ネットワーク呼び出しは使用しません：

1. 静的解析 — フレームワーク検出、ビルドコマンド、プロジェクト構造、環境変数

2. インポートグラフ — すべてのインポートの有向グラフを構築し、PageRankを実行して構造的に最も重要なファイルを特定

3. Gitフォレンジック — コミット履歴からリバート、アンチパターン、変更の結合、チャーン（頻繁な変更）のホットスポット、放棄されたアプローチをマイニング

4. 規約推論 — ソースファイルをサンプリングして、命名、インポート、エクスポート、エラーハンドリング、型注釈のパターンを検出

5. 予算管理 — 出力がトークン予算を超えた場合、優先度の低いセクションをインテリジェントに削除（補足的な発見事項を先に、重要な制約は決して削除しない）

次に発見可能性フィルターを適用します。すべての発見事項に対して「エージェントはコードを読むだけでこれを把握できるか？」と問いかけ、Yesであれば削除します。発見不可能な情報のみが出力されます。

出力はコンテキストの陳腐化への耐性を考慮してフォーマットされます。重要な制約はファイルの先頭と末尾（LLMが最も注意を払う場所）に配置され、軽量な参照情報は中央に配置されます。

MCPサーバー

sourcebook serve は、ライブコードベースインテリジェンスをMCP互換のAIクライアント（Claude Desktop、Cursorなど）に公開するローカルMCP（Model Context Protocol）サーバーを起動します。

静的なコンテキストファイルではなく、AIエージェントがプロジェクトのアーキテクチャをオンデマンドで照会できます。編集前に影響範囲を調べたり、コードを書く前に規約を確認したり、Git履歴からアンチパターンをマイニングしたりすることが可能です。

インストール

MCPクライアントの設定にsourcebookを追加します：

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

Claude Code — ターミナルで実行：

claude mcp add sourcebook -- npx -y sourcebook serve --dir /path/to/your/project

または ~/.claude/claude_desktop_config.json に手動で追加します。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

Cursor — プロジェクト内の .cursor/mcp.json またはグローバルの ~/.cursor/mcp.json に追加します。

その他のMCPクライアント — STDIOトランスポートをサポートするクライアントであれば、上記の同じ設定ブロックで動作します。

設定を更新した後、クライアントを再起動してください。

利用可能なツール

サーバーはスキャン結果をメモリにキャッシュするため、後続のツール呼び出しは高速です。再スキャンを強制するには analyze_codebase に refresh: true を渡してください。

ロードマップ

• [x] .cursor/rules/sourcebook.mdc + レガシー .cursorrules 出力

• [x] .github/copilot-instructions.md 出力

• [x] sourcebook update — 手動編集を保持しながら再分析

• [x] sourcebook diff — 変更内容の表示（CIフレンドリーな終了コード）

• [x] --budget <tokens> — PageRankベースのスマートな優先順位付け

• [x] リバートされたコミットや削除されたファイルからのアンチパターン検出

• [x] Pythonサポート (Django, FastAPI, Flask, pytest)

• [x] Goサポート (Gin, Echo, Fiber, モジュールレイアウト)

• [x] CI用GitHub Action

• [x] sourcebook serve — MCPサーバーモード

• [ ] フレームワークナレッジパック（コミュニティ提供）

• [ ] より深い規約検出のためのTree-sitter AST解析

• [ ] コンテキスト品質スコア付きのホスト型ダッシュボード

研究基盤

以下の研究成果に基づいています：

• ETH Zurich AGENTS.md study — 自動生成された明白なコンテキストはエージェントのパフォーマンスを低下させる

• Karpathy's autoresearch — キュレーションされたコンテキスト (program.md) はエージェントの有効性を高める最大のレバーである

• Aider's repo-map — 構造的な重要度を判断するためのインポートグラフ上のPageRank

• Chromaのコンテキスト陳腐化研究 — LLMはコンテキストの中間にある情報に対して30%以上の精度低下を示す

ライセンス

BSL-1.1 — ソース利用可能、無料で使用可能ですが、ホスト型サービスとして提供することはできません。2030年3月25日にMITライセンスに移行します。詳細は LICENSE を参照してください。