权威开发者指南：Claude Code 与 Anthropic API

@https://www.anthropic.com/learn/build-with-claude

第一部分：Anthropic 开发者生态系统导论

为了高效地利用 Anthropic 的技术，开发者必须首先理解其提供的工具生态系统。这个生态系统并非单一的产品，而是一个分层的工具集，旨在满足从快速原型设计到生产级应用集成的不同需求。“Claude Code”是这个生态系统中的一个特定工具，理解其定位以及与其他组件的关系至关重要。

1.1 解构 Anthropic 工具包

Anthropic 的平台围绕一个核心 API 构建，并通过不同层次的抽象工具提供服务，以适应各种开发工作流程。

• 核心：Messages API 这是与所有 Claude 模型进行交互的基础 RESTful 接口。所有其他工具和 SDK，其本质上都是对该 API 的封装。它采用无状态、基于对话轮次（alternating turns）的模式运行，为开发者提供了最底层的控制能力。  
• 库：客户端 SDK (Python & Node.js/TypeScript) 这是将 Claude 集成到应用程序中的主要工具。Anthropic 提供了针对 Python (anthropic) 和 TypeScript/Node.js (@anthropic-ai/sdk) 的官方 SDK。这些库封装了 Messages API 的复杂性，处理了 HTTP 请求、身份验证头和 JSON 序列化等样板任务，极大地简化了开发过程。  
• 命令行环境：Claude Code 这是一个独特的 npm 包 (@anthropic-ai/claude-code)，作为一个专门的命令行工具和开发环境而存在。它的主要目的不是用于生产应用的库集成，而是为了简化开发者的“内循环”工作流，特别是在处理本地文件系统、快速迭代和原型设计时。  
• 更广泛的生态系统 除了上述核心组件，Anthropic 还提供了一系列支持资源，包括：用于 API 密钥管理和实验的 Anthropic Console 和 Workbench；提供代码片段和常见工作流程的 Anthropic Cookbook；以及用于快速构建应用程序的 Quickstarts 代码仓库。  

这种分层结构并非偶然，而是经过深思熟虑的设计。它反映了 Anthropic 对开发者工作流程的深刻理解。首先，最底层的 REST API 提供了最大的控制权和语言无关性，适用于需要精细控制或使用非官方支持语言的场景。其次，客户端 SDK 为主流语言（Python 和 TypeScript/Node.js）的开发者提供了便利性和安全性（例如 TypeScript 中的类型定义），显著减少了集成所需的时间和精力。最后，  

claude-code 工具则完全针对另一种不同的工作场景：开发者在本地环境中工作，希望快速将 Claude 的智能应用于现有项目文件，而无需编写完整的脚本或应用程序。

这种设计哲学表明，Anthropic 认识到“使用 LLM 进行构建”并非单一活动，而是包含多个不同阶段的生命周期：探索（通过 Workbench）、在本地项目上进行快速原型设计（使用 

claude-code），以及最终的生产集成（使用 SDK 或直接调用 API）。通过为每个阶段提供专门优化的工具，Anthropic 旨在减少整个开发过程中的摩擦，这是一种比仅仅提供单一 API 端点更为成熟和全面的平台策略。

第二部分：入门指南：设置与身份验证

本节将提供详尽的、按部就班的设置指南，从创建账户到安装和验证 claude-code 工具，并重点强调 API 密钥管理的安全最佳实践。

2.1 基础步骤：账户与 API 密钥

• 账户创建 首先，开发者需要访问 Anthropic 控制台 (console.anthropic.com) 注册或登录开发者账户。  
• API 密钥生成 登录后，在控制台导航至“API Keys”部分。点击“Create Key”按钮，为密钥命名后即可生成。至关重要的一步是：立即复制并妥善保管生成的 API 密钥。出于安全考虑，该密钥只显示一次，如果丢失，将无法再次查看，只能重新生成。  
• API 密钥管理 Anthropic 提供了工作区（workspaces）功能，允许开发者根据不同的用例对 API 密钥进行分段管理和控制开销。对于更高级的管理需求，还可以通过 Admin API 以编程方式管理密钥。  
• 账单配置 这是一个关键且容易被忽略的步骤。API 密钥在账户没有充值的情况下将无法使用。开发者需要访问控制台的“Billing”部分购买积分。作为预防措施，强烈建议设置每日使用量上限，以避免意外产生高额费用。  

2.2 安装与配置 claude-code

• 系统要求 安装 claude-code 前，请确保系统满足以下要求：
  • 操作系统: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 或 Windows 10+ (需配合 WSL 1, WSL 2, 或 Git for Windows)
  • 硬件: 4GB+ RAM
  • 软件: Node.js 18+
  • 网络: 需要互联网连接以进行身份验证和 AI 处理。  
• 标准安装 主要的安装命令是 npm install -g @anthropic-ai/claude-code。Anthropic 官方强烈警告  不要使用 sudo 执行此命令，因为这可能导致权限问题和安全风险。  
• 替代安装方法 为适应不同的环境和权限限制，claude-code 提供了多种安装方式：
  • 本地安装: 通过 claude migrate-installer 将全局安装迁移到本地，以避免自动更新时的 npm 权限问题。  
  • 原生二进制安装 (Alpha): 通过 claude install 或 curl 命令直接安装。此方法目前处于 Alpha 测试阶段，支持 macOS, Linux, 和 Windows (通过 WSL)。  
• 平台特定设置 (Windows) Windows 用户需要使用 WSL 或 Git for Windows。如果使用便携式 Git，可能需要通过环境变量 $env:CLAUDE_CODE_GIT_BASH_PATH 指定 bash.exe 的路径。  
• 身份验证流程 claude-code 支持多种身份验证方式，以服务于不同类型的用户：
  1. Anthropic Console (默认): 这是标准的 OAuth 流程，将工具连接到开发者的控制台账户，并要求账户已激活账单功能。这是为构建商业应用的开发者设计的路径。  
  2. Claude.ai Pro/Max 订阅: 适用于拥有消费者订阅计划的用户，可以将 claude-code 的使用与网页版 Claude 的订阅统一管理和计费，主要面向希望将 Claude 用于个人项目的“高级用户”。  
  3. 企业平台: 允许企业用户配置 claude-code 以使用 Amazon Bedrock 或 Google Vertex AI，从而与现有云基础设施集成。  
• 首次运行与验证 安装完成后，建议在项目目录中运行 claude doctor 命令。该命令会检查安装类型、版本并验证整体设置是否正确。  

claude-code 提供的多种安装和身份验证路径，揭示了该工具正从一个单一用途的开发者工具，演变为一个服务于不同用户群体（个人开发者、高级用户、企业）的多功能产品。这种灵活性虽然强大，但也引入了复杂性，需要清晰的文档来引导用户。这些选项的存在是为了服务于特定的受众群体。例如，npm 安装方式主要面向广大的 Web 开发者；原生二进制文件则满足了那些没有 Node.js 环境或偏爱独立可执行文件的用户的需求；而不同的身份验证方式则分别对应商业开发者、个人爱好者和大型企业组织。这一产品策略表明，Anthropic 试图用一个工具捕获广泛的用户光谱，这既是雄心壮志，也意味着开发者需要一份明确的决策指南，帮助他们根据自身情况（例如，“我是一个正在构建 SaaS 应用的独立开发者”）选择正确的设置路径（例如，“使用 npm 安装并通过控制台进行身份验证”）。这也标志着 claude-code 是 Anthropic 的一个严肃的长期项目，而不仅仅是一个次要的实用工具。

第三部分：核心 API 概念：Messages API

Messages API 是所有与 Claude 交互的基石。本节将深入探讨其技术细节，从基本结构到控制模型行为的关键参数。

3.1 Messages API 请求剖析

• 端点与方法: POST /v1/messages。  
• 必需的请求头:
  • x-api-key: 用于身份验证，与特定的工作区绑定。  
  • anthropic-version: 用于指定 API 版本，确保向后兼容性。例如 2023-06-01。  
  • content-type: application/json: 指明请求体的格式为 JSON。  
• JSON 请求体:
  • model: 指定要使用的模型，例如 claude-3-5-sonnet-20240620。  
  • messages: 对话历史数组，是输入的核心部分。
  • max_tokens: 指定模型在响应中生成的最大 token 数量。  

3.2 对话模型：messages 数组

• 无状态设计: 必须强调，API 是无状态的。这意味着开发者在每次请求时都必须发送所有相关的对话历史。这种设计虽然增加了客户端的复杂性，但赋予了开发者完全的控制权。开发者可以实施复杂的策略，如使用滑动窗口来管理上下文、总结长对话的早期部分以节省 token、将 RAG 系统检索到的文档注入历史记录，甚至分叉对话。这种设计哲学将 Anthropic API 定位为构建智能系统的底层“引擎”，而非一个高级的、托管的“聊天机器人服务”。  
• 交替角色: messages 数组必须包含具有交替 role 的对象：user 和 assistant。连续的同角色消息会被合并为一轮。  
• 内容块 (Content Blocks): content 字段可以是一个简单的字符串（这是单个文本块的简写形式），也可以是一个内容块数组。这种结构使得多模态输入（如同时包含文本和图像）成为可能。  
• 视觉能力: 开发者可以通过 base64 编码的数据或 URL 在 messages 数组中包含图像，并需指定 media_type (如 image/jpeg, image/png 等)。  
• 预填充响应: 这是一种高级技术，通过将 messages 数组中的最后一条消息的角色设置为 assistant，可以有效地“为 Claude 开头”，从而引导其响应的起始部分和格式。  

3.3 控制生成：关键参数

• temperature: 控制响应的随机性。该值范围为 0.0 到 1.0。接近 0.0 的值适用于分析性、确定性强的任务；接近 1.0 的值则适用于创造性、生成性的任务。  
• top_p 和 top_k: 这是控制随机性的另外两种方法。Anthropic 的最佳实践建议是：要么调整 temperature，要么调整 top_p，但不要同时调整两者。  
• system 提示: 这是一个顶层参数，用于向 Claude 提供高级指令、上下文或设定角色。这是设置系统级指令的首选方法，因为 Messages API 的 messages 数组中不存在 "system" 角色。  
• stop_sequences: 允许开发者定义一个或多个自定义字符串，当模型生成这些字符串时会立即停止输出。  

3.4 快速参考表

为了便于开发者快速查询和决策，以下提供了两张关键信息汇总表。

表 1：Claude 模型比较与 API 速率限制

开发者的首要决策之一是选择合适的模型，这直接影响到应用的成本、性能和能力。速率限制是生产环境中一个至关重要的非功能性需求。此表将模型的特性与运行限制并列，使开发者能够清晰地看到能力与吞吐量之间的权衡，从而避免代价高昂的架构错误。

表 2：Messages API 关键参数参考

在日常开发中，程序员需要频繁查阅 API 参数的准确名称、类型和默认值。此表作为一个高效的生产力工具，将最常用的参数信息整合在一起，以便快速查阅。

第四部分：生产级应用的高级功能

本节将从核心概念过渡到构建健壮、响应迅速且功能强大的应用所必需的高级特性，涵盖了用于实时交互的流式传输、扩展 Claude 能力的工具使用以及用于离线处理的批处理 API。

4.1 通过流式传输实现实时响应

• 启用流式传输: 在 Messages API 请求中设置 "stream": true 即可激活流式响应。  
• 底层技术：服务器发送事件 (SSE): 流式传输基于 SSE 协议，它允许服务器以增量方式将数据推送到客户端，从而实现实时体验。  
• 使用 SDK 实现: Python 和 TypeScript/Node.js SDK 提供了便捷的方式来处理流。例如，在 Python 中可以通过迭代 stream.text_stream，在 TypeScript 中可以使用 .on('text',...) 事件处理器来接收文本流。  
• 事件流详解: 一个 Anthropic API 流并非简单的文本流，而是一系列结构化的 JSON 事件。一个刚接触此 API 的开发者如果仅按文本流处理，其代码将非常脆弱。理解这个结构化的事件协议是构建可靠实时应用的关键。表 3：流式 API 事件类型

导出到 Google 表格

*数据来源: [19, 20]*

• 处理错误和 Ping: 最佳实践要求代码能够优雅地处理 ping 事件（用于保持连接）和可能在流中途出现的 error 事件（如 overloaded_error）。  

4.2 通过工具使用（函数调用）扩展 Claude

Anthropic 的工具使用（或称函数调用）实现方式本质上是对话式的，而非简单的远程过程调用 (RPC)。这种设计要求开发者将函数调用视为与模型之间的一场对话或协商，这对应用逻辑、状态管理和用户体验设计有着深远的影响。

• 概念: 工具使用是一种机制，允许 Claude 与外部系统、API 和函数进行交互，以获取信息或执行操作。  
• 客户端工具 vs. 服务端工具: 需要区分由开发者自己实现的客户端工具（如自定义函数）和由 Anthropic 托管的服务端工具（如 web_search）。  
• 多步对话流程: 客户端工具的完整交互流程如下：
  1. 定义工具: 在 API 请求的 tools 参数中提供工具的 name、description 和 JSON input_schema。  
  2. Claude 返回 tool_use: API 返回一个 stop_reason 为 tool_use 的响应，其 content 中包含一个 tool_use 类型的内容块，内有唯一的 id、工具 name 和 input 对象。  
  3. 执行工具: 开发者应用解析此响应，使用提供的 input 运行实际的函数。
  4. 返回结果: 开发者发起一个新的 API 请求，在对话历史中追加一条 user 消息，其中包含一个 tool_result 类型的内容块，该块引用了第 2 步的 tool_use_id 并提供了函数执行的 content（结果）。  
  5. Claude 总结最终答案: 模型处理工具结果，并生成一个自然的、结合了工具输出的最终答复。  
• 工具设计最佳实践: 编写极其详尽的工具描述至关重要，因为这是模型理解何时以及如何使用该工具的主要方式。  
• 控制工具执行: 使用 tool_choice 参数可以强制模型使用特定工具 ({"type": "tool", "name": "..."})、任何可用工具 ({"type": "any"}) 或不使用任何工具 ({"type": "none"})。  
• 并行与顺序工具使用: Claude 能够在一次响应中调用多个独立的工具（并行），或在多轮对话中链接依赖的工具（顺序）。  

这种对话式的设计是构建强大代理（agent）的基础。代理不仅仅是函数调用者，更是规划者和推理者。通过使工具使用成为对话的一部分，Anthropic 为代理行为提供了基本的构建模块。开发者必须围绕这种“回合制”的交互模式来设计他们的应用，例如，在 UI 中显示“正在思考...”或“正在使用工具...”的状态，并构建能够编排这些多步调用链的逻辑。

4.3 通过 Message Batches API 进行异步处理

• 使用场景: 当需要处理大量非交互式、异步的请求时（每个批次最多 100,000 个请求），应使用批处理 API。它非常适合文档分析、大规模摘要或分类等任务，处理过程最长可达 24 小时。  
• API 端点: 流程包括 POST /v1/messages/batches 来创建批处理任务，然后使用 GET 端点来检索任务状态和结果。  
• 请求结构: 批处理请求的 requests 数组中的每个项目都包含一个 custom_id（用于匹配结果）和一个 params 对象，后者结构与标准的 Messages API 请求体相同。  

第五部分：Claude 的提示工程艺术与科学

提示工程（Prompt Engineering）是释放 Claude 全部潜能的核心技能，其重要性不亚于编写代码。本节将综合 Anthropic 的官方指南，提供一份全面的提示工程实践手册。

5.1 理念：提示工程 vs. 微调

与模型微调相比，提示工程通常是更优的选择，因为它更快、更便宜、更灵活、需要的数据更少，并且过程更加透明。这为我们深入探讨提示工程技术的重要性奠定了基础。  

5.2 基础提示技术

Anthropic 的提示工程指南并非一堆松散的“技巧”，而是一套用于控制模型认知过程的系统性方法。这些技术（角色、示例、思维链、XML 结构）旨在在模型开始任务之前，为其加载一个特定的“心智模型”或“操作上下文”。

• 清晰直接: 这是最基本也最关键的原则。提供具体、无歧义的指令。  
• 使用 XML 标签构建结构: 这是提示 Claude 的一个基石。使用 <document>, <example>, <instructions> 等标签来清晰地划分提示的不同部分。Claude 经过专门的微调，会对这些标签特别关注。  
• 通过系统提示分配角色: 使用顶层的 system 参数为 Claude 设定一个角色（例如，“你是一位专业的 SQL 开发人员”）。这能极大地提高响应的准确性、语气和专注度。  
• 提供示例（多样本提示）: 深入探讨如何使用 3-5 个高质量的示例来向 Claude 展示期望的输出格式、风格和结构。最佳实践包括确保示例具有相关性、多样性和清晰性。  
• 让 Claude 思考（思维链）: 在给出最终答案之前，指示模型“一步一步地思考”，通常将思考过程置于 <thinking> 标签内。这能改善模型在复杂问题上的推理能力。  
• 预填充 Claude 的响应: 在 messages 数组的最后使用 assistant 角色来为 Claude 的回答开个头，这有助于控制输出格式并减少不必要的寒暄。  

5.3 针对 Claude 4 的高级与特定最佳实践

• 明确并提供上下文: 对于 Claude 4 模型，指令需要更加明确，并解释其背后的“原因”（例如，“不要使用省略号，因为文本转语音引擎会朗读此响应”）。  
• 正面与负面框架: 告诉 Claude 该做什么，而不是不该做什么（例如，使用“使用散文段落”代替“不要使用 markdown”）。  
• 优化代理任务: 使用特定的提示来增强并行工具调用、减少编码任务中的临时文件创建，以及改善前端代码生成。  

5.4 提示工程工具与资源

• 提示生成器: Anthropic 控制台提供了一个工具，可以根据任务描述生成高质量的提示草稿。  
• 提示库与教程: 官方提供了提示库以供开发者获取灵感，以及交互式教程用于动手实践。  

这些技术共同构成了一个完整的“任务规范”，开发者通过它来声明性地编程，指定上下文、数据、期望的输出格式和推理策略。这是一种强大的范式，将开发者的工作从编写命令式代码转变为为 AI 设计认知工作流。

第六部分：战略建议与开发者路线图

本节将提供高层次的建议，帮助开发者做出战略选择，并规划从简单脚本到生产就绪应用的开发路径。

6.1 为任务选择合适的工具

• 何时使用 Console Workbench: 用于初步探索、提示实验和一次性任务。  
• 何时使用 claude-code: 用于快速原型设计、处理本地文件系统、将 Claude 应用于现有代码库以及自动化开发相关任务。  
• 何时使用客户端 SDK: 构建生产应用、服务和后端集成的默认选择。  
• 何时直接使用 REST API: 用于非官方支持语言的应用，或需要对 HTTP 层进行最大程度控制（如自定义代理、超时）的场景。  

6.2 应用开发的分阶段方法

一个成功的 Anthropic 平台项目不仅仅关乎代码，它还关乎应用逻辑与驱动模型的提示之间的协同演进。最高效的开发者会像对待源代码一样，用同样的谨慎和版本控制来对待他们的提示库。

• 第一阶段：原型设计与验证 从 Console Workbench 和 claude-code 开始，快速测试核心想法并开发有效的提示。重点是定义成功标准和构建一小组测试用例。这个阶段主要是关于  提示的发现。
• 第二阶段：构建核心逻辑 转向 Python 或 Node.js SDK。实现核心应用逻辑，重点是稳健地处理 Messages API，包括对话状态管理。
• 第三阶段：扩展与加固 根据需要集成高级功能。为响应式用户体验实现流式传输；为外部数据和操作添加工具使用；为离线作业使用批处理 API。实施全面的错误处理和日志记录。
• 第四阶段：评估与优化 使用结构化评估来测试和改进应用性能，以对照成功标准。通过试验不同的模型（例如，在可能的情况下用 Sonnet 替换 Opus）和实施提示缓存来优化成本和延迟。这个阶段是关于  提示的验证。

6.3 应用的未来保障

• 处理模型更新: 使用 anthropic-version 请求头至关重要。同时应理解，提示通常比微调更能抵抗模型更新带来的变化。  
• 监控与适应: 持续监控应用性能，并准备好随着新模型和功能的发布而调整提示。针对 Claude 4 的最佳实践表明，技术是不断演进的。  

最终，这导向了一种新的软件开发范式：“面向提示的开发 (Prompt-Oriented Development)”。在这种范式中，应用程序的大部分行为由存储在应用代码之外的自然语言提示来定义。这意味着来自软件工程的最佳实践——如版本控制（用 Git 管理提示）、自动化测试（针对评估集运行提示）和模块化（创建可重用的提示模板）——都应该应用于提示的管理。一个成熟的开发团队，其代码库中的 prompts/ 目录将与 src/ 目录同等重要。这是将成功的、可维护的 AI 应用与脆弱的、不可预测的应用区分开来的战略路线图。