CodeGraph 实战教程：给 AI 编程助手装上“代码导航仪”

如果你最近在用 Qoder、Trae 这类 AI 编程助手，大概率遇到过这样的痛点：面对一个陌生的庞大项目，AI 往往不知道代码的入口在哪、谁调用了谁。于是它只能不停地执行搜索、查找和读取文件等命令，一边摸索一边消耗上下文，最后给你的往往不是直接答案，而是一长串翻找文件的过程。

CodeGraph 的出现正是为了解决这个问题。它的核心思路非常直接：提前把代码库建立成一个本地知识图谱，让 AI 直接查询图谱，而不是反复扫描文件。它把函数、类、方法、导入关系、调用关系和框架路由整理进一个本地 SQLite 数据库里，配合全文检索引擎做快速查询，还会用文件监听器自动增量同步。简单来说，它的目标不是替代你的编辑器，而是给 AI 增加一层精准的“代码地图”。

针对 VS Code、Excalidraw 等真实开源仓库的测试中，接入 CodeGraph 后，AI 的工具调用次数平均减少了 89%，Token 消耗减少了 69%，整体费用降低了 60%。

安装

Node.js 环境，可以直接通过 npm 全局安装：

npm i -g @colbymchenry/codegraph

安装完成后，进入你的项目目录并初始化索引：
bash

cd your-project
codegraph init

这一步会在项目根目录创建 .codegraph/ 目录，并生成知识图谱。

其他命令

配置AI工具

为了让 AI 助手（如 Claude Code）能够调用这个图谱，你需要启动本地的 MCP 服务。可以通过交互式命令自动配置：

codegraph install

或者手动在 AI 工具的配置文件（如 ~/.claude.json）中添加 MCP 服务配置：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

配置保存后重启 AI 工具，它就能自动识别并调用 CodeGraph 的能力了。

检查AI工具是否支持 CodeGraph 了

• 直接chat问AI工具：请检查项目是否能使用codegraph检索代码

约束工具使用 CodeGraph

聊天版

重要执行规则，必须严格遵守：
1. 在编写代码、定位逻辑、查询函数/类/接口、寻找变量定义、追踪调用链路、查找相关实现文件前，**优先调用 CodeGraph 进行代码检索**；
2. 禁止仅凭记忆猜测代码位置、文件路径、函数签名，禁止直接罗列臆想的代码；
3. 检索策略：
   - 需要查找定义：使用 CodeGraph 搜索类名、函数名、常量、接口名称；
   - 需要梳理调用关系：使用 CodeGraph 查询调用方/被调用方依赖图；
   - 需要匹配业务逻辑：使用 CodeGraph 根据关键字检索相关文件；
4. 只有 CodeGraph 返回结果不足时，再申请读取对应文件内容，不允许跳过 CodeGraph 直接读取文件；
5. 每一步改动前先通过 CodeGraph 确认现有代码结构，避免写出和仓库现有代码冲突、风格不一致的实现。

需求：【在这里粘贴你的功能需求】

工具规则约束版

• 创建项目规则（不同工具存放目录不同）：project_rules.md

# 硬性工具调用规范（不可违反）
任何代码分析、定位函数、查找类、追踪调用链路、寻找实现文件、新增功能开发，
**第一步必须优先调用 CodeGraph MCP 工具**，禁止跳过 CodeGraph 直接读取文件、禁止glob遍历文件。

执行标准流程：
1. 收到需求 → 使用 codegraph_search / codegraph_context 检索符号、模块、业务代码
2. 根据CodeGraph返回结果，按需读取对应文件
3. 基于检索到的真实代码进行修改、方案设计

禁止行为：
❌ 跳过CodeGraph直接批量读取文件
❌ 凭空猜测项目内函数、路径、接口定义
❌ 优先使用原生searchcodebase代替codegraph
❌ 在未检索符号前直接编写代码

工具选择建议：
- 查找函数/类定义：codegraph_search
- 梳理调用关系、依赖：codegraph_context
- 项目架构概览：project_overview

只有当CodeGraph检索信息不足时，才允许补充读取文件。
所有代码修改必须和仓库现有结构保持一致。