如何让 Claude Code 成为领域特定编码专家

Aliyan Ishfaq

/

Tyde

[解读]

为智能体提供一个浓缩的“心智模型”（Claude.md），远比给它一个通往海量信息的“图书馆钥匙”（文档工具）更有效。这说明智能体（以及人类）认知的一个基本原则：有效的学习始于结构，而非信息。没有认知脚手架，再多的信息也只是噪音。

与AI协作不仅是提供信息，更重要的是传授策略、原则和反模式（Claude.md中的内容）。这标志着我们从“提示工程师”转变为“AI认知教练”。构建强大AI应用的关键，在于成为AI认知架构师，设计和优化AI的“思考”流程，而不仅仅是调用API。

Claude.md实际是工作记忆——容量小、优先级高、随时可用，用于指导当前任务。文档工具像是长期记忆——容量巨大，但提取速度慢、需要特定线索。而高效思考依赖于工作记忆对长期记忆的有效调度。

编码智能体在编写使用LLM有大量训练的流行库的代码方面表现出色。但如果将它们指向自定义库、新版本的库、内部API或小众框架，它们的表现就不尽如人意。这对于使用领域特定库或企业代码的团队来说是一个问题。

作为库（LangGraph、LangChain）的开发者，我们非常关注如何让这些编码智能体在编写LangGraph和LangChain代码方面表现出色。我们尝试了许多上下文工程技术。有些奏效，有些则没有。在这篇文章中，我们将分享我们进行的实验和获得的经验。我们最大的收获是：

高质量、精炼的信息与按需访问更多细节的工具相结合，产生了最佳结果。

提供智能体原始文档访问权限并没有像我们希望的那样显著提高性能。事实上，上下文窗口填充得更快。以Claude.md形式提供的简洁、结构化的指南总是优于简单地连接文档工具。最佳结果来自于两者的结合，即智能体拥有一些基础知识（通过Claude.md），但也可以在需要时访问文档的特定部分。

在这篇文章中，我们将分享：

• 我们测试的不同Claude Code配置
• 我们用于评估生成代码的评估框架（一个可供您重复用于自己库的模板）
• 结果和主要收获

Claude Code 设置

我们测试了四种不同的配置，为了保持一致性，均使用Claude 4 Sonnet作为模型：

• Claude Vanilla：开箱即用的Claude Code，未进行任何修改。
• Claude + MCP：Claude Code连接到我们的MCPDoc服务器以访问文档。
• Claude + Claude.md：Claude Code使用包含LangGraph特定指导的详细Claude.md文件。
• Claude + MCP + Claude.md：Claude同时访问详细的Claude.md和MCPDoc服务器。

用于文档的MCP工具

我们构建了MCPDoc服务器，因为我们希望为编码智能体提供访问任何库文档的能力。它是一个开源的MCP服务器，暴露了两个工具：list_doc_sources 和fetch_docs。前者共享可用llms.txt文件的URL，后者读取特定的llms.txt文件。在我们的设置中，我们提供了对LangGraph和LangChain Python及JavaScript文档的访问。您可以通过在MCP配置中传入库的llms.txt文件的URL，轻松地将其适应您的用例。

Claude.md

对于Claude.md，我们创建了一份LangGraph库指南。它包含了LangGraph项目常见结构要求的详细说明，例如在创建文件前强制进行代码库搜索、正确的导出模式以及部署最佳实践。它包含了构建单智能体和多智能体系统所需原语的示例代码，例如create_react_agent、主管模式和动态切换的群集模式。LLM在某些实现上遇到了困难，例如流式传输和面向用户的智能体中的人工干预。我们为此添加了广泛的指导。

我们发现，包含关于常见陷阱和反模式的综合部分特别有价值。这涵盖了常见的错误，如不正确的 interrupt() 使用、错误的状体更新模式、类型假设错误以及过于复杂的实现。这些是LLM经常犯的错误，可能是由于库已弃用或与其他框架的模式混淆。

我们还包含了LangGraph特定的编码标准，如结构化输出验证、正确的消息处理以及其他框架集成调试模式。由于Claude可以访问网络工具，我们在每个部分的末尾添加了特定的文档URL，以供进一步参考和导航指南。

这个文件与llms.txt的区别在于，后者是包含所有页面内容的纯文本文件，而前者包含的是从头开始时最重要的精炼信息。正如我们将在结果中看到的，当单独传递llms.txt时，它并不是最有效的，因为它有时会用更多的上下文混淆LLM，并且没有关于如何导航和辨别重要内容的说明。

在深入探讨我们的Claude Code配置在不同任务中的表现之前，我们想分享我们用于确定任务完成度和代码质量的评估框架。

评估

我们的目标是衡量对代码质量贡献最大的因素，而不仅仅是功能性。像Pass@k这样的流行指标只捕捉功能性，而不捕捉最佳实践，这因上下文而异。

我们构建了一个任务特定的评估工具，它既检查技术要求，也检查主观方面，如代码质量、设计选择和对首选方法的遵守。

我们将评估分为三类：

冒烟测试：这些测试验证基本功能。测试确认代码编译、暴露 .invoke() 方法、处理预期的输入状态，并返回预期的输出结构，如带有所需状态属性的AIMessage对象。

          我们使用加权求和计算分数：

分数 = Σᵢ wᵢ × cᵢ

其中 wᵢ 是测试 i 的权重，cᵢ 是测试的二元结果。
        

任务需求测试

这些测试验证任务特定功能。测试包括部署配置文件验证、对外部API（如网络搜索或LLM提供商）的HTTP请求验证，以及每个编码任务特有的单元测试。评分通过每个测试结果的加权求和完成，与冒 烟测试相同。

代码质量与实现评估

对于这一类别，我们使用LLM作为评判者来捕捉二元测试遗漏的内容。遵循更好方法的实现应该比那些仅仅编译和运行的实现得分更高。代码质量、设计选择和LangGraph抽象的使用都需要细致的评估。

我们审查了专家为每个任务编写的代码，并构建了任务特定的评分标准。使用Claude Sonnet 4 (claude-sonnet-4-20250514)，温度设置为0，我们根据这些评分标准评估了生成的代码，使用专家编写的代码作为参考，并使用人工标注来记录编译和运行时错误。

我们的评分标准有两种类型：

• 客观检查：这些是关于代码的二元事实（例如，特定节点的出现、正确的图结构、模块分离、没有测试文件）。LLM评判者为每个检查返回一个布尔响应，我们使用加权求和（与冒烟测试相同）来获得客观检查的分数。
• 主观评估：这是对代码的定性评估，使用专家编写的代码作为参考，并使用人工标注来传递编译和运行时错误的日志。LLM评判者识别问题并按严重性（关键、主要、次要）对它们进行分类，分为两个维度：正确性违规和质量问题。

          我们使用基于惩罚的评分：

分数 = Scoreₘₐₓ - Σₛ (nₛ × pₛ)

其中 Scoremax 是可能的最大分数，nₛ 是严重性 s 的违规数量，pₛ 是该严重性的惩罚权重。

结合客观和主观结果的总分如下：

分数 = Σᵢ wᵢ × cᵢ + Σₛ (Scoreₘₐₓ,ₛ - Σₛ (nₛ × pₛ))

其中第一项代表客观检查，第二项代表所有主观类别的评估。
        

我们对每个Claude Code配置的每个任务运行了三次，以考虑差异。为保持一致性，所有分数均以总可能分数的百分比报告，然后对任务进行平均。您可以使用LangSmith平台为自己的库复制此方法，以比较编码智能体配置。

结果

我们对三个不同的LangGraph任务的得分进行平均，以比较Claude Code配置。下图显示了总分：

对我们来说最有趣的发现是，Claude + Claude.md 的表现优于 Claude + MCP，尽管 Claude.md 只包含了 MCP 服务器能提供内容的一个子集。Traces (通过 LangSmith的观察平台对智能体的监测，译注) 解释了原因：Claude 调用 MCP 工具的频率没有我们预期的那么高。即使任务需要遵循两到三个链接页面，它通常也只调用 MCP 一次，并在主页停止，而主页只提供表面描述，没有所需的详细信息。

相比之下，Claude + Claude.md + MCP 更有效地使用了文档。我们在 traces 中观察到，它更频繁地调用 MCP 工具，甚至在需要时触发了网络搜索工具。这种行为是由 Claude.md 驱动的，该文件在每个部分的末尾包含了参考URL，以供进一步信息查询。

这不意味着 MCP 工具本身没有帮助。它们将分数提高了约10个百分点，主要通过让智能体掌握基本语法和概念。但对于任务完成度和代码质量，Claude.md 更重要。该指南包含了要避免的陷阱和要遵循的原则，这有助于Claude Code更好地思考和探索库的不同部分，而不是停留在高层描述。

这些结果为配置编码智能体的人提供了一些更广泛的经验教训。

主要收获

下面结果给我们不少启发。如果您正在考虑为自己的库定制编码智能体，以下几点可能会有所帮助：

• 上下文过载：从文档中倾倒大量的llms.txt文件可能会挤占上下文窗口。这可能导致性能不佳和成本增加。我们的MCP服务器在获取页面内容方面有一个简单的实现。即使只调用一次，也会触发Clau de Code的上下文窗口已满警告。如果您的文档足够广泛，以至于您需要工具来检索特定文档，那么构建更智能的检索工具，只提取相关片段是值得的。
• Claude.md 的回报最高：它比MCP服务器或特定工具更容易设置，运行成本也更低。在任务#2中，Claude + Claude.md 比 Claude MCP 和 Claude + Claude.md + MCP 便宜约2.5倍。它比Claude MCP便宜，并且表现更好。这是考虑定制Claude Code的一个很好的起点，并且可能对某些用例来说已经足够好。
• 编写好的说明：一个Claude.md（或Agents.md）应该突出您库中的核心概念、独特功能和常见原语。手动审查失败的运行，找出反复出现的陷阱，并为它们添加指导。对我们来说，这意味着涵盖Lan gGraph中与Streamlit的异步任务，智能体经常在asyncio集成上失败。我们还添加了启动开发服务器的调试步骤，这修复了导入错误，并让Claude Code向服务器发送请求以验证输出。流行的代码生成工具通常使用长系统提示（7-10k token）。在说明上投入精力会带来很好的回报。
• Claude + Claude.md + MCP 获胜：虽然Claude.md提供了每个token的最大收益，但最强的结果来自于将其与允许其详细阅读文档的MCP服务器配对。指南提供了概念的导向，文档则帮助深入了解。两者结合，可以在领域特定库上产生最佳结果。

在附录中，我们包含了每个任务的结果和类别级别的图表，供希望深入了解每个任务性能的读者参考。

附录

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

我们要求每个配置构建一个基于LangGraph的文本到SQL智能体，该智能体可以从自然语言生成SQL查询，针对数据库执行查询，并返回自然语言响应。此任务需要从远程URL获取Chinook SQLite数据库并设置内存数据库。您可以在此处阅读我们传递给Claude Code实例的提示。

对于此任务，我们的冒烟测试验证了基本的LangGraph功能。任务要求检查数据库设置；简单查询、连接查询、日期范围查询的SQL查询处理；以及LLM作为评判者评估的代码设计选择，例如远程URL获取、SQL生成、执行和响应的独立节点。LLM作为评判者的提示可在此处获取。

结果显示了Claude Code配置和类别之间的性能差异：糟糕的实现通常难以连接跨线程的内存数据库，在LLM提示中下载并硬编码模式而不是使用带有运行时模式读取的远程URL，并且未能正确解析LLM输出以进行SQL执行（当LLM生成格式略有不同的结果 时会中断）。

任务#2：公司研究员

对于此任务，我们要求每个Claude配置构建一个多节点LangGraph智能体，该智能体使用Tavily API通过网络搜索研究公司。智能体需要处理结构化数据收集，实现并行搜索执行，并添加一个反思步骤，以确保收集所有请求的信息。您可以在此处阅读提示。

我们的测试验证了基本功能、Tavily API集成以及结构化对象类中所有请求属性的存在。LLM作为评判者检查了反射逻辑、最小搜索查询限制和并行网络搜索执行等功能的实现。

以下是此任务的结果：大多数实现失败与在状态和反射步骤中以对象形式组织信息有关。糟糕的实现要么没有功能性反射节点，要么未能触发额外的搜索。

任务#3：记忆类别

这是一个编辑任务，我们为每个Claude Code配置提供了一个现有的记忆智能体作为基础代码。我们要求它们扩展记忆存储方法，除了用户ID之外，还按类型（个人、专业、其他）对记忆进行分类， 实现基于消息类别而不是仅仅用户ID的选择性记忆检索，并在保存记忆之前添加人工确认步骤。我们还故意添加了语法错误。完整提示可在此处获取。

通过测试，我们验证了实现是否在记忆存储之前正确添加了中断功能，实现了按类别存储和检索，使用了三个特定类别（个人、专业、其他），并维护了功能性中断逻辑，只有在用户接受时才保存记 忆。LLM作为评判者评估了实现是否使用了基于LLM的分类而不是脆弱的关键词匹配和不必要的文件。

对于编辑任务，我们看到以下结果：大多数实现难以正确实现中断功能。错误的实现要么添加简单的 input() 调用来获取终端输入，要么通过创建单独的节点而不是使用几行正确的 interrupt 逻辑来过度复杂化解决方案。糟糕的实现还依赖于关键词匹配进行分类而不是基于LLM的分类，并且几乎所有都未能捕获我们故意包含的语法错误。