Code Project Brain (CPB)

Проектный «второй мозг», растущий синхронно с репозиторием кода. Development Guide (контекст первого класса) лежит поверх CodeGraph (факты) и Project KB (обработанные знания), компилируясь в контекст под конкретную задачу для Claude Code — с управляемым циклом Change → Proposal, который поддерживает корректность знаний, не позволяя ИИ молча переписывать их.

CPB реализует дизайн v3.0: Development Guide — первоочередная сущность — проектная ментальная модель, которую агент загружает первой. Context Compiler собирает ContextPlan в фиксированном порядке Guide → KB → CodeGraph; Concept hub связывает три области по canonical_id; слой Code Anchor не даёт Guide расходиться с кодом.

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.

Три слоя (v3.0, update3.0 §1)

Фиксированный порядок загрузки — Guide → KB → CodeGraph, никогда не наоборот (§3):

• Development Guide = Контекст — что такое проект, почему он спроектирован так и по каким правилам живёт. Ментальная модель, которую агент подгружает первой. Лежит в guide/ как скелет 00-overview → 06-decisions (§14).

• CodeGraph = Факты — код, разобранный tree-sitter в SQLite-граф символов и рёбер вызовов/ссылок (WAL + FTS5). Адаптер Ground Truth, который проверяет Code Anchors из Guide (§9). ЧТО ЕСТЬ.

• Project KB = Знания — проанализированные требования / баги / решения (ADRs) / внешние источники / уроки. Детальный исторический слой, доступ к которому открывается только после Guide. ЧТО УЗНАЛИ.

Concept hub (§21/§22) связывает разделы Guide, документы KB и символы CodeGraph через canonical_id, поэтому изменение кода способно проследить путь symbol → guide → guide section и пометить Guide устаревшим.

Управляемый цикл (§11/§13/§24)

Изменение кода или KB никогда молча не правит Guide. Вместо этого:

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

Механизм предлагает; человек (или Claude в роли рецензента) проверяет и утверждает до применения. Знания из KB могут быть повышены до Guide через тот же управляемый процесс (§13 Knowledge Promotion). cpb sync оформляет ожидающие предложения; cpb proposals <id> --approve|… выносит по ним решение.

Что он делает

• Development Guide — индексирует Markdown из guide/ (скелет frontmatter + Code Anchors), проверяет якоря через CodeGraph и помечает устаревшие.

• CodeGraph — пофайловая инкрементальная синхронизация символов и рёбер.

• Project KB — индексирует Markdown из project-kb/ с типизированным frontmatter; разбирает его на kb_digests; дедуп/merge дублирующихся дайджестов (§13).

• Context Compiler — cpb context "<task>" → ContextPlan (Guide → KB → Code, Progressive Disclosure Level 0-6, бюджет токенов) (§18).

• Impact Engine — взрывная зона + затронутые ограничения/решения, а также затронутые концепции / разделы Guide (§22).

• Concept hub — canonical_id, связывающий Guide / KB / CodeGraph (§21).

• Claude Code Skills — восемь рабочих процессов: /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 (WASM-грамматики для C/C++/TS/JS/Python/Rust/Go/Java). Без нативных сборок, без векторных БД (сознанное решение, §19). Движок v3.0.0 / protocol 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

Self-hosted

CPB индексирует собственный исходный код и входящие guide/ + project-kb/:

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

MCP (интерфейс для ИИ)

CPB подключается через MCP-инструменты с пространством имён — единственный интерфейс для ИИ:

• 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/) — адаптер из VSC over Engine. Engine (этот репозиторий, CLI cpb/cpb-mcp) остаётся отдельным рантаймом; плагин подключается через протокол MCP, а не npm-import, поэтому Engine может развиваться независимо. См. 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/ (обзор + архитектур + constraint + ADR) и project-kb/ (ADR, требование, баг, урок, внешние заметки V4L2/FFmpeg, тестовые данные). Он догфуд: CPB индексирует его, исследует, проверяет нет риль и запускает цикл change→proposal.

Структура

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)

Границы дизайна (per §19/§23/§25)

Не делаем: автоперезапись всех документов, автосоздание всех знаний, векторный / embedding-поиск (§19 — локальный-first, SQLite+FTS5), далеко идущий IDE или корпоративный граф знаний. Движок никогда не встаивает LLM (§29) — Claude думать через MCP; движок отвечает за факты и логику. Знания остаются под контролем человека (§11/§1б); Guide — управляемый актив: каждое изменение проходит через Proposal. Код является высшим источником истины (§9).

Лицензия

MIT.