这个提示词解决什么问题

当你让 Claude 分析一个陌生的代码库时，常见做法就是一股脑扔进去全部源文件。结果 token 爆炸、工具调用疯狂、甚至直接超上下文窗口。CodeGraph 这个今天刚暴涨 1.7 万 star 的项目，把代码库预先索引成知识图谱（JSON 格式），只保留关键结构、依赖和类型签名。

但光有图谱还不够——你还得会写能让 AI 用起来的 prompt。下面这个模板就是我跟 CodeGraph 配合折腾出来的，实测能让 Claude 对中型项目（100+ 文件）的第一次理解从 8000+ token 降到 1500 左右。

核心思路

原理很简单：AI 读代码不需要所有行，它只需要知道什么模块干什么事、怎么依赖、暴露了什么接口。CodeGraph 生成的图谱恰好就是这些信息。你再配合一个结构化引导 prompt，告诉 AI 按模块逐步推理，就能让它像老手一样快速搞懂项目，而不必一个字一个字读源码。

完整提示词模板

你是一个经验丰富的代码审查专家。下面是一个项目的知识图谱（JSON格式），包含所有模块、类型签名、函数暴露和依赖关系。你的任务是快速理解项目架构，然后回答用户的问题。

### 项目图谱 JSON
<project_graph_json>
</project_graph_json>

### 分析步骤
1. 先扫描顶层模块，列出每个模块的职责（用一句话概括）。
2. 然后按照依赖方向（入口 → 核心 → 工具）逐层深入，重点关注暴露的接口和类型。
3. 最后基于这个理解，回答用户的具体问题。如果问题涉及某个函数的实现细节，先在图谱中找到该函数所在的模块和类型签名，如果需要更多源码细节，再请求具体文件的某几行。

开始分析吧。

把上面的 <project_graph_json> 替换成 CodeGraph 生成的 graph.json 内容即可直接在 Claude/Cursor 里用。

效果演示

我用这个模板测试了 colbymchenry/codegraph 项目本身（TypeScript，约 50 个源文件）:

差 Prompt（常规做法）
输入："分析这个项目，告诉我它怎么工作的" + 所有源码文件（约 900KB）
输出：Claude 先读一遍所有文件，耗时约 90 秒，消耗 12,000+ token，回答却只是简单罗列文件列表。

好 Prompt（本文模板）
输入：上面模板 + CodeGraph 生成的 graph.json（仅 12KB）
输出：Claude 用了 8 秒就输出了一份清晰的架构说明：

• 核心模块：src/ 下的 CodeGraph.ts（入口）、Grapher.ts（图谱构建）、Indexer.ts（索引）
• 依赖关系：CodeGraph 调用 Grapher，Grapher 使用 Indexer 和 TypeResolver
• 暴露接口：buildGraph()、queryModule()、exportJSON() 等
• 还主动指出需要进一步查看 TypeResolver.ts 中类型推断的细节，因为图中提到但未展开

token 对比：差 prompt 约 12,000，好 prompt 约 1,600，节省 87%。而且好 prompt 的回答有结构、有推理，差 prompt 只给了一堆文件名。

变体和注意事项

变体 1：聚焦单类问题
如果你只想问“这个项目的测试覆盖率够不够”，可以在 prompt 最后加一句：“只关注测试文件和配置，直接忽略其他模块。” 省去无干扰。

变体 2：让 AI 自动补充图谱
如果图谱缺失某些细节（例如某个函数的入参没有类型签名），让 prompt 里加上：“如果图谱信息不足以回答，先尝试推断，如果仍然无法确定则提出需要补充哪几个文件的具体内容。” 这样 AI 不会硬猜，而是精准请求文件。

变体 3：多轮对话复用图谱
把图谱内容放在 System Prompt 里，后续每次提问不用再带图谱，只带问题。实测 Claude 能记住图谱信息约 3-5 轮对话（取决于上下文窗口）。

注意事项

• CodeGraph 的 graph.json 文件大小通常只有源码的 1%～5%，但如果是巨大型项目（上千文件）仍可能超过上下文。可以用 --depth 参数限制层级。
• 这个 prompt 对 LLM 的推理能力要求较高，Claude Sonnet 和 GPT-4o 表现最好，DeepSeek Coder 也能用但偶尔遗漏模块。
• 如果图谱中没有类型签名或依赖关系，AI 会抓瞎。所以请确保 CodeGraph 索引时使用了 --with-types 和 --with-deps 选项。