Claude 4 提示工程：Agentic Coding 最佳实践与技巧

第一时间捕获有价值的信号

本文译自 Anthropic 发布的官方指南 Claude 4 prompt engineering best practices，经过一周的使用体验，Claude Sonnet 4.5 确实称得上”全球最佳编码模型”，与 Claude 3 系列模型相比，新一代模型经过专门训练，能更精准地理解和执行指令，本文结合官方文档分享一系列具体的使用技巧，以在应用中获得最佳效果（此指南同样适用于 Claude 4 系列的 Opus 4.1, Opus 4, 和 Sonnet 4 模型）。

通用原则

指令应清晰明确

Claude 4 模型能够很好地响应清晰、明确的指令，具体说明期望的输出，有助于获得更好的结果，如果希望 Claude 4 能像之前的模型一样，表现出超越预期的主动性，可能需要更明确地在提示中提出这些要求。

效果较差的示例:

创建一个分析仪表板

效果更佳的示例:

创建一个分析仪表板。请包含尽可能多的相关功能与交互。不要局限于基础功能，而是要力求实现一个功能完备的版本。

补充背景信息以提升模型表现

在指令背后提供相关的背景信息或动机 (例如，向 Claude 解释为何需要这样做) ，能够帮助 Claude 4 模型更好地理解的目标，从而给出更有针对性的回答。

效果较差的示例:

永远不要使用省略号

效果更佳的示例:

你的回答将由文本转语音引擎朗读，所以请不要使用省略号，因为引擎无法识别和朗读它们。

Claude 非常智能，能够从解释中举一反三。

谨慎提供示例和细节

作为精准执行指令能力的一部分，Claude 4 模型会密切关注提供的细节和示例。因此，请确保的示例能够引导模型产生期望的行为，并尽量避免出现不希望看到的行为。

长程推理与状态跟踪

Claude Sonnet 4.5 在需要长程推理 (long-horizon reasoning) 的任务中表现卓越，并具备出色的状态跟踪 (state tracking) 能力。它能够在长时间的会话中保持任务方向，其策略是专注于增量式推进——即每次稳步完成几项子任务，而不是试图一次性解决所有问题。当任务需要跨越多个上下文窗口或进行多轮迭代时，这一能力尤为突出。在这种场景下，Claude 能够处理复杂任务，保存当前状态，然后在新的上下文窗口中无缝衔接，继续工作。

上下文感知与多窗口工作流

Claude Sonnet 4.5 具备 上下文感知 (context awareness) 能力，这意味着模型可以在整个对话过程中，实时了解当前上下文窗口的剩余容量 (即 “Token 预算”)。这使得 Claude 能够更有效地规划和执行任务，因为它清楚自己还有多少“发挥空间”。

管理上下文窗口限制:

如果在一个能够自动压缩上下文，或允许将上下文保存到外部文件 (例如 Claude Code 中的做法) 的 AI 智能体 (AI Agent) 框架中使用 Claude，我们建议将这一信息加入到提示中，以便 Claude 能够相应地调整其行为。否则，当接近上下文窗口的容量极限时，Claude 可能会自然地尝试结束当前工作。以下是一个提示示例：

你的上下文窗口在接近容量极限时会自动被压缩，让你能够从中断的地方无限期地继续工作。因此，不要因为 Token 预算不足而提前中止任务。当你接近 Token 预算上限时，请在上下文窗口刷新前，将当前进度和状态保存到内存中。请始终保持持久和自主，即便预算即将耗尽，也要力求完整地完成任务。无论上下文剩余多少，都不要人为地提前中止任何任务。

内存工具 与上下文感知能力是天作之合，两者结合可以实现上下文之间的无缝过渡。

多上下文窗口工作流

对于需要跨越多个上下文窗口的复杂任务，可以采用以下策略：

为首个上下文窗口设计专门的提示: 利用第一个上下文窗口搭建起任务框架 (例如，编写测试用例、创建初始化脚本) ，然后在后续的窗口中专注于迭代完成待办事项列表。
让模型以结构化格式编写测试: 要求 Claude 在开始工作前创建测试，并使用结构化的格式 (例如 tests.json 文件) 来进行追踪。这样做有助于提升项目长期的迭代能力。同时，要向 Claude 强调测试的重要性：“绝不允许删除或修改测试，因为这可能导致功能缺失或引入错误。”
配置便捷的辅助工具: 鼓励 Claude 创建初始化脚本 (例如 init.sh) ，用于便捷地启动服务、运行测试套件和代码风格检查工具 (linter) 。这可以避免在开启新的上下文窗口时重复进行环境设置。
从零开始 vs 上下文压缩: 当一个上下文窗口被清空时，可以考虑让模型在一个全新的窗口中从零开始，而不是依赖上下文压缩。Sonnet 4.5 非常擅长从本地文件系统中发现和恢复任务状态。在某些情况下，利用这一特性可能比压缩上下文更有效。需要明确指示它应该如何开始：
- “调用 pwd 命令；你只能读写当前目录下的文件。”
- “请查阅 progress.txt、tests.json 和 git 日志。”
- “在开始实现新功能之前，请先手动运行一个基础的集成测试。”
提供验证工具: 随着自主任务的持续时间变长，Claude 需要能够在没有持续人工干预的情况下验证工作的正确性。类似 Playwright MCP 服务器或用于测试用户界面 (UI) 的计算机控制工具，都将非常有帮助。
鼓励充分利用上下文窗口: 提示 Claude 在转向下一步之前，高效地完成当前组件的工作：

这是一项非常耗时的任务，因此清晰地规划工作会很有帮助。我们鼓励你充分利用整个输出上下文来完成任务——只要确保不要在仍有大量工作未提交时耗尽上下文即可。请系统地持续工作，直到完成这项任务。

状态管理的最佳实践

使用结构化格式保存状态数据: 当追踪结构化信息时 (例如测试结果、任务状态) ，使用 JSON 或其他结构化格式，能帮助 Claude 更好地理解数据模式。
使用非结构化文本记录进度: 对于记录总体进展和上下文信息，自由格式的文本笔记非常有效。
使用 git 进行状态跟踪: Git 不仅能记录已完成工作的日志，还能创建可供随时恢复的检查点。Claude Sonnet 4.5 在利用 git 跨多个会话追踪状态方面表现得尤为出色。
强调增量式推进: 明确要求 Claude 追踪自身进度，并专注于以增量的方式完成工作。

// 结构化的状态文件 (tests.json)
{
  "tests": [
    {"id": 1, "name": "authentication_flow", "status": "passing"},
    {"id": 2, "name": "user_management", "status": "failing"},
    {"id": 3, "name": "api_endpoints", "status": "not_started"}
  ],
  "total": 200,
  "passing": 150,
  "failing": 25,
  "not_started": 25
}

// 进度笔记 (progress.txt)
第 3 次会话进度：
- 修复了身份验证 Token 的验证逻辑。
- 更新了用户模型以处理边界情况。
- 下一步：调查 user_management 测试的失败原因 (测试编号 #2) 。
- 注意：不要删除测试，这可能导致功能缺失。

沟通风格

与之前的模型相比，Claude Sonnet 4.5 的沟通风格更加简洁和自然：

更直接，有理有据: 它会提供基于事实的进度报告，而不是自我表扬式的更新。
更接近日常对话: 语言更流畅、更口语化，减少了机器感。
更精炼: 除非特别要求，否则为了效率，它可能会省略详细的摘要。

这种沟通风格能准确地反映已完成的工作，而不会进行不必要的赘述。

针对特定情况的指导建议

平衡输出的详细程度

Claude Sonnet 4.5 倾向于追求效率，可能会在调用工具后省略口头总结，直接执行下一步操作。虽然这能简化工作流程，但有时可能希望更清晰地了解它的推理过程。

如果希望 Claude 在工作时提供进度更新，可以使用如下提示：

在完成一项涉及工具使用的任务后，请简要总结一下你所做的工作。

工具使用模式

Claude Sonnet 4.5 经过训练，能够精准地执行指令，因此明确指示它使用特定工具会获得更好的效果。如果说“你能提些修改建议吗？”，它有时只会给出建议，而不会直接实施——即便的本意可能是让它直接修改。

要让 Claude 采取行动，的指令需要更明确：

效果较差 (Claude 可能只会提出建议):

你能建议一些改动来优化这个函数吗？

效果更佳 (Claude 将直接进行修改):

修改这个函数，提升它的性能。

为了让 Claude 默认更主动地采取行动，可以在系统提示中加入以下内容：

<default_to_action>
默认情况下，请直接实施修改，而不是仅仅提出建议。如果用户的意图不明确，请推断出最有可能有帮助的操作并执行，利用工具来获取缺失的细节，而不是靠猜测。请尝试推断用户是否希望进行工具调用 (例如，编辑或读取文件) ，并据此行动。
</default_to_action>

反之，如果希望模型默认更为谨慎，不轻易直接进行修改，只在明确要求下才行动，可以用类似下方的提示来引导它的行为：

<do_not_act_before_instructions>
在没有明确指令的情况下，不要直接进行代码实现或文件修改。当用户的意图不明确时，应默认提供信息、进行研究并给出建议，而不是直接采取行动。只有在用户明确要求时，才进行编辑、修改或实现。
</do_not_act_before_instructions>

控制响应格式

我们发现，以下几种方法在引导 Claude 4 模型的输出格式方面特别有效：

多用肯定句，少用否定句
- 不推荐：“不要在你的回答中使用 Markdown。”
- 推荐：“你的回答应由流畅的散文段落构成。”
使用 XML 标签来指定格式
- 推荐：“请将你回答中的散文部分放在 <smoothly_flowing_prose_paragraphs> 标签内。”
让提示的风格与期望的输出风格保持一致

在提示中使用的格式风格可能会影响 Claude 的回应风格。如果在控制输出格式时仍然遇到困难，我们建议尽可能让提示的风格与期望输出的风格相匹配。例如，在提示中不使用 Markdown，有助于减少模型输出中的 Markdown 内容。
使用详细的提示来指定特定的格式偏好

若想更精确地控制 Markdown 和格式的使用，可以提供如下明确的指导：

<avoid_excessive_markdown_and_bullet_points>
在撰写报告、文档、技术说明、分析或任何长篇内容时，请使用清晰、流畅的散文，构成完整的段落和句子。使用标准的段落换行来进行组织，并将 Markdown 主要保留用于 `行内代码`、代码块 (```...```) 和简单的标题 (###) 。避免使用 **粗体** 和 *斜体*。

请不要使用有序列表 (1., 2., ...) 或无序列表 (*, -, +) ，除非：a) 所呈现的内容确实是独立的条目，使用列表是最佳选择；或者 b) 用户明确要求使用列表或排名。

尽量将条目自然地融入句子中，而不是使用项目符号或数字罗列。这一指导原则在技术写作中尤其重要。使用散文而非过多的格式化能提升用户体验。绝不要输出一连串过短的项目符号列表。

的目标是生成可读性强、行文流畅的文本，能够自然地引导读者理解的思路，而不是将信息分割成一个个孤立的要点。
</avoid_excessive_markdown_and_bullet_points>

研究与信息收集

Claude Sonnet 4.5 展现了卓越的 AI 智能体搜索能力，能够高效地从多个来源查找并整合信息。为获得最佳的研究结果，请遵循以下建议：

提供明确的成功标准: 清晰地定义怎样的回答才算是成功解决了的研究问题。
鼓励进行多源验证: 要求 Claude 交叉验证来自不同来源的信息。
对于复杂的研究任务，采用结构化的方法:

请以结构化的方式搜索这些信息。在收集数据的过程中，提出几个相互竞争的假设。在进度笔记中记录你对各个假设的置信度，以便进行校准。定期自我审视你的研究方法和计划。更新一个假设树或研究笔记文件，以保存信息并保持过程的透明度。请系统地分解这项复杂的研究任务。

这种结构化的方法让 Claude 能够查找和整合几乎任何信息，并对研究结果进行迭代式审视，无论资料库的规模有多大。

子智能体编排

Claude Sonnet 4.5 在原生的子智能体 (subagent) 编排能力上有了显著提升。模型能够识别出哪些任务适合委托给专门的子智能体处理，并能主动进行分配，无需用户明确指示。

要利用这一特性，可以：

确保子智能体工具有清晰的定义: 准备好可用的子智能体工具，并在工具定义中清晰地描述它们的功能。
让 Claude 自然地进行任务编排: 在没有明确指令的情况下，Claude 会适当地进行任务委托。
必要时调整其主动性:

仅在任务能明确从一个拥有独立上下文窗口的、独立的智能体中获益时，才将任务委托给子智能体。

模型自我认知

如果希望 Claude 在的应用中能够正确地表明自己的身份，或使用特定的 API 字符串，可以使用如下提示：

我是 Claude，一个由 Anthropic 创建的助手。当前使用的模型是 Claude Sonnet 4.5。

对于需要在应用中指定模型字符串的、由大语言模型 (LLM) 驱动的程序：

当需要使用大语言模型时，请默认选择 Claude Sonnet 4.5，除非用户另有指定。Claude Sonnet 4.5 的确切模型字符串是 claude-sonnet-4-5-20250929。

善用思考与交错思考能力

Claude 4 提供了思考 (thinking) 功能，这对于需要在工具使用后进行反思或处理复杂多步推理的任务尤其有帮助。可以引导其进行初始思考或交错思考 (interleaved thinking) ，以获得更好的结果。

在收到工具返回的结果后，请先仔细评估其质量，并确定最佳的下一步行动，然后再继续。利用你的思考能力，根据新信息进行规划和迭代，然后采取最优的下一步操作。

文档创建

Claude Sonnet 4.5 擅长创建演示文稿、动画和可视化文档。在这一领域，它的表现能与 Claude Opus 4.1 相媲美甚至超越，并展现出令人印象深刻的创意才华和更强的指令遵循能力。在大多数情况下，该模型首次尝试就能生成精美且可用的输出。

要在文档创建方面获得最佳效果，可以尝试如下提示：

请就 [主题] 创建一个专业的演示文稿。其中应包含经过深思熟虑的设计元素、清晰的视觉层次，并在适当之处加入引人入胜的动画。

优化并行工具调用

Claude 4 模型擅长并行执行工具，其中 Sonnet 4.5 在同时发起多个操作方面表现得尤为积极。该模型会：

在研究过程中进行多次推测性搜索。
一次性读取多个文件，以更快地建立上下文。
并行执行 bash 命令 (这甚至可能导致系统性能瓶颈) 。

这种行为是完全可控的。虽然模型在没有提示的情况下，并行调用工具的成功率已经很高，但可以通过提示将其成功率提升至接近 100%，或者调整其并行操作的积极程度：

<use_parallel_tool_calls>
如果你打算调用多个工具，并且这些调用之间没有依赖关系，请并行执行所有独立的工具调用。只要操作可以并行完成，就应优先选择同时调用而非顺序调用。例如，当需要读取 3 个文件时，请并行运行 3 个工具调用，将这 3 个文件同时读入上下文。在可能的情况下，最大限度地利用并行工具调用以提升速度和效率。然而，如果某些工具调用依赖于前一个调用的结果来获取参数等信息，则不要并行调用，而应顺序执行。切勿在工具调用中使用占位符或猜测缺失的参数。
</use_parallel_tool_calls>

请按顺序执行操作，每步之间稍作停顿，以确保系统稳定。

减少智能体编码过程中的文件创建

在使用 AI 智能体进行编码时，Claude 4 模型有时会为了测试和迭代而创建新文件。这种方法让 Claude 可以把文件 (尤其是 Python 脚本) 当作“临时草稿纸”，在保存最终输出前进行演练。使用临时文件能够改善编码效果，尤其是在智能体编码场景下。

如果希望尽量减少额外创建新文件，可以指示 Claude 在任务结束后自行清理：

如果在迭代过程中创建了任何临时的文件、脚本或辅助文件，请在任务结束时将它们删除，以完成清理工作。

增强视觉效果与前端代码生成

Claude 4 模型能够生成高质量、视觉效果独特且功能完善的用户界面。然而，若没有明确指导，其生成的前端代码可能偏向于缺乏视觉吸引力的通用样式。要获得出色的用户界面，可以尝试以下方法：

明确鼓励发挥创意：

请不要拘束，尽情发挥。创建一个令人印象深刻的演示，充分展示你的 Web 开发能力。

指定美学方向和设计约束：

请使用深蓝色和青色的调色板，搭配现代无衬线字体 (例如，标题使用 Inter，正文使用系统字体) 和带有微妙阴影的卡片式布局，来创建一个专业的仪表板。请包含精心设计的细节，如悬停状态、过渡效果和微交互。同时，请遵循以下设计原则：层次感、对比度、平衡感和动态感。

鼓励设计多样性与融合美学：

请提供多种设计方案。尝试通过融合不同来源的元素来创造新的美学风格——比如，采用一种配色方案，搭配另一种字体，再结合第三种布局原则。请避免使用通俗的居中布局、简单的渐变色和千篇一律的样式。

明确要求特定功能：

“请包含尽可能多的相关功能与交互。”
“请添加动画和交互元素。”
“请实现一个超越基础功能的、完备的版本。”

避免只为通过测试而进行硬编码

Claude 4 模型有时可能过于关注如何让测试通过，从而牺牲了解决方案的通用性；或者在进行复杂重构时，可能会使用辅助脚本等变通方法，而不是直接使用标准工具。为避免这种情况，确保获得稳健且可推广的解决方案，请使用以下提示：

请使用标准的可用工具，编写一个高质量的通用解决方案。不要为了更高效地完成任务而创建辅助脚本或使用变通方法。请实现一个对所有有效输入都能正确运行的方案，而不仅仅是针对测试用例。不要硬编码 (hard-code) 数值，或创建仅适用于特定测试输入的解决方案。相反，请实现能够从根本上解决问题的通用逻辑。

请专注于理解问题需求，并实现正确的算法。测试的目的是验证正确性，而不是定义解决方案本身。请提供一个遵循最佳实践和软件设计原则的规范实现。

如果任务本身不合理或不可行，或者任何测试用例有误，请直接告知我，而不是试图绕过它们。最终的解决方案应该是稳健、可维护且可扩展的。

最小化智能体编码中的幻觉

Claude 4 模型产生幻觉 (hallucinations) 的倾向较低，能根据代码给出更准确、有理有据的智能回答。为了进一步强化这一优势并最大限度地减少幻觉，可以采用以下提示：

<investigate_before_answering>
绝不要对你未曾打开过的代码进行推测。如果用户提到了某个特定文件，你必须在回答前先阅读该文件。在回答有关代码库的问题之前，请务必调查和阅读相关文件。除非你对正确答案非常有把握，否则在调查之前绝不对代码做出任何断言——请给出有理有据、杜绝幻觉的回答。
</investigate_before_answering>

迁移注意事项

当从 Sonnet 3.7 迁移到 Claude 4 (包括 Sonnet 4.5) 时，请注意以下几点：

具体说明期望的行为: 考虑清楚地描述希望在输出中看到什么样的结果。
在指令中加入修饰语: 添加一些鼓励 Claude 提升输出质量和细节的修饰语，有助于更好地塑造其表现。例如，将“创建一个分析仪表板”改为“创建一个分析仪表板。请包含尽可能多的相关功能与交互。不要局限于基础功能，而是要力求实现一个功能完备的版本。”
明确要求特定功能: 如果需要动画和交互元素等功能，应当在提示中明确提出。