CodeGraph 第 3 课：进阶配置与最佳实践

CodeGraph 的进阶配置和最佳实践，主要围绕 性能优化、多项目管理、定制化索引 和 高效工作流 这几个方面。掌握这些，可以让你和 AI 助手的协作更高效。

⚙️ 进阶配置：调整索引参数

CodeGraph 提供了多种配置方式来微调其行为，包括命令行参数、环境变量和配置文件。

1. 索引性能调优

配置方式示例：

• 命令行参数：codegraph init --graph-only

• 环境变量：export CODEGRAPH_NO_FAST_INIT=1

• 配置文件：在项目根目录创建 .codegraph/config.json。

{
  "max_nodes": 100000,
  "enable_community": false
}

注意：配置文件中的设置是最低优先级，会被环境变量和命令行参数覆盖。

2. MCP 服务器高级选项

在配置 MCP 客户端时，可以向 args 数组添加更多参数：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph-server",
      "args": [
        "--mcp",
        "--workspace", "/path/to/project1",
        "--workspace", "/path/to/project2",
        "--exclude", "tests",
        "--profile", "core"
      ]
    }
  }
}

• --workspace：可重复使用，指定多个项目目录。

• --exclude：可重复使用，排除特定目录。

• --profile：缩小 MCP 工具范围，只暴露特定子集。

🚀 最佳实践：让AI助手更高效

1. 初始化会话与验证连接

在新会话开始时，先让 AI 助手读取 CodeGraph 的使用说明：“Read the codegraph instructions so you know how to use it”。然后让它验证连接：“Can you verify codegraph is connected and the index is available?”。

2. 掌握 7 大核心工具

CodeGraph 为 AI 助手提供了 7 个专用工具，你可以用自然语言指令来触发它们：

3. 为 AI 配置规则文件

从 codegraph-rules-for-agents 仓库复制对应你 AI 助手的规则文件，能教会它优先使用 CodeGraph 工具，而不是盲目地 grep。

4. 管理好索引范围

• 遵循 .gitignore：CodeGraph 默认会遵循 .gitignore 的规则。

• 手动排除目录：在项目根目录创建 .codegraph/config.json 文件，使用 exclude 字段排除特定目录。

{
  "exclude": ["**/node_modules/**", "**/dist/**", "**/legacy/**"]
}

• 强制包含：如果希望索引被 .gitignore 忽略的文件，可以使用 include 列表。

5. 保持索引最新

确保 CodeGraph 的文件监听器（--watch）处于运行状态，以便在编辑文件时自动更新索引。

codegraph start stdio --watch

🏗️ 多项目与 Monorepo 支持

CodeGraph 对多项目和 Monorepo 有良好支持。

• 分别初始化：在每个子项目的根目录下分别运行 codegraph init。

• 跨项目查询：所有 MCP 工具都支持 projectPath 参数。

codegraph_context(task: "auth flow", projectPath: "/path/to/backend")

• 自动识别：AI 助手在引用另一个已初始化的项目时，会自动使用 projectPath 参数。

🚦 在 CI/CD 中使用

CodeGraph 可以集成到 CI 流程中，例如在 PR 时自动分析代码影响。核心是使用 --graph-only 和 --run-tool 参数：

codegraph-server --graph-only \
  --run-tool codegraph_pr_context \
  --tool-args '{"baseBranch":"main","format":"markdown"}'

这会生成一个 Markdown 格式的影响分析报告，可以直接作为 PR 评论发布。

🧠 高级技巧：与 Subagent 协同

在复杂的多 Agent 协作场景中，可以让子 Agent (Subagent) 专门负责调用 CodeGraph 进行影响分析，主 Agent 只做规划和决策。这样能实现职责分离，进一步优化 Token 消耗。

⚠️ 常见问题排查

掌握这些进阶配置和最佳实践，能帮你根据项目特点深度定制 CodeGraph，让它成为你开发流程中更得力的助手。