code-graph

代码图谱技能

**用途：**使用代码图谱（codebase-memory-mcp）进行亚毫秒级符号查找、函数搜索、依赖分析和影响范围检测。它可取代繁琐的 grep 和文件读取，用于代码导航。

---

核心原则

**先查图谱，再看文件。**在读取文件或使用 grep 搜索之前，先查询代码图谱。只有在需要修改文件，或需要了解图谱无法提供的上下文时，才读取完整文件。

**规划时也要考虑图谱。**规划任何变更时——功能开发、重构、错误修复——都应先查询图谱，了解范围、依赖关系和影响范围。这不仅适用于实现阶段，也适用于思考和规划阶段。搜索字符串字面量、日志消息、配置值，以及代码结构之外的内容时，仍应使用 grep。

┌────────────────────────────────────────────────────────────────┐
│  GRAPH FIRST, FILE SECOND                                      │
│  ─────────────────────────────────────────────────────────────│
│  The code graph indexes your entire codebase as a persistent   │
│  knowledge graph. Claude queries it via MCP for instant         │
│  symbol lookup, dependency chains, and blast radius — instead   │
│  of reading hundreds of files.                                 │
│                                                                │
│  14 MCP tools │ 64 languages │ sub-ms queries │ zero deps      │
│  ~99% fewer tokens for navigation vs brute-force file reads    │
├────────────────────────────────────────────────────────────────┤
│  AUTO-UPDATED                                                  │
│  ─────────────────────────────────────────────────────────────│
│  File watcher keeps graph in sync. Post-commit hook ensures    │
│  freshness. No manual rebuild needed.                          │
└────────────────────────────────────────────────────────────────┘

---

何时使用图谱，何时直接读取

任务	使用图谱工具	需要直接读取吗？
查找函数／类定义	search_graph	否
获取函数签名和文档	get_code_snippet	否
查找函数的所有调用方	trace_call_path	否
追踪依赖链	query_graph	否
确定变更的影响范围	detect_changes	否
了解项目架构	get_architecture	否
搜索代码模式	search_code	否
阅读完整实现以进行修改	使用 search_graph 定位，然后读取文件	是
了解业务逻辑上下文	使用 get_code_snippet 获取概览，然后读取文件	是

**规则：**如果图谱工具能回答问题，就使用它。只有需要完整源码来进行修改时，才打开文件。

---

可用的 MCP 工具

索引与状态

工具	用途	使用时机
index_repository	为项目构建／重建图谱	首次设置，或重大重构后
index_status	检查图谱是否为最新	查询前，如果不确定图谱是否为最新
list_projects	列出所有已索引项目	跨项目导航

查询与导航

工具	用途	使用时机
search_graph	按名称查找符号（模糊搜索）	“查找与身份验证相关的函数”
search_code	在已索引代码库中进行文本搜索	“查找 TODO 注释”、模式匹配
get_code_snippet	获取特定符号的源代码	需要签名、文档字符串或实现时
get_graph_schema	了解图谱结构和关系	探索可用数据
query_graph	执行结构化图谱查询	复杂的依赖／关系查询

分析

工具	用途	使用时机
trace_call_path	追踪调用方／被调用方链	“谁调用了 sendEmail？”、“init() 会触发什么？”
detect_changes	识别变更文件及其影响范围	代码变更前后、PR 审查
get_architecture	高层模块／包结构	入门、了解项目布局

管理

工具	用途	使用时机
delete_project	从图谱中移除项目	清理、项目重构
manage_adr	架构决策记录	记录架构决策
ingest_traces	导入运行时追踪数据	性能分析、死代码检测

---

工作流：进行任何代码变更之前

0. PLAN       → get_architecture + search_graph to understand scope before planning
1. LOCATE     → search_graph to find the symbol
2. UNDERSTAND → get_code_snippet for context
3. BLAST      → detect_changes to assess impact
4. TRACE      → trace_call_path to find all affected callers
5. CHANGE     → Read file, make edit
6. VERIFY     → detect_changes again to confirm scope

**步骤 0 适用于规划，不仅限于编写代码。**当用户要求你规划功能、重构或修复时，先查询图谱，了解现有内容、依赖关系以及工作范围。这可以避免基于错误的代码库假设制定计划。

**绝不要跳过步骤 3。**影响范围分析可以防止共享代码的变更造成意外故障。

---

图数据与时效性

图会通过 3 层机制自动保持最新——无需手动重建：

层	触发条件	发生的操作
文件监视器	每次保存文件	codebase-memory-mcp 会实时检测更改并重新索引受影响的文件
自动索引	会话开始时	auto_index: true 可确保 Claude Code 启动时图数据保持最新
提交后钩子	每次 git commit	更新 .code-graph/.needs-update 标记——文件监视器会检测到它（约 10ms，非阻塞）

除非进行大规模重构，否则无需手动重新索引（例如重命名整个目录、切换到差异巨大的分支）。遇到这种情况时：运行一次 index_repository，之后由这 3 层机制保持数据最新。

• 存储：.code-graph/ 目录（自动创建，并加入 gitignore）
• MCP 配置：项目根目录下的 .mcp.json（提交到仓库，与团队共享）

---

MCP 配置

代码图 MCP 服务配置在项目根目录下的 .mcp.json 中：

{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": []
    }
  }
}

安装： ~/.claude/install-graph-tools.sh

---

决策框架

Need to find a symbol/function?
  → search_graph (sub-ms, structured result)
  → NOT: grep -r "functionName" (slow, unstructured)

Need to understand dependencies?
  → query_graph or trace_call_path (complete, traversable)
  → NOT: manually reading import statements

Need to assess change impact?
  → detect_changes (comprehensive, instant)
  → NOT: searching for usages manually across files

Need to understand architecture?
  → get_architecture (high-level overview)
  → NOT: reading every directory listing

Need to read/modify code?
  → search_graph to locate, then Read the specific file
  → NOT: reading entire directories hoping to find it

---

反模式

反模式	应改为
使用 grep 搜索函数名	使用函数名调用 search_graph
读取整个文件以查找签名	使用 get_code_snippet 获取特定符号
手动追踪导入链	使用 trace_call_path 或 query_graph
未检查影响就进行更改	每次修改共享代码前调用 detect_changes
读取目录中的所有文件	使用 get_architecture 查看结构，使用 search_graph 查找具体内容
忽略图数据过时警告	检查 index_status，必要时重新索引
每次查询都重新索引	相信文件监视器；只有大规模重构后才手动重新索引