用 Codegraph 给 AI 编码助手装上“记忆地图”，省 80% 无意义调用

你有没有遇到过这种情况：用 Cursor 或 Claude Code 问一句“用户登录逻辑在哪里”，AI 先调用 grep 满项目搜一遍，再打开五六个文件读内容，最后才憋出两句回答。对，至少几百 token 的上下文就这么浪费掉了。

developer frustrated with slow AI responses, code editor with long file list

今天分享一个实战 Skill：用 Codegraph（一个开源本地代码知识图谱工具）给你的 AI 编码助手预先建好项目地图。它能让 AI 在回答问题时，直接命中你要的关键函数和类，而不用每次都翻遍整个仓库。

1. 这个 Skill 解决什么具体问题

核心痛点：工具调用次数多、上下文 token 浪费。

现代 AI 编码助手（Claude Code、Codex、Gemini Code Assist、Cursor 等）在回答项目级问题时，通常需要：

  1. 遍历文件目录 → 2. 搜索关键词 → 3. 打开匹配文件 → 4. 读完整代码 → 5. 判断是否相关。

每一步都产生工具调用和 token 消耗。如果在 5 万行项目的根目录问“哪个函数处理用户注册”，AI 可能调用 10+ 次工具，消耗 20k+ token。

实际情况是，我们不需要每段代码的全部细节——只需要知道函数签名、文件位置、依赖关系这些元信息就够了。

Codegraph 的方案：在开发前（或 CI 中）用一次扫描生成项目的结构化索引（JSON / Markdown），此后 AI 助手只需要加载这个索引摘要（通常 < 2000 token），就能快速定位代码，再按需读取单个文件即可。工具调用次数从 >10 次降到 1-2 次。

2. 触发条件和适用场景

触发条件

  • 你拥有一个代码仓库（本地或可访问的 Git 项目）。
  • 你使用支持“读取文件”或“执行命令”的 AI 编码工具（Claude Code、Cursor、Codex、Gemini Code Assist、OpenCode、AntiGravity、Kiro、Hermes Agent 等）。
  • 项目规模 > 200 个文件，或者结构复杂（多模块、多语言混用）。

适用场景

  • 新成员接手老项目：不需要人花一周熟悉代码，直接问 AI，AI 用知识图谱快速回答。
  • 重构前的全局分析：查看所有导出函数、依赖关系，评估影响范围。
  • 减少 Token 开销：团队用 AI 辅助编码频繁但预算有限，压缩每次对话的消耗。

不适用的场景

  • 超小型项目（<50 个文件，或者单个文件大于 2000 行）：直接传整个文件更简单。
  • 频繁变动的开发分支（每天几十次提交）：图谱需要频繁同步，维护成本高。

3. 完整 Skill 结构（SKILL.md 示例）

以下是一个可直接复制使用的 Skill 定义文件。将其放在项目根目录 .ai/skills/ 下，适用于 Claude Code 等支持 Skills 的工具。

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 
# SKILL: codegraph-quick

## Trigger
用户提到以下关键词时激活：
- 代码图谱 / codegraph
- 项目结构 / project map
- 查找函数 / find function / find class
- 依赖关系 / dependency

## Description
利用预生成的 codegraph 索引（`codegraph.json` 或 `CODERAG.md`）快速定位代码元素，避免全量文件扫描。

## Instructions

### 第一步：检查图谱是否存在
如果当前工作目录下存在 `codegraph.json` 或 `CODERAG.md`，直接使用。
否则提示用户运行：
```bash
npx codegraph init

（会生成 codegraph.json 和可选的 CODERAG.md 摘要文件）

第二步：加载图谱摘要

如果已有 CODERAG.md，直接读取该文件（通常 < 2000 token）。
否则读取 codegraph.json（更大，约 5-10k token），由你按需过滤关键信息。

第三步：基于图谱回答问题

  • 用户问“获取用户列表的 API 在哪里？” → 搜索图谱中的 get_users 或 /users 端点定义，提取文件路径和行号。
  • 用户问“UserController 依赖哪些服务？” → 从图谱中查找 UserController 的依赖项并列出。

第四步：按需读取具体文件

只打开图谱定位到的确切文件行，而不是全文件搜索。

Variables

  • $QUERY：用户的自然语言问题
  • $GRAPH_FILE：图谱文件路径（默认 codegraph.json）
    ```

4. 实际案例演示

差 Prompt（直接在 Cursor 里问）

text
1 
“我项目里有个函数叫 `processPayment`，它在哪里？”

效果：Cursor 会调用 grep -r "processPayment" . 搜索，然后打开匹配的每个文件，再读取内容。假设匹配了 5 个文件，每个文件读 200 行 → 至少 6 次工具调用，token 消耗约 8000。

好 Prompt（基于 codegraph）

text
1 
“根据 codegraph 知识图谱，帮我找出 `processPayment` 函数所在的文件、行号、参数类型和调用者列表。图谱文件是 CODERAG.md。”

效果：AI 读取 CODERAG.md（一次工具调用，2000 token），从中查找 processPayment，立即返回：

  • 文件：src/payment/processor.ts，第 42 行
  • 参数：(amount: number, currency: string) => void
  • 调用者：checkoutService.ts:88、refundHandler.ts:15
  • 共计 1 次工具调用，token 约 2500。

side-by-side comparison of tool call counts and token usage: left (6 calls, 8000 tokens) vs right (1 call, 2500 tokens)

为什么这样写有效

Codegraph 的工作原理决定了它的高效：

  1. 使用 Tree-sitter 解析语法：而不是简单的正则或 grep。Tree-sitter 能精确识别函数、类、接口、导入导出、注释等。生成的 JSON 结构包含每个符号的准确位置、类型和依赖。
  2. 索引的压缩比极高：一个 10 万行 TypeScript 项目的完整 codegraph.json 约 500-800 KB（文本），但经过摘要的 CODERAG.md 只有 15-30 KB，且覆盖所有公开符号。对 LLM 来说，30 KB 相当于 7500 token，只有项目总代码的 1/10 甚至更少。
  3. 减少工具调用 = 减少延迟：每个工具调用在 Claude Code 中平均需要 1-2 秒（包括解析、执行、回传）。从 6 次降到 1 次，节省 5-10 秒响应时间。

你可能会说：“那我直接把整个 codegraph.json 传进去当上下文不就好了？” 这确实可行，但要注意：token 预算会被占用。更好的做法是让 AI 按需查询图谱文件中的关键部分。上面 Skill 里我选择先用 CODERAG.md 做摘要，然后只在需要时才读取完整 JSON 的特定条目。

5. 变体与扩展用法

变体 1：与 MCP 服务器集成

Codegraph 提供了 MCP（Model Context Protocol）服务器，支持动态查询。你可以为 Claude Desktop 或 Cline 等配置一个 MCP 工具“query-codegraph”，AI 直接调用该工具查询函数定义、依赖关系，而不用自己解析 markdown。

配置方式（.claude/mcp.json）：

json
1 2 3 4 5 6 7 8 9 
{
  "mcpServers": {
    "codegraph": {
      "command": "npx",
      "args": ["-y", "@antigravity/codegraph-mcp", "--path", "."],
      "env": {}
    }
  }
}

然后 AI 可以直接说：“使用 codegraph MCP 查找 authenticate 的定义”。

变体 2：生成特定语言/模块的子图谱

如果项目是微服务架构，可以只为某个服务生成图谱：

bash
1 
npx codegraph init --src services/auth --out auth-codegraph.json

然后在对话中只引用这个子图谱，减少无关噪音。

变体 3：与 CI/CD 流程联动

在 CI 中每个 PR 自动更新图谱，并 diff 检查是否有破坏性变化（删除公共函数、修改导出签名）。

yaml
1 2 3 4 5 6 7 
# .github/workflows/codegraph.yml
- name: Generate codegraph
  run: npx codegraph init --output codegraph.json
- name: Diff with baseline
  run: |
    curl -o baseline.json https://.../latest-codegraph.json
    npx codegraph diff ./codegraph.json baseline.json

我的判断

Codegraph 不是必须的——对于小型项目或你完全熟悉的代码库，直接问 AI 也没问题。但当你的项目超过 50 个文件，或者你经常需要回答“某个函数在哪”“谁调用了我”这类问题，花 10 分钟设置 Codegraph 并配合上述 Skill，能明显提升 AI 应答的准确性和速度。

要注意的是：图谱需要同步。如果你的项目在快速迭代，每 5 分钟就改一次代码，那么图谱很快就会过时。我建议至少在每个功能分支提交前重新生成一次图谱，或者干脆在 pre-commit hook 中自动化。

另一个常见误区：不要把整个 codegraph.json 塞给 AI 作为固定上下文。这会浪费大量 token 位置给不常用的定义。更好的做法是像 Skill 里写的那样，只加载摘要（CODERAG.md），让 AI 按需从完整图谱中提取细节。

直接可用的 Prompt 模板

以下是一个针对 Claude Code 的完整 prompt，你可以直接复制到会话开头：

text
1 2 3 4 5 6 7 8 9 10 11 
你正在使用 Codegraph 预索引的知识图谱辅助编码。图谱文件位于项目根目录的 `CODERAG.md`。

请先读取 `CODERAG.md`，了解项目中所有公开的类、函数、方法和全局变量。

之后，对于我提出的每个关于代码位置、依赖关系、函数定义的问题，请按以下步骤回答：
1. 在 `CODERAG.md` 中找到目标符号。
2. 返回它的完整文件路径、起始行号、参数签名（如适用）。
3. 如果问题涉及调用者/调用关系，也要一并列出。
4. 只有在需要查看具体实现时才打开对应的文件，否则依赖图谱摘要即可。

你可以根据图谱中的类型信息给出初步的分析。

把这个 prompt 和 SKILL.md 结合起来，你的 AI 编码助手就像有了一个内置的地图——不再迷路，不再绕远路。

a screenshot of Claude Code answering a question with file path and line numbers, showing low tool call count