Back to Details

code-graph

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Graph Skill

代码图技能

Purpose: Use the code graph (codebase-memory-mcp) for sub-millisecond symbol lookup, function search, dependency analysis, and blast radius detection. This replaces brute-force grep and file reading for code navigation.
用途： 使用代码图（codebase-memory-mcp）实现亚毫秒级的符号查找、函数搜索、依赖分析和影响范围检测。这替代了暴力grep和文件读取的代码导航方式。

Core Principle

核心原则

Graph first, file second. Before reading files or grepping, query the code graph. Only read full files when you need to modify them or need context beyond what the graph provides.
Consider graph when planning. When planning any change — feature, refactor, bug fix — start by querying the graph to understand scope, dependencies, and blast radius. This applies to thinking and planning phases, not just implementation. Grep is still the right tool for searching string literals, log messages, config values, and content that lives outside code structure.
┌────────────────────────────────────────────────────────────────┐
│  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.                          │
└────────────────────────────────────────────────────────────────┘
先查图，再读文件。 在读取文件或使用grep之前，先查询代码图。仅当需要修改文件或需要图中未提供的上下文时，才读取完整文件。
规划时考虑图的使用。 在规划任何变更——功能开发、重构、bug修复——时，先查询图以了解范围、依赖关系和影响范围。这适用于思考和规划阶段，而不仅仅是实现阶段。Grep仍然是搜索字符串字面量、日志消息、配置值和代码结构之外内容的合适工具。
┌────────────────────────────────────────────────────────────────┐
│  先查图，再读文件                                              │
│  ─────────────────────────────────────────────────────────────│
│  代码图将整个代码库索引为持久化知识图谱。Claude通过MCP查询它，以实现即时的│
│  符号查找、依赖链和影响范围检测——无需读取数百个文件。             │
│                                                                │
│  14种MCP工具 │ 64种语言 │ 亚毫秒级查询 │ 零依赖                  │
│  与暴力读取文件相比，导航所用令牌减少约99%                        │
├────────────────────────────────────────────────────────────────┤
│  自动更新                                                      │
│  ─────────────────────────────────────────────────────────────│
│  文件监视器保持图同步。提交后钩子确保                            │
│  图的新鲜度。无需手动重建。                                      │
└────────────────────────────────────────────────────────────────┘

When to Use Graph vs Direct Read

何时使用图工具 vs 直接读取文件

TaskUse Graph ToolUse Direct Read?
Find function/class definition
search_graph
No
Get function signature + docs
get_code_snippet
No
Find all callers of a function
trace_call_path
No
Trace dependency chain
query_graph
No
Determine blast radius of change
detect_changes
No
Understand project architecture
get_architecture
No
Search for code patterns
search_code
No
Read full implementation to modify
search_graph
to locate, then Read file		Yes
Understand business logic context
get_code_snippet
for overview, then Read		Yes
Rule: If a graph tool can answer the question, use it. Only open files when you need the full source to make edits.
任务使用图工具是否直接读取？
查找函数/类定义
search_graph
否
获取函数签名+文档
get_code_snippet
否
查找函数的所有调用者
trace_call_path
否
追踪依赖链
query_graph
否
确定变更的影响范围
detect_changes
否
理解项目架构
get_architecture
否
搜索代码模式
search_code
否
读取完整实现以进行修改
search_graph
定位，然后读取文件		是
理解业务逻辑上下文
get_code_snippet
获取概述，然后读取		是
规则： 如果图工具可以回答问题，就使用它。仅当需要完整源代码进行编辑时才打开文件。

Available MCP Tools

可用的MCP工具

Indexing & Status

索引与状态

ToolPurposeWhen to Use
index_repository
Build/rebuild graph for a projectFirst setup, or after major restructure
index_status
Check if graph is currentBefore querying, if unsure of freshness
list_projects
List all indexed projectsMulti-project navigation
工具用途使用场景
index_repository
为项目构建/重建代码图首次设置，或重大重构后
index_status
检查代码图是否为最新状态查询前不确定图的新鲜度时
list_projects
列出所有已索引的项目多项目导航时

Querying & Navigation

查询与导航

ToolPurposeWhen to Use
search_graph
Find symbols by name (fuzzy)"Find auth-related functions"
search_code
Text search across indexed codebase"Find TODO comments", pattern matching
get_code_snippet
Get source code for a specific symbolNeed signature, docstring, implementation
get_graph_schema
Understand graph structure and relationshipsExploring what data is available
query_graph
Run structured graph queriesComplex dependency/relationship queries
工具用途使用场景
search_graph
按名称模糊查找符号"查找与认证相关的函数"
search_code
在已索引代码库中进行文本搜索"查找TODO注释"、模式匹配
get_code_snippet
获取特定符号的源代码需要签名、文档字符串、实现细节时
get_graph_schema
了解代码图的结构和关系探索可用数据时
query_graph
运行结构化图查询复杂的依赖/关系查询时

Analysis

分析

ToolPurposeWhen to Use
trace_call_path
Trace caller/callee chains"Who calls sendEmail?", "What does init() trigger?"
detect_changes
Identify changed files and blast radiusBefore/after code changes, PR review
get_architecture
High-level module/package structureOnboarding, understanding project layout
工具用途使用场景
trace_call_path
追踪调用者/被调用者链"谁调用了sendEmail？"、"init()触发了什么？"
detect_changes
识别变更文件和影响范围代码变更前后、PR评审时
get_architecture
获取高层次模块/包结构新员工入职、理解项目布局时

Management

管理

ToolPurposeWhen to Use
delete_project
Remove a project from the graphCleanup, project restructure
manage_adr
Architecture decision recordsDocument architectural decisions
ingest_traces
Import runtime tracesPerformance analysis, dead code detection
工具用途使用场景
delete_project
从代码图中移除项目清理、项目重构时
manage_adr
架构决策记录记录架构决策时
ingest_traces
导入运行时追踪数据性能分析、死代码检测时

Workflow: Before Any Code Change

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

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
Step 0 applies to planning, not just coding. When the user asks you to plan a feature, refactor, or fix — query the graph first to understand what exists, what depends on what, and what the scope looks like. This prevents plans based on wrong assumptions about the codebase.
Never skip step 3. Blast radius analysis prevents unexpected breakage from changes to shared code.
0. 规划       → 使用get_architecture + search_graph在规划前了解范围
1. 定位       → 使用search_graph查找符号
2. 理解       → 使用get_code_snippet获取上下文
3. 影响范围   → 使用detect_changes评估影响
4. 追踪       → 使用trace_call_path查找所有受影响的调用者
5. 变更       → 读取文件，进行编辑
6. 验证       → 再次使用detect_changes确认范围
步骤0适用于规划，而非仅编码阶段。 当用户要求你规划功能、重构或修复bug时——先查询代码图，了解现有内容、依赖关系和范围。这能避免基于对代码库错误假设的规划。
永远不要跳过步骤3。 影响范围分析可防止共享代码变更导致意外故障。

Graph Data & Freshness

图数据与新鲜度

The graph stays fresh automatically through 3 layers — no manual rebuild needed:
LayerTriggerWhat Happens
File watcherEvery file savecodebase-memory-mcp detects changes and re-indexes affected files in real-time
Auto-indexSession start
auto_index: true
ensures graph is current when Claude Code starts
Post-commit hookEvery 
git commit
Touches 
.code-graph/.needs-update
marker — file watcher picks it up (~10ms, non-blocking)
You do NOT need to manually re-index unless you do a major restructure (rename entire directories, switch branches with massive diffs). In that case: 
index_repository
once, then the 3 layers keep it fresh.
  • Storage: 
    .code-graph/
    directory (auto-created, gitignored)
  • MCP config: 
    .mcp.json
    at project root (committed, shared with team)
代码图通过三层机制自动保持新鲜——无需手动重建：
层级触发条件操作内容
文件监视器每次文件保存codebase-memory-mcp检测变更并实时重新索引受影响的文件
自动索引会话启动
auto_index: true
确保Claude Code启动时图是最新的
提交后钩子每次
git commit
标记
.code-graph/.needs-update
——文件监视器会检测到它（约10ms，非阻塞）
除非进行重大重构（重命名整个目录、切换差异巨大的分支），否则无需手动重新索引。 这种情况下：运行一次
index_repository
，之后三层机制会保持图的新鲜度。
  • 存储：
    .code-graph/
    目录（自动创建，已加入git忽略）
  • MCP配置：项目根目录的
    .mcp.json
    （已提交，团队共享）

MCP Configuration

MCP配置

The code graph MCP server is configured in 
.mcp.json
at project root:
json
{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": []
    }
  }
}
Installation: 
~/.claude/install-graph-tools.sh
代码图MCP服务器在项目根目录的
.mcp.json
中配置：
json
{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": []
    }
  }
}
安装： 
~/.claude/install-graph-tools.sh

Decision Framework

决策框架

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
需要查找符号/函数？
  → 使用search_graph（亚毫秒级，结构化结果）
  → 不要使用：grep -r "functionName"（缓慢，非结构化）

需要理解依赖关系？
  → 使用query_graph或trace_call_path（完整，可遍历）
  → 不要使用：手动读取导入语句

需要评估变更影响？
  → 使用detect_changes（全面，即时）
  → 不要使用：手动跨文件搜索用法

需要理解架构？
  → 使用get_architecture（高层次概述）
  → 不要使用：读取每个目录列表

需要读取/修改代码？
  → 使用search_graph定位，然后读取特定文件
  → 不要使用：读取整个目录试图找到目标

Anti-Patterns

反模式

Anti-PatternDo This Instead
Grepping for function names
search_graph
with the function name
Reading entire files to find a signature
get_code_snippet
for the specific symbol
Manually tracing import chains
trace_call_path
or 
query_graph
Making changes without checking impact
detect_changes
before every edit to shared code
Reading all files in a directory
get_architecture
for structure, 
search_graph
for specifics
Ignoring graph staleness warningsCheck 
index_status
, re-index if needed
Re-indexing on every queryTrust the file watcher; only manual re-index after major restructure
反模式正确做法
用grep搜索函数名使用
search_graph
搜索函数名
读取整个文件以查找签名使用
get_code_snippet
获取特定符号
手动追踪导入链使用
trace_call_path
或
query_graph
未检查影响就进行变更在修改共享代码前使用
detect_changes
读取目录中的所有文件使用
get_architecture
了解结构，
search_graph
查找细节
忽略图过期警告检查
index_status
，必要时重新索引
每次查询都重新索引信任文件监视器；仅在重大重构后手动重新索引