工程實踐

工程實踐

CodeMind Graph 的設計哲學與工程標準：AI-native workflow、local-first processing、deterministic knowledge graph 與唯讀 MCP integration。

工程實踐

AI 原生、在地優先的工程標準

CodeMind Graph 把結構化 context 視為一級工程產物。產品核心建立在 deterministic graph、隱私優先的本機處理，以及唯讀 Agent integration 之上。

AI-first Development

Repository 同時為 Agent 與人類設計：指令輸出必須 deterministic、可 diff，且 context 必須結構化。

Local-first Processing

Source analysis 在開發者本機執行。除非專案擁有者明確發布 public demo，否則 graph data 不離開本機。

Privacy-first Architecture

MCP tools 預設唯讀，不暴露 session notes、私有 docs、環境變數，也不提供寫入操作。

Source of Truth Management

透過 persisted graph、Repo Map 與 docs-as-state，讓長期工程 session 能被 resume、review 與 audit。

架構

架構標準

v0.1 架構以 TypeScript Compiler API adapter、deterministic core graph model、CLI-first query surface 與 read-only MCP server 為核心。

Knowledge Graph Runtime將 files、modules、symbols、imports、exports 與 traces 建模為穩定 nodes 與 edges。
AI-native Workflow在 Agent 行動前，讓 Implementer、Evaluator 與 Reviewer 共享同一份結構化 context。
Persistent Context System以 generated repo map 與 project state docs 作為 long-running engineering session 的 handoff artifacts。
Graph-based Code Intelligence在架構任務中，優先使用 deterministic symbol navigation，而不是近似的 raw-file prompting。

標準

操作標準

Deterministic Output

Index、find、trace、map 與 MCP responses 必須足夠穩定，才能支援 tests、review 與 diff。

Read-only Agent Boundary

MCP server 可以取回 graph context，但不能編輯檔案、執行 shell、安裝 package 或洩漏 secrets。

Agent-friendly Context Design

公開產品內容可以解釋 graph model，但不得發布私有 `.codemind/` data 或工程記憶文件。

Quality Gate

影響網站、graph query 或 MCP protocol 的變更，必須通過對應 build、test 與 browser QA workflow。

為什麼需要 CodeMind Graph

AI Coding Agent 需要的不只是原始檔案

大型 Repository 會快速耗盡 context window，架構關係也常被檔案樹掩蓋。CodeMind Graph 把程式碼結構轉成可持久保存的知識層，讓人類與 Agent 都能穩定查詢。

現有限制

Context window 會碎片化

模型可以讀取少量檔案，但在長期工程任務中，很難穩定維持完整依賴與架構脈絡。

單純 RAG 不夠確定

相似度搜尋能協助探索，卻無法保證符號歸屬、import path 與 module boundary 的 deterministic 關係。

專案記憶容易漂移

如果決策、Repo Map 與交接狀態沒有與目前 graph 對齊，Agent resume 後很容易依賴過期資訊。

CodeMind Graph 解法

Knowledge Graph

把檔案、模組、符號、imports、exports 與 trace 轉為可定位的 graph entities，而不是鬆散文字片段。

Local-first Runtime

Repository intelligence 在本機產生並保存於 `.codemind/`，兼顧隱私、資料主權與低延遲查詢。

Persistent Engineering Memory

Repo Map 與唯讀 MCP tools 讓 Agent 跨 session 保持穩定上下文，同時不暴露私有工程筆記。

品牌定位

CodeMind Graph 不是另一層文件工具

CodeMind Graph 為大型 Repository、AI Agent 與長期工程開發而設計，結合 graph-driven code intelligence 與 local-first safety。

不是
  • 不是單純文件工具
  • 不只是向量資料庫
  • 不是 raw RAG wrapper
而是
  • AI-native code knowledge graph
  • Local-first repository intelligence layer
  • 支援長期 Agent 的 graph-driven context system