Code Project Brain (CPB)

코드 저장소와 동기화되어 성장하는 프로젝트 수준의 세컨드 브레인(second brain)입니다. Development Guide(일급 컨텍스트)가 CodeGraph(사실)와 Project KB(소화된 지식) 위에 자리하며, Claude Code용 작업별 컨텍스트로 컴파일됩니다 — AI가 결코 조용히 다시 쓰지 못하게 하면서 지식이 정확하게 유지되도록 하는 통제된 Change → Proposal 루프와 함께 제공됩니다.

CPB는 v3.0 설계를 구현합니다. Development Guide는 **일급 시민(first citizen)**입니다 — 에이전트가 가장 먼저 로드하는 프로젝트 멘탈 모델이죠. Context Compiler는 고정된 순서 Guide → KB → CodeGraph로 ContextPlan을 조립합니다. 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 = Context — 프로젝트가 무엇인지, 왜 이렇게 설계되었는지, 따라야 할 규칙. 에이전트가 가장 먼저 로드하는 멘탈 모델. guide/에 스켈레톤 00-overview → 06-decisions 구조로 위치합니다(§14).

• CodeGraph = Facts — tree-sitter가 파싱한 코드를 심볼과 호출/참조 엣지로 구성된 SQLite 그래프로 저장합니다(WAL + FTS5). Guide의 Code Anchor를 검증하는 Ground Truth Adapter입니다(§9). WHAT IS.

• Project KB = Knowledge — 소화된 요구사항 / 버그 / 결정(ADR) / 외부 소스 / 교훈. Guide 다음에 도달하는 상세하고 역사적인 계층. WHAT WAS LEARNED.

Concept hub(§21/§22)는 Guide 섹션, KB 문서, CodeGraph 심볼을 canonical_id로 연결하므로, 코드 변경 시 symbol → concept → guide section을 추적하고 Guide가 낡았음을 표시할 수 있습니다.

통제된 루프 (§11/§13/§24)

코드나 KB 변경은 Guide를 결코 조용히 수정하지 않습니다. 그 대신:

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

엔진이 **제안(propose)**합니다. 사람(또는 리뷰어로서의 Claude)이 적용 전에 검증하고 승인합니다. KB 지식은 동일한 통제된 제안 절차를 통해 Guide로 **승격(promote)**될 수 있습니다(§13 Knowledge Promotion). cpb sync는 대기 중인 제안의 초안을 만들고, cpb proposals <id> --approve|…는 이를 처리합니다.

하는 일

• Development Guide — guide/ Markdown을 인덱싱하고(스켈레톤 frontmatter + Code Anchor), CodeGraph를 기준으로 Anchor를 검증하며, 낡은 Anchor를 플래그로 표시합니다.

• CodeGraph — 심볼 + 엣지의 파일별 증분 동기화.

• Project KB — 타입이 지정된 frontmatter가 있는 project-kb/ Markdown을 인덱싱하고, kb_digests로 소화하며, 중복 다이제스트를 중복 제거/병합합니다(§13).

• Context Compiler — cpb context "<task>" → ContextPlan 생성(Guide → KB → Code, Progressive Disclosure 레벨 0-6, 토큰 예산 적용)(§18).

• Impact Engine — 영향 범위(blast radius) + 영향을 받는 제약/결정 그리고 영향을 받는 개념 / Guide 섹션(§22).

• Concept hub — Guide / KB / CodeGraph를 연결하는 canonical_id(§21).

• Claude Code Skills — 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 / 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

셀프 호스트

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는 Engine 위의 어댑터 계층인 Claude Code 플러그인(cpb-claude-plugin/)으로 제공됩니다. Engine(이 저장소의 cpb/cpb-mcp CLI)은 독립 실행형 런타임으로 유지되고, 플러그인은 npm import가 아닌 MCP 프로토콜로 바인딩됩니다 — 따라서 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/는 완전한 v3.0 문서 세트를 갖춘 소규모 C++ 카메라 파이프라인입니다(CameraDevice → FrameQueue → VideoEncoder) — guide/(개요 + 아키텍처 + 제약 하나 + ADR 하나)와 project-kb/(ADR, 요구사항, 버그, 교훈, 외부 V4L2/FFmpeg 메모, 테스트 증거). CPB의 도그푸딩(dogfood) 대상입니다. 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)

설계 경계 (§19/§23/§25 기준)

구현하지 않는 것: 모든 문서 자동 재작성, 모든 지식 자동 생성, 벡터/임베딩 검색 (§19 — 로컬 우선, SQLite+FTS5), 완전한 IDE, 또는 엔터프라이즈 지식 그래프. 엔진은 LLM을 절대 내장하지 않습니다(§29) — Claude는 MCP를 통해 사고하고, 엔진은 사실과 상태 머신을 보유합니다. 지식은 인간의 통제 하에 유지됩니다(§11/§14). Guide는 통제되는 자산이며 — 모든 편집은 Proposal을 거칩니다. 코드가 최고의 진실 원천(source of truth)입니다(§9).

라이선스

MIT.