编码助手在处理流行库时表现出色，因为大语言模型（LLM）在这些库上经过了大量训练。但一旦面对自定义库、新版库、内部 API 或小众框架，它们往往力不从心。这对于使用特定领域库或企业代码的团队来说是个大问题。

作为 LangGraph 和 LangChain 等库的开发者，我们非常希望能让编码助手高效地编写相关的代码。为此，我们尝试了多种上下文工程技术，并总结了其中的成败经验。

我们的核心发现是：高质量的精炼信息，结合按需获取更多细节的工具，能产生最佳效果。

简单地让智能体访问原始文档，效果并不如预期，反而会更快地占满上下文窗口。一个以 Claude.md 形式存在的、结构清晰的简明指南，其表现始终优于直接接入文档工具。而最佳方案是将两者结合：让智能体拥有基础知识（通过 Claude.md），同时也能在需要时查询文档的具体部分。

本文将分享：

  • 我们测试的几种 Claude Code 配置方案。
  • 用于评估生成代码的评测框架（你可以复用此模板）。
  • 实验结果与核心要点。

Claude Code 测试配置

为保证一致性，我们统一使用 Claude 4 Sonnet 模型，并测试了以下四种不同的配置：

  1. Claude 原生版 (Claude Vanilla)：未经任何修改的开箱即用版本。
  2. Claude + MCP：连接到我们自建的 MCPDoc 服务器，使其具备文档访问能力。
  3. Claude + Claude.md：提供一个详细的 Claude.md 文件，其中包含针对 LangGraph 的专门指导。
  4. Claude + MCP + Claude.md：同时提供 Claude.md 指南和 MCPDoc 服务器的访问权限。

MCP 文档访问工具

我们构建了 MCPDoc 服务器，旨在让编码助手能够访问任何库的文档。这是一个开源的 MCP 服务器，提供了两个工具：list_doc_sources 和 fetch_docs。前者用于列出可用的文档源文件（llms.txt），后者则用于读取指定文件的内容。

在我们的实验中，我们提供了 LangGraph 和 LangChain 的 Python 及 JavaScript 文档。你可以通过在 MCP 配置中传入自己库的 llms.txt 文件 URL，轻松地将其应用于你的场景。

Claude.md 指南文件

我们为 LangGraph 创建了一个专门的 Claude.md 指南文件。它与直接提供所有页面内容的 llms.txt 不同，Claude.md 包含了从零开始构建项目时最关键的精炼信息。其内容包括：

  • 项目结构要求：例如，在创建文件前必须搜索代码库、正确的导出模式、部署最佳实践等。
  • 核心代码示例：涵盖了构建单智能体和多智能体系统所需的原语，如 create_react_agent、主管（supervisor）模式和用于动态切换的群体（swarm）模式。
  • 疑难场景指南：针对 LLM 难以处理的实现，如流式处理（streaming）和面向用户的人机交互（human-in-the-loop），我们添加了详尽的指导。
  • 常见陷阱与反模式：我们发现，包含一个关于常见陷阱和反模式的综合性章节非常有价值。这部分涵盖了 LLM 经常犯的错误，如不正确的 interrupt() 用法、错误的状更新模式、类型假设错误以及过度复杂的实现。这些错误通常源于模型对已弃用库的记忆或对其他框架模式的混淆。
  • 编码标准：包括 LangGraph 特有的编码规范，如结构化输出验证、正确的消息处理以及与其他框架集成的调试模式。
  • 文档链接：由于 Claude 能够使用网络工具，我们在每个章节末尾都附上了具体的文档 URL，以供其进一步参考和导航。

评测框架

我们的目标是衡量那些能真正提升代码质量的因素，而不仅仅是代码能否运行。像 Pass@k 这样的流行指标只能捕捉到功能性，而无法评估是否遵循了最佳实践。

因此，我们构建了一个任务专用的评测工具，它既能检查技术要求，也能评估代码质量、设计选择和是否遵循推荐方法等主观方面。评测分为三类：

1. 冒烟测试 (Smoke Tests)

这部分用于验证基本功能，例如：

  • 代码能否成功编译。
  • 是否暴露了 .invoke() 方法。
  • 能否处理预期的输入状态。
  • 能否返回预期的输出结构（如包含必要状态属性的 AIMessage 对象）。

我们使用加权求和来计算分数： Score = Σᵢ wᵢ × cᵢ 其中 wᵢ 是测试 i 的权重，cᵢ 是该测试的二元结果（通过/失败）。

2. 任务需求测试 (Task Requirement Tests)

这部分验证任务的特定功能，例如：

  • 部署配置文件的验证。
  • 对外部 API（如网络搜索或 LLM 提供商）的 HTTP 请求验证。
  • 针对每个编码任务的特定单元测试。

计分方式与冒烟测试相同。

3. 代码质量与实现评估

对于二进制测试无法捕捉的方面，我们采用“LLM 辅助评估”（LLM-as-a-Judge）的方法。遵循更佳实践的实现应该比那些仅仅能编译运行的代码得分更高。代码质量、设计选择和 LangGraph 抽象的使用都需要更细致的评估。

我们参考了每个任务的专家代码，并构建了任务专用的评估标准（rubric）。我们使用 Claude Sonnet 4（claude-sonnet-4-20250514，温度设置为 0）来对照这些标准评估生成的代码，同时结合专家代码作为参考，并由人工标注编译和运行时错误。

评估标准分为两类：

  • 客观检查：这些是关于代码的二元事实（例如，是否存在特定节点、图结构是否正确、模块是否分离、是否包含测试文件）。LLM 评测者对每项检查返回布尔值，我们同样使用加权求和得出分数。
  • 主观评估：这是对代码的定性评估。LLM 评测者会识别问题，并按严重性（严重、主要、次要）和维度（正确性违规、质量问题）进行分类。我们为此采用基于惩罚的计分方式： Score = Scoreₘₐₓ - Σₛ (nₛ × pₛ) 其中 Scoreₘₐₓ 是最高可能分数，nₛ 是严重性为 s 的违规次数，pₛ 是该严重性的惩罚权重。

综合客观与主观结果，总分计算公式为： Score = Σᵢ wᵢ × cᵢ + Σₛ (Scoreₘₐₓ,ₛ - Σₛ (nₛ × pₛ))

为减少随机性，我们对每个任务的每种配置都运行了三次。所有分数均以总分的百分比形式呈现，并跨任务取平均值。

实验结果分析

下图展示了四种 Claude Code 配置在三个不同 LangGraph 任务上的平均总分：

// 图表：四种配置的平均得分对比
// 4. Claude + Claude.md + MCP: ~85% (最高)
// 3. Claude + Claude.md:        ~75%
// 2. Claude + MCP:              ~60%
// 1. Claude Vanilla:            ~50% (最低)

最有趣的发现是，Claude + Claude.md 的表现优于 Claude + MCP，尽管 Claude.md 包含的信息只是 MCP 服务器所能提供的子集。

通过分析运行轨迹（trace），我们找到了原因：Claude 调用 MCP 工具的频率远低于我们的预期。即使任务需要查阅两三个链接页面才能完成，它通常也只调用一次 MCP，停留在只提供表面描述的主页面，而没有深入获取所需的细节。

相比之下，Claude + Claude.md + MCP 配置能更有效地利用文档。我们观察到，它调用 MCP 工具的频率更高，甚至在需要时会触发网络搜索工具。这种行为是由 Claude.md 驱动的，因为我们在指南的每个章节末尾都提供了参考 URL，鼓励它去查找更多信息。

这并不意味着 MCP 工具毫无用处。它将智能体的分数提高了约 10 个百分点，主要是在基本语法和概念上提供了有效指引。但对于任务完成度和代码质量而言，Claude.md 的作用更为关键。该指南包含了需要避免的陷阱和应遵循的原则，帮助 Claude Code 更好地“思考”，并探索库的不同部分，而不是停留在高层描述上。

核心要点总结

这些结果为配置编码助手提供了几点通用经验：

  1. 警惕上下文过载 直接将大量文档（llms.txt）塞入上下文窗口可能会导致性能下降和成本增加。我们 MCP 服务器的实现方式比较简单，会获取整个页面的内容，即使只调用一次，也会触发 Claude Code 上下文窗口即将填满的警告。如果你的文档非常庞大，需要工具来检索，那么值得投入精力构建更智能的检索工具，只提取相关的代码片段。

  2. Claude.md 的高性价比 与搭建 MCP 服务器或专用工具相比，创建一个 Claude.md 文件更容易，运行成本也更低。在我们的第二个任务中，Claude + Claude.md 的成本比其他两种带工具的配置低了约 2.5 倍。它既便宜又高效，是定制 Claude Code 的绝佳起点，对某些用例来说可能已经足够。

  3. 编写高质量的指令 一份好的指南文件（Claude.md 或 Agents.md）应该突出库的核心概念、独特功能和常用原语。通过手动审查失败的运行案例，找出反复出现的陷阱，并为其添加指导。例如，我们发现智能体在处理 LangGraph 与 Streamlit 的异步任务时经常失败，于是在指南中专门说明了 asyncio 的集成方法。我们还添加了启动开发服务器的调试步骤，这解决了导入错误，并让 Claude Code 能够向服务器发送请求以验证输出。

  4. 强强联合，效果最佳 虽然 Claude.md 的“每令牌收益”最高，但最强的结果来自于将其与 MCP 服务器配对。指南提供了概念引导，而文档工具则帮助其深入细节。两者结合，才能在领域专用库上发挥出最佳性能。

附录：任务示例

任务 1：文本到 SQL 的智能体

我们要求每个配置构建一个基于 LangGraph 的“文本到 SQL”智能体。它需要能根据自然语言生成 SQL 查询，在数据库中执行，并返回自然语言响应。此任务需要从远程 URL 获取 Chinook SQLite 数据库，并设置一个内存数据库。

  • 冒烟测试：验证基本的 LangGraph 功能。
  • 任务需求测试：检查数据库设置、对简单查询/连接查询/日期范围查询的处理能力。
  • LLM 辅助评估：评估代码设计选择，如远程 URL 获取、SQL 生成/执行/响应节点的模块化分离等。相关的评估提示词可在原文中查看。

通过此类具体任务的评测，我们得以深入比较不同配置在实际场景中的表现差异。

👉 如果你需要 ChatGPT 代充 / Claude / Claude Code / 镜像 / 中转 API：