コードプロジェクトブレイン（CPB）

コードリポジトリと同期して成長するプロジェクトレベルのセカンドブレイン。 開発ガイド（最優先コンテキスト）がCodeGraph（事実）と Project KB（消化された知識）の上に位置し、Claude Code用のタスク固有コンテキストに コンパイルされます。また、管理された変更→提案ループにより、 AIが静かに書き換えることなく知識の正確性を維持します。

CPBはv3.0設計を実装しています。開発 ガイドは第一の市民です。エージェントが最初に読み込むプロジェクトのメンタルモデルです。 コンテキストコンパイラが固定順序ガイド→KB→CodeGraphでContextPlanを組み立てます。 コンセプトハブがcanonical_idで3つのドメインをリンクし、コードアンカーレイヤーが ガイドをコードに対して正直に保ちます。

Development Guide (context / first-class)
        │  describes / governs (via Concept hub)
        ▼
CodeGraph (facts)  ·  Project KB (digested knowledge)
        └──────────────► Context Compiler ► Claude Code
Change → Impact → (Guide stale?) → Guide Proposal → Validate → Approve → Apply

初めての方へ？ docs/OVERVIEW.mdをお読みください。アーキテクチャ、 実装、設計上の選択、ロードマップの単一エントリーツアーです。 v2.0の履歴はUpdateGuide2.0.mdにあります。

3つのレイヤー（v3.0、update3.0 §1）

固定読み込み順序はガイド→KB→CodeGraphであり、逆はありません（§3）。

• 開発ガイド = コンテキスト — プロジェクトが何か、なぜこのように設計されているか、 従うべきルール。エージェントが最初に読み込むメンタルモデル。 guide/にスケルトン00-overview → 06-decisionsとして配置（§14）。

• CodeGraph = 事実 — tree-sitterによってSQLiteグラフ（WAL + FTS5）に解析されたコード。 シンボルと呼び出し/参照エッジ。ガイドのコードアンカーを検証するグラウンドトゥルースアダプター（§9）。WHAT IS。

• Project KB = 知識 — 消化された要件/バグ/決定（ADR）/外部ソース/教訓。 ガイドの後にのみ到達する詳細な履歴レイヤー。WHAT WAS LEARNED。

コンセプトハブ（§21/§22）は、ガイドセクション、KBドキュメント、CodeGraph シンボルをcanonical_idでリンクするため、コード変更は symbol → concept → guide sectionをトレースし、ガイドの陳腐化をフラグできます。

Related MCP server: project-context-map-mcp

管理されたループ（§11/§13/§24）

コードまたはKBの変更がガイドを静かに編集することはありません。代わりに：

Change → Impact → Concept impact → Guide stale? → Guide Proposal (draft)
      → Validate → Approve → Apply

エンジンが提案し、人間（またはレビュアーとしてのClaude）が適用前に検証および承認します。 KB知識は、同じ管理された提案（§13 Knowledge Promotion）を通じてガイドに昇格できます。 cpb syncは保留中の提案をドラフトし、cpb proposals <id> --approve|…はそれらを処理します。

機能

• 開発ガイド — guide/ Markdown（スケルトンフロントマター+コードアンカー）をインデックス化し、 アンカーをCodeGraphに対して検証し、陳腐化したものをフラグします。

• CodeGraph — シンボル+エッジのファイルごとの増分同期。

• Project KB — 型付きフロントマターでproject-kb/ Markdownをインデックス化し、 kb_digestsにダイジェスト化、重複ダイジェストの重複排除/マージ（§13）。

• コンテキストコンパイラ — cpb context "<task>" → ContextPlan（ガイド→KB →コード、プログレッシブディスクロージャーレベル0-6、トークンバジェット）（§18）。

• インパクトエンジン — ブラスト半径+影響を受ける制約/決定および 影響を受けるコンセプト/ガイドセクション（§22）。

• コンセプトハブ — Guide / KB / CodeGraphをリンクするcanonical_id（§21）。

• Claude Codeスキル — 8つのワークフロー：/project-init、 /project-context、/project-feature、/project-impact、 /project-update-docs、/project-review、/project-knowledge、 /project-sync。

技術

Node/TypeScript、node:sqlite（組み込み、WAL+FTS5、Node ≥ 22）、 web-tree-sitter（C/C++/TS/JS/Python/Rust/Go/Java用WASMグラマー）。ネイティブビルドなし、 ベクターDBなし（設計上、§19）。エンジンv3.0.0 / プロトコル2。

クイックスタート

# inside a code repository
cpb init        # create .project-brain/ + guide/ + project-kb/
cpb index       # build codegraph + knowledge + guide + concepts + git
cpb status      # summary: engine/protocol/guide sections/stale anchors
cpb context FrameQueue        # ContextPlan (Guide → KB → CodeGraph)
cpb concept camera/capture-pipeline   # the Concept hub: 3-domain graph
cpb guide list               # the Guide skeleton (Level 0)
cpb guide validate           # Guide well-formedness (§17 validator)
cpb impact FrameQueue         # blast radius + affected concepts/guide
cpb kb dedup                  # find duplicate KB digests (§13); --apply to merge
cpb sync                      # detect changes → draft Guide/Update proposals
cpb proposals                 # list / validate / approve / apply proposals

セルフホスト

CPBは自身のソースと同梱のguide/ + project-kb/をインデックス化します：

git init && cpb init && cpb index && cpb status

MCP（AIインターフェース）

CPBは名前空間付きMCPツールを公開します。唯一のAIインターフェースです：

• code.* — code.search code.symbol code.callers code.callees code.dependencies code.impact

• docs.* — docs.get docs.search docs.related docs.constraints docs.validate docs.apply

• kb.* — kb.search kb.requirement kb.bug kb.decision kb.reference kb.ingest kb.promote kb.digest kb.promote-guide kb.dedup

• guide.* — guide.index guide.section guide.stale guide.validate

• concept.* — concept.graph concept.forSymbol

• project.* — project.context project.impact project.changes project.sync project.proposals project.status

インストール設定と完全なツールリファレンスはUSAGE.mdを参照してください。

Claude Codeプラグインとして

CPBはClaude Codeプラグイン（cpb-claude-plugin/）として提供され、 エンジン上のアダプターレイヤーです。エンジン（このリポジトリ、cpb/cpb-mcp CLI）は スタンドアロンランタイムのままで、プラグインはnpmインポートではなくMCPプロトコルを介して バインドします。これによりエンジンは独立して進化できます。根拠は docs/plans/archi.md、完全なインストール手順は cpb-claude-plugin/README.mdを参照してください。

# 1. Engine on PATH (once)
npm install -g @cpb/engine        # or: npm link  (from this repo)

# 2. In Claude Code
/plugin marketplace add /path/to/CPB
/plugin install cpb@cpb

次に/cpb:status、/cpb:context、/cpb:sync、… — またはタスクを説明するだけで スキルが自動的にアクティブになります。

デモプロジェクト

demo-src/camera/は小さなC++カメラパイプライン（CameraDevice → FrameQueue → VideoEncoder）で、完全なv3.0ドキュメントセット — guide/ （概要+アーキテクチャ+制約+ADR）とproject-kb/（ADR、 要件、バグ、教訓、外部V4L2/FFmpegノート、テスト証跡）を備えています。 ドッグフーディングです。CPBはインデックス化、探索、ドリフトチェック、変更→提案 ループの実行を行います。

レイアウト

src/
  core/        types (domain model: Guide/Concept/ContextPlan + structured objects)
  db/          sqlite adapter + schema.sql + migrate.ts (versioned migrations)
  engine/
    codegraph/  tree-sitter extractor, grammars, parser, orchestrator, queries
    guide/      Development Guide: indexer, anchor, query, validator (§17)
    concept/    Concept hub: index + query (§21)
    knowledge/  KB: frontmatter, indexer, recall, freshness, entities, external, ingestion, promotion, dedup
    docs/       structured reads: constraints, decisions (Guide-seeded)
    git/        commit index + ADR mining + gitDiff
    impact/     blast radius + affected knowledge/concepts/guide (§22)
    context/    Context Compiler (§18) + builder (v2, cpb explain) + explain/explore
    sync/       semantic-diff, changeset, proposal, pipeline (change→proposal loop)
  mcp/         namespaced MCP tools (code.*/docs.*/kb.*/guide.*/concept.*/project.*) + stdio server
bin/cpb.ts      CLI
guide/          CPB's own Development Guide (self-hosted, v3.0 skeleton)
cpb-claude-plugin/  the Claude Code adapter (skills + commands + MCP declaration)

設計上の境界（§19/§23/§25による）

構築されないもの：すべてのドキュメントの自動書き換え、すべての知識の自動生成、ベクター/ 埋め込み検索（§19 — ローカルファースト、SQLite+FTS5）、完全なIDE、または エンタープライズ知識グラフ。エンジンはLLMを埋め込むことはありません（§29）— ClaudeはMCPを介して思考し、エンジンは事実と状態機械を保持します。知識は 人間が管理します（§11/§14）。ガイドは管理された資産です。すべての編集は 提案を通過します。コードが最高の真実の源です（§9）。

ライセンス

MIT。