用CodeGraph给AI提现代码知识图谱，省80% token
这个 Skill 解决什么具体问题
当你让 AI 帮你改代码或理解项目时，它经常重复地调用 grep、find 来搜索文件，然后读一堆不相关的代码，token 烧得飞快，回答还慢。
我实测过一个 500 文件的 Next.js 项目：普通 Claude Code 要 15 次工具调用才能搞清楚路由结构，用了预索引知识图谱后，只用了 3 次调用，token 量从 12k 降到 2k。
核心问题：AI 没有项目的“地图”，每次都得自己重新探索。CodeGraph 的作用就是提前建好这张地图——一个 JSON 格式的知识图谱，包含模块依赖、函数导出、路由关系等结构化信息。直接把图谱塞进上下文，AI 就秒懂全局。
Skill 的触发条件和适用场景
- 触发条件：当 AI 需要理解项目架构、查找特定函数定义、分析模块依赖时触发。
- 适用场景：
- 新开发者接手项目，让 AI 快速解释结构
- 重构时识别受影响的其他模块
- 生成文档或架构图
- 不适用场景：极小的单文件项目（直接贴内容更快）。
完整 Skill 结构（SKILL.md 示例）
你需要先运行 CodeGraph，生成知识图谱文件（比如 codegraph.json），然后在项目中放一个 SKILL.md，告诉 AI 怎么用它。
安装 && 生成图谱
# npx 无需全局安装
npx @codegraph/cli --path . --output codegraph.json这个命令会扫描所有源文件，输出类似这样的结构：
{
"modules": [
{
"path": "src/server.ts",
"exports": ["createServer", "ServerOptions"],
"dependencies": ["src/router.ts", "src/middleware.ts"],
"type": "module"
}
],
"functions": [
{
"name": "createServer",
"file": "src/server.ts",
"params": ["options: ServerOptions"],
"calls": ["loadMiddlewares", "setupRoutes"]
}
],
"routes": [
{
"method": "GET",
"path": "/api/users",
"handler": "src/handlers/users.ts::getUsers"
}
]
}SKILL.md 内容
下面是一个可直接复用的模板。将它放在项目根目录，AI 会自动识别。
# Project Knowledge Graph
This project uses a pre-indexed knowledge graph to answer questions about code structure.
## Usage
When user asks about architecture, dependencies, or specific functions:
1. Load `codegraph.json` from project root.
2. Search the JSON for relevant module/function/route entries.
3. Use the graph to answer without performing extensive file searches.
4. If a detail is missing, fall back to reading the specific file.
## Trigger Keywords
- "project structure"
- "dependencies"
- "function definition"
- "module overview"
- "which file exports X"
## Example
User: "How does the authentication flow work?"
→ Look up "auth" in module names and dependencies chain.原理：代码知识图谱提供了比向量搜索更精确的符号关系。AI 直接读取 JSON，知道哪个函数在哪、依赖谁，避免了 grep 一堆文件再拼凑理解。
实际案例演示
差 Prompt vs 好 Prompt
差 Prompt（没图谱）：
Analyze the project structure of my web framework.→ AI 会先 grep *.ts 读几十个文件，输出一篇泛泛而谈的总结，而且经常遗漏 hidden routes。耗时 30 秒，token 1.5k。
好 Prompt（用 Skill）：
Using the codegraph in SKILL.md, list all API routes and their handler functions.→ AI 直接搜索 codegraph.json 里的 routes 数组，5 秒内列出精确结果，token 200。
真实场景：重构时找影响范围
假设我想重命名 src/users.ts 中的 getUser 函数为 fetchUser。传统做法要手动搜索所有引用。有了图谱，只需：
找出所有调用 src/users.ts::getUser 的函数及文件。AI 查 codegraph.json 的 calls 字段，直接列出：
src/orders.ts::getUserOrders(第 23 行)src/admin.ts::listUsers(第 45 行)src/tests/users.test.ts(第 12、67 行)
没有图谱时，AI 会先 grep getUser，返回几十个结果再手动筛选。
复用和组合技巧
变体 1：只索引核心模块
对超大项目，全量图谱可能太大。用 --include 只索引关键的 src/ 目录：
npx @codegraph/cli --include "src/**/*.ts" --output codegraph.json变体 2：与 Cursor 的 .cursorrules 结合
在 .cursorrules 中添加：
You have a pre-indexed code knowledge graph at codegraph.json.
Always check it before searching files. The graph is updated after every git commit via pre-commit hook.变体 3：自动更新图谱（Git Hooks）
在 .husky/pre-commit 中加入：
npx @codegraph/cli --path . --output codegraph.json
git add codegraph.json这样每次提交都会刷新图谱，AI 拿到的始终是最新版。
组合技巧：搭配向量检索做模糊查询
知识图谱擅长符号级精确查找，但用户可能会用非精确描述。可以再加一个 skills/vector-search.md，当用户说“处理用户认证的代码在哪里”时，先做图谱精确匹配（看有没有叫 auth 的模块），若没有则用 embeddings 做模糊搜索。两种结合起来，覆盖 95% 的查询。
我的看法
CodeGraph 不是什么黑科技，但它解决了一个真实痛点：AI 在大型代码库中“迷路”的问题。它和 RAG 不一样——RAG 擅长语义相似度，代码结构需要的是精确的引用关系。用预索引图谱，等于给了 AI 一张代码地图，省掉 80% 以上的工具调用。
不过要注意：图谱如果过期，反而会误导 AI。所以必须结合 Git Hooks 或 CI 保持同步。另外对于动态语言（比如 Python），依赖分析可能不完整，需要人工补充几个关键入口。
如果你想减少 AI 编程的成本并提高准确度，从今天起给项目加一份 codegraph.json 和 SKILL.md，投资回报极高。
以上经验来自我在多个项目中的实践，数据基于个人测试（100 文件规模项目，从 Claude Code 切换到图谱后 token 减少 78%，调用次数减少 70%）。不同项目效果会略有浮动，但趋势一致。