Claude CodeGraph MCP 完整指南：代码图谱工具详解（替代与互补 Codebase-Memory）
在使用 Claude 处理大型项目时，几乎所有开发者都会遇到一个痛点：每次新开会话，AI 便会“失忆”——它完全忘记项目结构、函数定义位置以及模块间的依赖关系。过去我们只能将整个项目文件一股脑喂给 AI，但这样会导致上下文 Token 飙升，效率极低。CodeGraph 正是为解决这一难题而生的轻量级代码图谱工具，它让 AI 在动手编码前先掌握全局“地图”。
一、CodeGraph 是什么
codegraph 是目前主流的代码语义图谱 MCP 服务，专门为 Claude 提供项目全局的代码结构、调用关系与依赖链路检索能力。简单来说，它让 AI 在修改代码之前，先对整个项目的架构了如指掌。对于大中型仓库而言，这几乎是刚需。通常它与 Karpathy（编码约束）、Superpowers（需求拆解与测试）搭配使用，形成一套完整的 AI 编码工作流。
它与 Codebase-Memory 属于同类工具，但在底层实现、性能表现和用法上存在明显差异。下面先看它解决了哪些核心痛点：
- 新开会话后，AI 完全丧失对项目结构、函数调用和模块依赖的记忆
- 翻阅大量文件会消耗巨额上下文 Token
- 修改代码时无法预判全局影响，重构容易踩坑
- Monorepo、多包项目的架构梳理成本极高
二、CodeGraph vs Codebase-Memory 核心差异
| 对比项 | CodeGraph | Codebase-Memory |
|---|---|---|
| 底层解析 | Tree-sitter 高性能语法解析，启动速度快 | 自定义深度 AST 解析，索引更完整 |
| 索引速度 | 轻量增量索引，小仓库秒级建立 | 百万行项目索引耗时更长 |
| 资源占用 | 内存占用低，轻薄笔记本友好 | 存储图谱体积更大 |
| 擅长场景 | 日常查调用链、定位函数、快速架构概览 | 深度重构、跨模块影响分析、死代码扫描 |
| 生态 | 开箱即用，无额外缓存文件 | 自带本地持久化知识库 |
| 适用人群 | 日常开发、前端/中小型后端开发者 | 大型 Monorepo、长期复杂重构团队 |
选择建议其实很直接：
- 笔记本性能一般、项目中小型 → 优先选择 CodeGraph
- 百万行级大仓库、频繁重构、需要精准影响评估 → 选择 Codebase-Memory
- 追求极致工程流程：两者二选一，再搭配 Karpathy + Superpowers 形成完整工作流
三、CodeGraph 核心能力
1. 仓库全局索引
自动扫描主流语言：TS/JS/Go/Python/Java/C++/Vue/React
- 增量索引：只更新修改过的文件，无需全量重建
- 自动忽略
.git、node_modules、dist、build 等目录
2. 语义查询工具集
search_symbol：按函数/类/变量名全局检索定义位置find_references：查找该符号所有调用、引用、使用处get_call_graph：生成函数完整调用上下游链路list_modules：输出项目模块分层、依赖关系get_file_deps：分析单个文件导入/被哪些文件导入list_exports：查看文件导出的所有接口、类型、工具函数
3. 架构可视化分析
一键输出项目分层结构：
- 目录模块划分
- 公共工具层、业务层、接口层边界
- 第三方依赖与内部代码隔离边界
4. 变更风险预判
修改文件前自动分析：哪些业务模块依赖当前代码？改动会影响多少页面、接口、单元测试？配合 Karpathy 外科式修改规则，避免牵连无关代码。
四、两种部署方式（MCP 标准配置）
方式1：.mcp.json 全局/项目配置（推荐）
在项目根目录新建 .mcp.json，CodeGraph MCP 会自动加载：
{
"mcpServers": {
"codegraph": {
"command": "npx",
"args": ["@codegraph/mcp"]
}
}
}保存后重启 Claude Code 会话即可初始化。
方式2：Claude Code 插件命令安装
# 添加社区插件源
/plugin marketplace add codegraph/mcp
# 安装 codegraph 技能
/plugin install codegraph@codegraph/mcp
# 初始化索引
/codegraph:index五、常用内置指令
/codegraph:index # 全量构建代码图谱
/codegraph:reindex # 增量更新索引
/codegraph:refs funcName # 查询函数所有引用位置
/codegraph:callgraph funcName # 打印完整调用链路
/codegraph:deps src/xxx.ts # 查看文件上下游依赖
/codegraph:arch # 输出项目整体架构
/codegraph:search UserService # 全局搜索类/方法六、标准三件套组合工作流（Karpathy + CodeGraph + Superpowers）
- 需求输入 → Karpathy Guidelines：禁止脑补，先对齐需求，简约实现
- 熟悉项目上下文 → CodeGraph：查询架构、现有接口、历史实现逻辑
- 需求确认 → Superpowers brainstorming 输出方案，write-plan 拆分微任务
- 编码阶段：
- CodeGraph 实时查询依赖、调用链，预判修改风险
- Karpathy 约束仅做精准外科修改，不乱改无关代码
- Superpowers TDD 先写测试再编码
- 报错调试：CodeGraph 追踪异常链路 + systematic-debugging 系统化排错
- 收尾校验：CodeGraph 分析改动影响范围 + 全量测试、代码评审
七、使用场景建议
小型脚本、单文件工具：仅开启 Karpathy 即可，无需 CodeGraph，节省资源。
中小型前后端单体项目：标配三件套 — Karpathy + CodeGraph + Superpowers，轻量化不卡顿。
大型 Monorepo / 企业级仓库：可选升级为 Codebase-Memory 替代 CodeGraph，深度重构能力更强。
团队统一规范：统一提交以下文件到项目，确保团队 AI 编码行为一致：
- CLAUDE.md（Karpathy 编码约束）
- .mcp.json（CodeGraph MCP 配置）
- Superpowers 标准化开发流程
八、核心优势总结
- 轻量高性能：基于 Tree-sitter 语法树解析，启动和索引速度极快，低配电脑也能流畅运行
- 大幅节省 Token：结构化查询替代全文读取，有效避免上下文溢出
- 跨会话持久记忆：新开会话无需重复讲解项目结构、接口定义
- 本地离线运行：代码仅在本机解析，不上传云端，私有业务代码安全无忧
- 全栈适配：前端组件、路由、后端接口、模型层均可解析调用关系
