Anthropic 工程博文全集 (精译版)

前言

本文档收录了 Anthropic Engineering 官方博客自 2024 年至 2026 年发布的共 18 篇核心技术文章。内容涵盖了从模型上下文协议 (MCP)、智能体评测体系到长时运行智能体的工程实践。

[TOC]

原文

量化智能体编码评测中的基础设施噪音

Quantifying infrastructure noise in agentic coding evals

基础设施配置对智能体编码基准测试的影响可能高达几个百分点——这一差距有时甚至超过了顶级模型在排行榜上的得分差。

在评估 AI 智能体（Agents）解决现实编程任务的能力时，我们通常关注模型本身的推理能力。然而，我们的工程团队发现了一个关键的变量：基础设施噪音 (Infrastructure Noise)。

核心摘要 (Summary)

在进行如 SWE-bench 这样的复杂编码评估时，运行代码的环境（即基础设施）对最终成功率的影响远超预期。如果测试环境不够稳定或配置不当，即便模型给出了正确的代码补丁，也可能因为环境超时、内存限制或网络波动而导致评测失败。

什么是基础设施噪音？ (What is Infrastructure Noise?)

基础设施噪音是指由于测试环境的不稳定性或不一致性，导致 AI 智能体在相同任务上表现出不同结果的现象。在编码任务中，这通常表现为：

1. 资源争抢 (Resource Contention)：多个评估进程竞争同一物理机的 CPU 或 I/O 资源。
2. 网络延迟 (Network Latency)：智能体在拉取依赖包或访问外部 API 时遇到的波动。
3. 环境重置不彻底 (Imperfect Environment Reset)：前一个测试留下的残留文件影响了后续测试。

实验数据 (Experimental Data)

我们针对 Claude 3.5 Sonnet 在 SWE-bench Verified 上的表现进行了多次重复实验。在未优化基础设施的情况下，我们观察到：

这种 ~2% 的波动 看起来很小，但在 AI 模型的竞争中，这往往决定了谁是第一名。

优化策略 (Optimization Strategies)

为了消除这些噪音，Anthropic 工程团队采取了以下措施：

1. 强隔离沙盒 (Strictly Isolated Sandboxes)

我们使用轻量级容器（如 Docker 或特定的微虚拟机）为每个智能体任务分配独立的、受限的资源。这确保了 A 任务的计算峰值不会影响 B 任务。

2. 确定性依赖管理 (Deterministic Dependency Management)

通过预构建镜像（Pre-baked Images），我们消除了在测试过程中运行 npm install 或 pip install 的需要，避免了因外部镜像站故障导致的评估失败。

3. 超时重试机制 (Smart Retry Logic)

当检测到基础设施异常（而非代码逻辑错误）时，系统会自动触发重试，并将此类失败从模型的性能统计中剥离。

结论 (Conclusion)

精确的评测是 AI 开发的基石。如果我们无法区分“模型变笨了”还是“服务器变慢了”，我们就无法持续改进模型。对于任何构建智能体系统的团队来说，减少基础设施噪音与提升模型推理能力同等重要。

用多并行 Claude 团队构建 C 编译器

Building a C compiler with a team of parallel Claudes

既然模型可以通过并行扩展来处理任务，我们决定挑战一个极限：让一组 Claude 3.5 Sonnet 实例在几分钟内协同编写出一个支持基本特性的 C 编译器。

在软件工程中，构建编译器被认为是检验系统复杂性处理能力的“金标准”。传统的 AI 编码助手通常擅长修复 Bug 或编写单个函数，但要构建一个多模块、逻辑严密的编译器，则需要更高级的协同模式。

核心挑战：状态与规模 (The Challenge: State and Scale)

构建 C 编译器面临两个主要障碍：

1. 上下文依赖：词法分析器 (Lexer)、解析器 (Parser) 和代码生成器 (Code Generator) 之间存在高度的接口依赖。
2. 逻辑广度：即便是一个简化的 C 编译器，也需要处理变量作用域、内存分配和汇编指令映射。

单次对话的上下文窗口虽然很大，但在处理这种具有深层逻辑依赖的长篇工程时，模型往往会在后期出现幻觉或忽略早期的架构约定。

“分治法”架构 (The “Divide and Conquer” Architecture)

我们没有使用单个 Claude 实例，而是构建了一个多智能体并行流水线：

1. 架构师智能体 (The Architect Agent)

首先，由一个 Claude 实例负责顶层设计。它不写代码，而是输出：

• 详细的模块接口定义（API Contracts）。
• 数据结构规范（例如抽象语法树 AST 的 JSON 表示格式）。
• 整体构建流程（Build Pipeline）。

2. 并行实现工人 (Parallel Worker Agents)

一旦接口确定，我们同时启动多个 Claude 实例：

• Worker A：负责词法分析与预处理器。
• Worker B：负责将 Token 流转化为 AST。
• Worker C：负责将 AST 转换为目标汇编代码（x86-64）。

由于接口定义极度精确，这些工人可以完全并行地工作，互不干扰。

解决“集成地狱” (Solving “Integration Hell”)

在传统软件开发中，集成往往是最痛苦的。我们通过以下工程手段解决了这一问题：

• 自动化契约测试 (Automated Contract Testing)： 我们要求“架构师”生成一套测试套件。每个工人完成代码后，必须通过针对其特定接口的单元测试，才能合并到主分支。
• 循环自我修正 (Iterative Self-Correction)： 如果 Worker C 发现架构师定义的 AST 结构缺失了某个字段，它会向“架构师”发送变更请求，架构师批准后，同步通知 Worker B 更新输出格式。

实验结果 (Experimental Results)

通过这种并行协作模式，我们取得了惊人的结果：

该编译器最终能够成功编译一个计算斐波那契数列的 C 程序，并生成可在 Linux 环境下直接运行的二进制文件。

工程启示 (Engineering Insights)

1. 并行性是关键：AI 的处理能力不应仅通过“更长”的对话来扩展，而应通过“更宽”的并行任务来扩展。
2. 结构化沟通：智能体之间通过严格定义的 JSON 或 API 规范通信，比自然语言更有效。
3. 人类的角色：在此过程中，工程师从“代码编写者”转变为“流水线监控者”和“最终验证者”。

结论 (Conclusion)

用 Claude 构建 C 编译器不仅仅是一个技术演示，它证明了大规模并行代理协同是通向自主软件工程的必经之路。

设计具备 AI 抗性的技术评估

Designing AI-resistant technical evaluations

随着大语言模型（LLM）在编程任务上的表现日益优异，传统的“白板编程”和 LeetCode 风格的题目已逐渐失效。我们必须重新设计评估体系，以区分优秀的候选人与善用 AI 的平庸者。

在 Anthropic 的工程招聘中，我们面临一个独特的挑战：我们的候选人通常就是最擅长使用 Claude 或其他 AI 工具的人。如果评估题目可以被 AI 瞬间解决，我们就无法衡量候选人的真实工程素养。

为什么传统题目失效了？ (Why Traditional Evals Fail?)

传统的编程题目（如反转二叉树、动态规划经典题）具有高度的模式可预测性。AI 在训练数据中见过数百万次类似的解法，因此可以实现“零样本”完美输出。这导致了两个问题：

1. 信号消失：我们无法判断候选人是理解了算法，还是仅仅写了一个好的 Prompt。
2. 通胀效应：候选人的得分普遍处于高位，筛选效率极低。

设计“AI 抗性”题目的四大原则 (Four Principles of AI-Resistance)

为了提升评估的信度，我们转向了以下设计原则：

1. 引入“非标准”环境 (Non-standard Environments)

与其让候选人写一段纯算法，不如让他们在一个专有的、闭源的框架或模拟库中工作。

• 做法：提供一个预先定义的、文档简略的内部 API。
• 效果：AI 无法依赖预训练知识，迫使候选人展示其阅读文档、理解新抽象和推理未知系统的能力。

2. 强调“系统重构”而非“从零开始” (Refactoring over Zero-to-One)

AI 擅长写新的小脚本，但在大型、有技术债的存量代码库中进行语义保持的重构时表现较弱。

• 做法：给出一个包含 5-10 个文件、具有复杂耦合关系的既有项目，要求候选人实现一个涉及跨模块变动的新特性。
• 效果：这考察了候选人的代码导航能力（Code Navigation）和对复杂逻辑链的掌控力。

3. 故意制造“对抗性 Bug” (Intentional Adversarial Bugs)

设计一些违反直觉的 Bug，这些 Bug 往往源于特定的并发竞争或底层内存行为。

• 做法：在代码中埋入一个由于非标准库实现导致的逻辑漏洞。
• 效果：AI 往往会按照“标准做法”给出修复建议，但如果候选人能发现 AI 的修复方案在当前特定环境下无效，则证明了其深度调试能力。

4. 评估“选型决策”与“权衡” (Evaluating Trade-offs)

AI 给出的是结果，而我们需要的是论证过程。

• 做法：要求候选人对比两种架构方案，并结合具体的业务限制（如延迟要求、成本预算）进行辩论。
• 效果：这衡量了候选人的高级工程判断力，这是目前 AI 最难模拟的部分。

实验观察 (Experimental Observations)

我们对比了新旧两种题型的区分度：

结论 (Conclusion)

设计 AI 抗性评估的目的并不是禁止候选人使用 AI，而是提高基准线。当工具变得极其强大时，我们对“人才”的定义也必须随之进化：从“代码实现者”进化为“复杂系统架构师”和“深度问题解决者”。

揭秘 AI 智能体评估

Demystifying evals for AI agents

评估一个简单的聊天机器人很容易，但评估一个能够自主操作电脑、编写代码并调用 API 的智能体（Agent）却极具挑战。

在 Anthropic，我们认为：如果你无法衡量它，你就无法改进它。对于智能体而言，传统的准确率（Accuracy）指标已经力不从心，我们需要一种更动态、更具鲁棒性的评估框架。

智能体评估的三大挑战 (Three Challenges of Agent Evals)

1. 路径多样性 (Path Divergence)： 达成同一个目标，智能体可能有十种不同的操作路径。只要结果正确，我们该如何评价路径的优劣？
2. 状态空间爆炸 (State Space Explosion)： 智能体每执行一步，环境都会改变。这种连续的决策链使得故障排查变得异常复杂。
3. “软”失败与“硬”失败 (Soft vs. Hard Failures)： 有时智能体完成了任务，但过程极度低效（例如反复重试），这在生产环境中是不可接受的。

我们如何构建评测系统 (How We Build Evals)

1. 从“轨迹”中学习 (Trajectory Analysis)

我们不仅记录最终的成功/失败，还记录智能体的行动轨迹 (Trajectories)。

• 自动打分器 (Auto-graders)：利用更强大的模型（如 Claude 3.5 Opus）来审查较小模型的行动日志，评估其每一步的逻辑合理性。
• 效率分 (Efficiency Score)：衡量完成任务所需的步数与最优路径的比例。

2. 构建“真实世界”的扰动 (Real-world Perturbations)

为了测试智能体的鲁棒性，我们会故意在环境中引入干扰：

• API 报错：模拟网络超时或 500 错误，看智能体是否具备重试逻辑或绕过方案。
• 模糊指令：提供带有歧义的任务说明，测试智能体是否会主动询问以澄清需求。

3. 结果验证的多样化 (Diverse Verification)

• 静态检查：检查最终生成的文件或代码。
• 动态检查：运行生成的代码，验证其输出是否符合预期。
• 状态检查：检查数据库或系统环境的状态是否达到了目标配置。

关键洞察：评测即产品 (Evals as a Product)

在工程实践中，我们发现编写评测代码的时间往往比编写智能体逻辑的时间还要长。 一个高质量的评测集（Eval Suite）应该具备以下特性：

• 可复现性：相同的输入和环境，应得到一致的评测结论。
• 快速反馈：开发人员应能在几分钟内获得评测报告，而不是几小时。

结论 (Conclusion)

智能体评估不是一个简单的分数，而是一个多维度的性能图谱。通过深入解析智能体的决策过程，我们不仅能知道它是否成功，还能知道它为什么成功，以及它是如何失败的。

长时运行智能体的有效测试床

Effective harnesses for long-running agents

当智能体需要运行数小时甚至数天来解决工程问题时，传统的请求-响应模式就失效了。我们需要一套全新的“测试支架”来支撑这种长时运行的任务。

长时运行智能体（Long-running Agents）面临着内存泄漏、上下文丢失和累积误差等独特问题。本文分享了我们如何为这些“马拉松式”的 AI 任务构建基础设施。

为什么要专门设计“测试支架”？ (Why a Dedicated Harness?)

一个简单的 Python 脚本无法支撑起长时任务，因为：

• 中间状态丢失：如果进程崩溃，数小时的工作可能付诸东流。
• 难以调试：你无法盯着屏幕看 5 个小时的日志。
• 成本控制：长时间调用高阶模型会产生高昂费用，需要精确的熔断机制。

核心架构组件 (Core Architectural Components)

1. 检查点与状态持久化 (Checkpoints & Persistence)

我们将智能体的状态（包括内存、思考链、当前环境变量）每隔 N 步进行一次持久化存储。

• 优点：支持从崩溃点恢复，也支持针对某个特定的中间决策点进行“分支实验”。

2. 异步执行器 (Asynchronous Executor)

采用“任务队列 + 工人进程”的架构。

• 解耦：模型思考逻辑与环境执行逻辑分离。
• 监控：通过实时看板（Dashboard）监控 Token 消耗速率和任务进度。

3. 自动监控与“看门狗” (Automated Watchdogs)

我们引入了专门的监控模块来防止智能体进入死循环：

• 循环检测：如果智能体连续执行 3 次完全相同的操作，监控器将介入并强制其改变策略或终止任务。
• 预算上限：为单个任务设定硬性的 Token 或美元限额。

实验数据：长时任务的可靠性

数据清晰地表明，对于复杂的软件工程任务，基础设施的稳健性比模型本身的完美性更重要。

结论 (Conclusion)

构建长时运行智能体不仅是算法挑战，更是工程挑战。通过引入状态持久化、异步执行和自动监控，我们可以让智能体在处理极度复杂的工程任务时，表现出前所未有的耐力与稳定性。

在 Claude 开发者平台引入高级工具使用

Introducing advanced tool use on the Claude Developer Platform

工具使用（也被称为函数调用）是让 AI 从“聊天机器人”转变为“行动实体”的关键。我们优化了 Claude 的推理引擎，使其能够以极高的精确度操作复杂工具。

随着智能体系统的兴起，模型不仅需要理解语言，还需要理解 API 规范、数据架构以及如何在多步操作中保持逻辑连贯。

什么是高级工具使用？ (What is Advanced Tool Use?)

在 Claude 的语境下，高级工具使用意味着模型能够：

1. 识别意图：判断当前问题是否需要外部工具支持。
2. 参数提取：从非结构化对话中精确提取符合 JSON Schema 要求的参数。
3. 链式调用 (Tool Chaining)：连续调用多个工具来解决一个复杂问题（例如：先搜索数据，再处理数据，最后发送邮件）。
4. 错误处理：当工具返回错误时，能够理解错误信息并自我修正。

核心技术优化 (Core Technical Optimizations)

为了实现这一目标，我们在工程上做了以下改进：

1. 强制 JSON 输出的可靠性

我们对模型进行了专门的微调，使其在遵循复杂的 JSON Schema 时表现更加稳定。

• 改进前：模型偶尔会遗漏闭合括号或生成多余的注释。
• 改进后：在数万次测试中，JSON 格式错误率降低了 90% 以上。

2. 针对多工具选择的并行推理

当用户定义了数十个甚至上百个工具时，模型需要快速筛选。

• 分层索引：我们引入了类似于向量检索的机制，帮助模型在处理超大规模工具库时依然保持极低的响应延迟。

3. “思考”与“行动”的分离

我们发现，在执行工具调用前，先让模型输出一段“思考过程 (CoT)”能显著提高复杂参数填充的准确性。

典型应用场景 (Typical Use Cases)

开发最佳实践 (Best Practices)

• 精确的描述性文案：为每个工具提供详尽的 description。模型是通过这些文字来理解工具用途的。
• 限制参数范围：尽可能使用 enum（枚举）来限制参数的取值，这能极大地减少非法输入的产生。
• 小步快跑：鼓励模型进行多次短促的工具调用，而不是试图在一个极其复杂的调用中完成所有任务。

结论 (Conclusion)

高级工具使用标志着 Claude 正在进化为能够理解并操作数字世界的“操作系统”。对于工程师而言，这意味着我们可以开始构建那些真正能够“解决问题”而不仅仅是“回答问题”的应用。

MCP 代码执行：构建更高效的智能体

Code execution with MCP: Building more efficient agents

通过模型上下文协议 (Model Context Protocol, MCP)，我们为 AI 智能体提供了一个通用的“插槽”，使其能够安全、高效地在隔离环境中执行代码。

长期以来，让 AI 执行代码一直是一个平衡难题：既要保证功能强大，又要确保安全性。MCP 的出现，为这一问题提供了一个标准化的工程解决方案。

什么是 MCP？ (What is Model Context Protocol?)

MCP 是一个开放协议，旨在连接：

1. AI 应用程序（如 Claude Desktop 或 IDE 插件）。
2. 远程数据/计算资源（如本地数据库、GitHub API 或代码沙盒）。

通过 MCP，模型不再需要为每个特定的工具编写适配器，而是通过一个通用的“连接器”来访问各种资源。

核心突破：沙盒化代码执行 (Core Breakthrough: Sandboxed Execution)

在 MCP 框架下，代码执行不再是在模型内部完成的，而是在一个受控的侧车环境 (Sidecar Environment) 中进行的。

1. 动态环境搭建

当 Claude 决定运行一段 Python 代码来处理数据时，MCP 服务器会即时拉起一个轻量级的安全容器。该容器预装了常用的科学计算库（如 NumPy, Pandas, Matplotlib）。

2. 双向通信协议

• 模型端：输出符合 MCP 规范的指令。
• MCP 服务器端：接收指令、执行代码，并将 stdout（标准输出）、stderr（错误输出）以及生成的图表附件返回给模型。

3. 安全防护墙 (Security Guardrails)

• 网络隔离：执行代码的容器默认禁止外部网络访问。
• 资源限额：限制 CPU 使用率、内存上限和磁盘 IO，防止恶意代码或无限循环导致主机崩溃。

为什么这让智能体更高效？ (Why is it More Efficient?)

典型工程场景 (Engineering Scenarios)

• 实时数据分析：智能体直接读取本地 CSV 文件，编写并运行 Python 脚本生成可视化趋势图，而无需将原始数据上传到云端。
• 系统自动化运维：通过 MCP 访问受限的终端，智能体可以自主检查日志、分析崩溃堆栈并尝试本地修复方案。
• 本地代码库索引：MCP 服务可以直接访问本地文件系统，为模型提供精确的代码结构视图。

结论 (Conclusion)

MCP 代码执行不仅提升了智能体的“动手能力”，更重要的是，它建立了一种去中心化的工具生态。通过标准化的协议，我们让智能体能够以一种前所未有的安全、解耦的方式，深度介入到真实世界的计算任务中。

超越权限提示：让 Claude Code 更安全且自主

Beyond permission prompts: making Claude Code more secure and autonomous

如果 AI 每执行一个命令都要人类点一次“允许”，那它就不是真正的智能体。我们设计了一套安全架构，旨在减少干扰的同时，通过工程化手段确保系统的绝对受控。

在开发 Claude Code（我们的命令行编码工具）时，我们面临一个悖论：为了提高生产力，智能体需要能够自主运行脚本、读写文件和执行测试；但赋予它这些权限，意味着必须承担系统误操作或遭受攻击的风险。

传统“权限提示”的局限性 (The Limits of Permission Prompts)

最简单的方案是“人机共驾（Human-in-the-loop）”，即每一步操作都弹出确认框。但这种模式存在以下弊端：

1. 警报疲劳 (Alert Fatigue)：频繁的点击会让用户产生麻木感，从而在不经意间批准了危险的操作。
2. 破坏流动感 (Flow Distruption)：工程师希望 AI 在后台修复 10 个 Bug，而不是每 5 秒钟被打断一次。

我们如何重构安全模型 (How We Reimagined the Security Model)

1. 意图分类与分级授权 (Intent Classification)

我们并不是一律放行，而是通过模型对操作意图进行分级：

• 低风险 (Read-only)：读取文件、检查 Git 状态。这些操作默认授权。
• 中风险 (Local Write)：修改代码、创建本地分支。系统会监控变动并支持“一键撤销（Undo）”。
• 高风险 (Destructive/Network)：执行 rm -rf、推送代码至远程库、发送网络请求。这类操作必须显式确认。

2. 运行时监视器 (Runtime Monitor)

我们在 Claude Code 内部运行了一个“安全看门狗”。它不是基于规则的死板检查，而是：

• 语义审计：在命令执行前，另一个轻量级模型会并行审查该命令是否符合当前的工程任务描述。
• 资源限制：限制 AI 能够访问的目录范围（Sandboxed Workspace），防止其越权访问主机的敏感配置文件（如 .ssh 或 .env）。

3. 基于“信任窗口”的自主权 (Trust Windows)

我们引入了“会话信任期”的概念。当用户在特定任务中连续批准了两次相似的操作后，系统会询问：“是否在接下来的 10 分钟内允许执行同类操作？”这在确保安全的前提下，极大地提升了自动化效率。

安全性实验数据 (Security Lab Results)

结论 (Conclusion)

智能体的安全性不应仅仅依赖于人类的勤奋，而应构建在智能化的防御层之上。通过将安全策略与任务上下文深度耦合，我们让 Claude Code 既能像资深工程师一样自主工作，又能像受限沙盒一样安全可靠。

AI 智能体的有效上下文工程

Effective context engineering for AI agents

给智能体投喂过多的信息往往适得其反。有效的上下文工程不是关于“填充”窗口，而是关于“精炼”信号。

在构建复杂的 AI 智能体（如 Claude Code）时，我们发现简单的“把所有文件都塞进上下文”会导致模型注意力分散、推理速度变慢以及幻觉增加。我们开发了一套名为“上下文工程”的方法论，以确保智能体始终拥有最相关的信息。

为什么“多”并不总是“好”？ (The Curse of Too Much Context)

尽管 Claude 拥有巨大的上下文窗口（Context Window），但将 200,000 个 Token 全部填满会带来三个工程难题：

1. 大海捞针效应 (Lost in the Middle)：模型在处理位于上下文中间位置的信息时，性能往往弱于两端。
2. 推理成本增加：更多的 Token 意味着更高的延迟和更高的 API 费用。
3. 噪音干扰：不相关的代码片段可能会诱导模型产生错误的逻辑假设。

核心技术策略 (Core Strategies)

1. 动态上下文提取 (Dynamic Context Extraction)

我们不一次性提供整个代码库，而是通过“多轮检索”来构建上下文：

• 第一步：骨架图 (Skeletal Map)：仅提供文件目录树和核心定义的摘要。
• 第二步：意图导航：让智能体自主决定需要读取哪些具体文件（例如：使用 grep 或 ls 工具）。
• 第三步：局部加载：仅将智能体明确请求的代码段装载进上下文。

2. 上下文缓存 (Context Caching)

对于那些在多轮对话中保持不变的信息（如系统提示词、基础库文档、项目架构图），我们使用 Prompt Caching 技术。

• 性能提升：减少了重复数据的处理时间，首字响应速度（TTFT）提升了 2x 以上。
• 成本优化：缓存部分仅需支付极低的缓存写入和读取费用。

3. 结构化“思维暂存区” (Structured Scratchpads)

我们强制智能体在执行任务前使用一个特殊的 Markdown 区域来整理它的上下文：

• 已知事实：当前确认的系统状态。
• 待办事项：接下来的逻辑步骤。
• 缺失信息：目前尚不清楚、需要进一步查询的变量或逻辑。

实验对比：上下文密度对成功率的影响

实用建议 (Practical Tips for Engineers)

• 使用 XML 标签：Claude 特别擅长处理被 XML 标签包裹的信息（如 <code_snippet> 或 <documentation>），这有助于模型区分不同来源的数据。
• 区分“短期记忆”与“长期记忆”：将用户当前的操作历史作为短期记忆，而将项目规范作为长期记忆，并在 Prompt 中明确其优先级。
• 定期清理：当任务从“修复 Bug”转变为“重写文档”时，主动清除之前的调试日志，防止旧噪音干扰新任务。

结论 (Conclusion)

上下文工程是智能体开发的“精细化运营”阶段。通过精确控制模型在每一时刻所能看到的信息，我们不仅能提升智能体的执行效率，更能在本质上增强其解决复杂、长链路问题的能力。

近期三个问题的回顾分析

A postmortem of three recent issues

在 Anthropic，我们信奉“从失败中学习”。本文透明地记录了近期我们在基础设施和模型部署中遇到的三个典型技术问题，以及我们如何修复它们。

构建可靠的 AI 系统不仅需要顶尖的模型，还需要稳健的工程底座。当系统规模达到数百万用户时，即使是万分之一概率的边缘案例（Edge Cases）也会演变成重大的服务中断。

问题一：缓存击穿导致的延迟激增 (Issue 1: Cache Stampede)

故障现象

在一次热门模型更新后，我们的 API 首字响应时间（TTFT）在高峰期突然飙升了 500%，导致大量请求超时。

根因分析

我们发现是上下文缓存（Context Caching）机制在高并发下触发了“重算风暴”。当一个极其热门的项目（如大型开源库的文档）缓存过期时，数千个并发请求发现缓存失效，同时启动了昂贵的重新计算流程，瞬间击穿了后端推理节点的算力水位。

修复方案

• 引入互斥锁 (Request Collapsing)：对于相同的缓存键，只允许一个请求负责重新计算，其余请求挂起等待结果。
• 预热机制：在缓存过期前 5%，由后台进程自动触发预刷新。

问题二：智能体死循环导致的 Token 熔断 (Issue 2: Agent Loop & Token Burn)

故障现象

某个自动编码智能体在处理一个循环依赖的 Git 仓库时，进入了死循环。在短短 10 分钟内，该账户消耗了数千美元的 Token 额度。

根因分析

该智能体在执行 git checkout 时遇到了未预料到的冲突，它尝试通过 git status 诊断，但由于逻辑错误，它陷入了“报错 -> 诊断 -> 报错”的闭环。由于缺乏跨轮次的重复行为检测，系统未能及时止损。

修复方案

• 语义哈希检测 (Semantic Hash Detection)：我们开始对智能体的连续 N 步行动进行向量化对比。如果检测到行动序列的语义高度重合，系统将强制注入一个“反思（Reflect）”步骤，要求模型重新评估策略。
• 阶梯式频率限制：对同一个任务的 API 调用频率实施指数级退避（Exponential Backoff）。

问题三：多模态输入中的“隐形”截断 (Issue 3: Silent Truncation in Multimodal Inputs)

故障现象

用户反馈在上传长文档配图时，Claude 的回答质量显著下降，经常忽略图片中的关键文字信息。

根因分析

这是一个隐蔽的工程 Bug。在我们的图像预处理流水线中，为了节省显存，系统会自动调整图像尺寸。然而，对于长图（Long screenshots），简单的等比例缩放导致文字像素低于 OCR 识别的阈值，而系统并未向模型或用户发出“画质受损”的警告。

修复方案

• 分片处理 (Tiling Strategy)：对于长图，不再全局缩放，而是智能切分为多个高分辨率的子图。
• 置信度反馈：如果预处理层发现图像特征丢失严重，会向推理引擎发送一个 Metadata 标记，提醒模型“当前输入模糊，请谨慎推理”。

工程总结 (Engineering Takeaways)

1. 监控必须具备语义化：传统的 CPU/内存监控无法捕获智能体的逻辑死循环。
2. 静默失败是最大的敌人：无论是缓存击穿还是图像截断，系统应具备更强的自我感知能力。
3. 容错重于防御：承认系统会出错，并建立强大的“一键回滚”和“损耗隔离”机制。

与智能体协作，为智能体编写高效工具

Writing effective tools for agents — with agents

最了解智能体需要什么样工具的，往往是智能体自己。我们探索了一套流程，让 Claude 参与到其自身工具库（Toolsets）的设计、测试与迭代中。

在构建智能体系统时，工程师经常会陷入“沟通错位”：我们编写的 API 接口可能符合人类的思维习惯，但对于 AI 模型来说，这些接口可能存在描述模糊、参数过于复杂或反馈信息不足的问题。

为什么让 AI 参与工具设计？ (Why Co-design with AI?)

1. 消除描述盲区：AI 知道哪些 description（描述文案）能让它更准确地识别调用时机。
2. 优化数据结构：AI 倾向于更扁平、语义更明确的 JSON 结构，而非深层嵌套的复杂对象。
3. 闭环测试：AI 可以快速模拟成百上千种边缘情况，来验证工具的鲁棒性。

“AI 驱动工具工程”的三步法 (The Three-Step Workflow)

1. 需求定义与原型设计 (Drafting)

当我们发现智能体在处理特定任务（如“修改数据库 Schema”）表现挣扎时，我们会向 Claude 发起一个元任务：

• 人类指令：“分析你最近 10 次失败的操作记录，设计一个能帮你更好完成任务的新工具。”
• 输出：Claude 会提议一个新的 API 定义，包括函数名、参数 Schema 以及它期望看到的返回格式。

2. 自动化脚手架生成 (Scaffolding)

一旦设计方案确定，我们利用 Claude 自动生成：

• 后端胶水代码（Python/TypeScript）。
• 符合 MCP 协议的接入配置。
• 模拟器（Mocks）：用于在真实 API 就绪前进行逻辑验证。

3. 协同调试与重构 (Iterative Refinement)

这是最关键的一步。智能体会亲自“试用”这个新工具。

• 如果返回的错误信息太简略，智能体会指出：“我无法区分这是权限错误还是路径不存在，请在 error 字段中增加更多上下文。”
• 结果：工具的进化方向是“对 AI 友好（AI-Friendly）”的。

实验案例：GitHub 管理工具的进化

通过增加“语义重构”这种高内聚工具，智能体避免了大量细碎的文件读写操作，从而显著降低了错误累积。

核心洞察：AI-Native 接口规范 (AI-Native API Design)

在与智能体协作的过程中，我们总结了以下原则：

• 自描述性 (Self-describing)：工具的每一个参数都应该有详细的 enum 定义和示例。
• 结果冗余 (Result Redundancy)：不仅返回执行结果，还要返回执行后的系统状态摘要，帮助模型确认操作生效。
• 原子性与组合性平衡：虽然单一功能的工具更安全，但对于复杂任务，提供一个高度集成的“宏指令”工具往往能提升成功率。

结论 (Conclusion)

工具不再是静态的库，而是智能体能力的延伸。通过让 AI 参与到工具的“生产线”中，我们正在构建一种共生进化的工程模式：工程师负责安全底座，而 AI 负责打磨它最趁手的“武器”。

桌面扩展：Claude Desktop 的一键式 MCP 服务安装

Desktop Extensions: One-click MCP server installation for Claude Desktop

为了让非技术用户也能享受到智能体工具的便利，我们为 Claude Desktop 引入了“桌面扩展”功能，实现了 MCP 服务器的一键式部署与集成。

模型上下文协议（MCP）的初衷是标准化，但对于大多数用户来说，手动配置 JSON 文件、设置环境变量和调试本地 Node.js 环境仍然门槛过高。我们决定通过工程优化，将这一过程彻底简化。

核心挑战：本地环境的复杂性 (The Complexity of Local Environments)

在用户本地机器上运行 MCP 服务器面临以下挑战：

1. 依赖冲突：用户的机器可能没有安装特定版本的 Python 或 Node.js。
2. 权限管理：如何确保第三方扩展不会在未经授权的情况下访问用户的敏感文件？
3. 发现机制：用户如何轻松找到并安装社区开发的 MCP 工具？

解决方案：桌面扩展架构 (Desktop Extensions Architecture)

1. 容器化/沙盒运行环境

我们为 Claude Desktop 开发了一个轻量级的运行引擎，它可以自动管理扩展所需的运行时环境。

• 自包含：扩展程序自带必要的依赖，或者通过预定义的容器镜像运行。
• 资源隔离：每个扩展在独立的进程中运行，通过标准 MCP 协议与 Claude 通信。

2. 一键式安装流程 (One-click Installation)

我们设计了一个简单的协议处理程序（Protocol Handler）。当用户点击网页上的“安装到 Claude”按钮时：

• 浏览器唤起 Claude Desktop。
• 客户端解析扩展的清单文件（Manifest），并向用户展示权限请求（如：需要访问 GitHub 或本地特定文件夹）。
• 用户确认后，系统自动完成配置，智能体立即获得新能力。

3. 动态工具发现

Claude 现在可以根据当前的上下文，主动建议用户安装相关的扩展。例如，当用户粘贴一个 SQL 查询时，Claude 会提示：“检测到 SQL，是否安装数据库连接扩展以直接运行查询？”

实验结果：用户采纳率 (Adoption Metrics)

结论 (Conclusion)

通过“桌面扩展”，我们打破了开发者工具与普通用户之间的壁垒。这不仅是一个功能更新，更是迈向“AI 个人助理”生态系统的关键一步——让每个人都能根据自己的需求，通过简单的点击来定制 Claude 的能力边界。

Claude Code：智能体编码的最佳实践

Claude Code: Best practices for agentic coding

智能体编码（Agentic Coding）不仅是自动补全，它是与一个拥有自主行动能力的实体共同开发。以下是我们从开发 Claude Code 过程中总结的高效协作模式。

当 AI 能够自主执行测试、阅读日志并跨文件修改代码时，开发者的角色正在从“打字员”转变为“审查者”和“决策者”。为了最大化这种协作的产出，我们建议遵循以下最佳实践。

1. 任务分解：从“做什么”到“怎么做” (Task Decomposition)

尽管 Claude Code 可以处理复杂任务，但一次性给出过于庞大的指令（例如“重构整个预测模块”）容易导致逻辑漂移。

• 推荐做法：将大任务拆分为可验证的子任务。例如，先让它“分析现有接口并生成文档”，确认无误后再执行“实现新的接口逻辑”。
• 工程价值：这不仅降低了幻觉概率，还方便你在每个里程碑进行代码评审。

2. 建立“反馈闭环” (The Feedback Loop)

智能体最强大的能力在于它能根据错误进行自愈。

• 让测试驱动开发 (TDD)：在让 Claude 修改代码前，先让它编写（或运行现有的）测试用例。如果测试失败，它会根据报错信息自动修复代码。
• 利用日志：鼓励智能体在运行时使用 grep 或查看 tail -f 实时日志。比起猜测，观察真实的运行时错误更能让智能体快速定位问题。

3. 管理上下文：保持“认知”的精简 (Context Management)

虽然 Claude 可以读取你的整个项目，但在对话中保持专注依然很重要。

• 精准导航：使用 ls、find 或 grep 来帮助智能体锁定目标文件，而不是让它盲目猜测。
• 清理历史：如果一个任务已经完成并开启了新任务，建议启动一个新的会话或清除过时的上下文信息，防止旧的错误假设干扰新的开发逻辑。

4. 审查：信任但要验证 (Trust, but Verify)

作为人类开发者，你拥有最终的签名权。

• 使用 git diff：在 Claude Code 提示“任务完成”后，养成使用 diff 工具检查每一行变动的习惯。
• 审查副作用：特别关注那些看似无关的变动，AI 可能会为了解决 A 问题而不小心修改了 B 处的全局变量或依赖。

5. 处理冲突与幻觉 (Handling Conflicts)

当 Claude 卡住或不断尝试错误的修复方案时：

• 手动介入：直接告诉它：“你的第 X 步操作是错误的，因为底层逻辑是 Y，请重新尝试。”
• 提供示例：如果你有一个类似的成功案例，直接提供代码片段作为参考。

总结：一种新的编程节奏

结论 (Conclusion)

Claude Code 的目标不是取代工程师，而是消除编程中的机械劳动。通过遵循这些最佳实践，工程师可以将精力集中在最需要人类判断力的领域：系统设计、安全性分析和复杂业务逻辑的建模。

“思考”工具：让 Claude 在复杂工具使用场景中停下来思考

The “think” tool: Enabling Claude to stop and think

对于极其复杂的工程问题，即便是最强的模型也需要“深呼吸”。我们引入了显式的思考工具，允许 Claude 在执行操作前进行多步骤的逻辑推演。

在处理多步骤的智能体任务时，我们观察到一个现象：模型有时会过早地触发工具调用，导致参数错误或逻辑漏洞。为了解决这个问题，我们为 Claude 3.5 系列模型赋予了“显式思考”的能力。

什么是“思考”工具？ (What is the “Think” Tool?)

传统的思维链（CoT）通常混合在对话回复中。而 think 工具是一个受限且结构化的输出空间，模型在此空间内进行自我博弈、方案对比和潜在风险预判，这些内容在最终输出给用户或执行器之前完成。

核心特性：

1. 递归推理：模型可以在思考空间内模拟“如果执行 A 可能会发生 B”的逻辑链。
2. 隐藏性与专注度：思考过程可以被系统剥离，不直接干扰用户的 UI 界面，从而保持界面的整洁。
3. 计算分配：赋予模型更多的时间（和 Token）去处理高难度的逻辑节点。

为什么这对智能体至关重要？ (Why it matters for Agents?)

在涉及外部环境交互时，错误的成本很高。通过 think 工具，智能体表现出了显著的进步：

• 减少“冲动型”调用：在面对歧义指令时，智能体会先通过思考确认：“用户是想删除这个文件，还是仅仅重构它？”
• 参数预校验：在调用具有复杂 JSON Schema 的工具前，模型会在思考区先构造一遍参数，检查是否符合类型要求。
• 长链路规划：对于需要连续调用 5 个 API 的任务，模型会先在思考区制定完整的“作战计划”。

实验数据：引入“思考”后的表现提升

我们对比了开启与关闭 think 工具后，模型在处理复杂工程任务时的成功率：

工程实现建议 (Engineering Implementation)

• 为思考分配配额：在 API 调用中，我们可以通过设置 max_thought_tokens 来控制模型在复杂问题上“钻牛角尖”的程度。
• 监控思考质量：通过分析思考区的长度和语义多样性，工程师可以判断当前的 Prompt 是否给模型造成了过大的认知负担。
• 用户透明度：在开发 IDE 插件或控制台工具时，可以选择性地向用户展示简化的思考摘要，增强人机之间的信任感。

结论 (Conclusion)

“思考”工具的引入，标志着 AI 正在从“概率预测机器”进化为“理性决策系统”。通过让模型拥有停下来审视自己逻辑的能力，我们不仅提高了任务的成功率，更显著增强了 AI 在严苛工程环境下的可靠性。

借助 Claude 3.5 Sonnet 提高 SWE-bench Verified 标准

Raising the bar on SWE-bench Verified with Claude 3.5 Sonnet

在真实世界的软件工程评估中，Claude 3.5 Sonnet 刷新了纪录。本文探讨了我们如何通过工程优化，使模型在解决真实 GitHub 问题上展现出质的飞跃。

SWE-bench 被公认为 AI 编程领域最具挑战性的基准测试，它要求模型修复真实开源项目中的 Bug。而 “Verified” 版本通过人工筛选，确保了测试用例的质量和评价的公正性。

核心成绩 (Key Results)

Claude 3.5 Sonnet 在 SWE-bench Verified 上的得分达到了 49.4%，大幅领先于之前的模型。这一成绩不仅代表了逻辑能力的提升，更代表了模型在以下方面的突破：

1. 长程轨迹处理：平均每个修复任务涉及读取数十个文件并进行多轮测试尝试。
2. 工具调用精度：模型需要熟练使用 grep, edit, python 等工具。

成功的工程要素 (Engineering Success Factors)

1. 更好的工具集（Toolset）

我们为模型提供了更符合人类直觉的命令行工具。例如，相比于直接输出整个文件，模型更倾向于使用能够进行“局部修改”的差异编辑工具，这极大地降低了 Token 消耗和出错概率。

2. 自我验证机制 (Self-Correction)

模型被赋予了“运行测试用例”的权限。如果它生成的补丁未能通过单元测试，它会阅读 Traceback 报错并自动进入第二轮修复。

3. 处理大规模上下文

在面对拥有数千个文件的仓库时，模型表现出了极强的“代码导航（Code Navigation）”能力，能够通过搜索符号定义快速定位相关逻辑。

结论 (Conclusion)

这一纪录证明了 AI 已经具备了处理生产级代码的能力。然而，50% 左右的成功率也提醒我们，在复杂系统架构理解和多模块耦合修复方面，AI 仍有很长的路要走。