Claude Agent Prompting 最佳实践

这篇笔记是对 Anthropic 官方《Prompting best practices》的一次知识库化整理。原文覆盖范围很大，既包含 Claude Opus 4.7 的模型特性，也包括通用 prompt 原则、工具调用、thinking、agentic system、前端设计与迁移建议。这里我保留了最值得复用的部分，并把内容改写成更适合长期维护的中文 wiki 版本。

如果你主要关心 thinking 配置，建议同时阅读 claude-agent-adaptive-thinking 和 claude-agent-effort。如果你关心实际编码代理的行为风格，这篇内容和 claude-code 也能互相印证。

一句话总结

Claude 新模型更强，但也更“照字面执行”。想要稳定结果，核心不是堆砌玄学提示词，而是把目标、边界、输出格式、工具策略、风险边界和评判标准说清楚。

适用范围

这份最佳实践主要适用于 Claude 最新模型，包括：

Claude Opus 4.7
Claude Opus 4.6
Claude Sonnet 4.6
Claude Haiku 4.5

其中，Opus 4.7 的若干行为和更早模型差异最明显，尤其体现在：

更严格遵守 effort
更按字面理解指令
更克制地调用工具和子代理
更自然但也更直接的写作风格

快速原则

用清楚、直接、可执行的语言描述任务，不要指望模型“自己懂”。
如果你想要“超出基本要求”的结果，要显式写出来。
当顺序、完整性或验收标准重要时，把要求写成步骤或检查项。
给模型上下文、动机和边界，而不是只给一个抽象命令。
当输出格式重要时，用正向描述告诉 Claude 应该输出成什么样，而不是只说“不要怎样”。
当任务涉及多个信息块时，用 XML 标签分段组织提示词。
当你希望 Claude 采取行动时，明确写成“去做”，不要只问“你能不能建议一下”。

Claude Opus 4.7 的关键变化

1. 响应长度更按任务复杂度自适应

Opus 4.7 不再像旧模型那样更容易输出固定风格的长回答。简单问题会更短，开放式分析会更长。

如果你的产品依赖特定篇幅或语气，最好显式约束。例如：

请保持回答简洁、聚焦。省略非必要背景，示例尽量少。

相比“不要啰嗦”这类负向表述，给出你想要的风格示例通常更有效。

2. `effort` 比过去更重要

Opus 4.7 对 effort 的遵守比更早的 Opus 模型更严格，尤其是在 low 和 medium 档位。低 effort 下，它更倾向于“只做你明确要求的部分”，而不是主动做额外探索。

建议经验：

编码和 agent 场景优先从 xhigh 开始试。
大多数对智能度敏感的任务，至少从 high 开始。
成本或延迟敏感的任务再考虑 medium 或 low。
如果复杂问题上出现“想得太浅”，先调高 effort，不要第一反应就去写更多提示词补丁。

如果必须保持低 effort，又希望它在关键场景多想一步，可以补充：

这个任务涉及多步推理。请在回答前认真梳理问题，再给出结论。

3. Adaptive thinking 的触发频率可被提示词影响

如果你发现 Claude thinking 过于频繁，尤其是在 system prompt 很大、很复杂的情况下，可以加一段软约束：

Thinking 会带来额外延迟，只有在它能显著提升答案质量时才应使用，通常是需要多步推理的问题。若拿不准，请直接回答。

调参优先级

对 thinking 频率的调优，优先顺序通常是：先改 effort，再改提示词。

4. 工具调用和子代理都更克制

Opus 4.7 相比 Opus 4.6 更少“下意识调用工具”，也更少默认生成子代理。这通常会减少无意义探索，但在搜索、代码调研、长链路任务里，有时需要你更明确地告诉它什么时候应当使用工具、什么时候应当分派。

例如：

当问题依赖代码库事实时，先读取相关文件再回答。若多个文件互不依赖，请并行读取。

5. 指令理解更字面化

Opus 4.7 更少“替你脑补”。这意味着：

你没有明确要求的，它更可能不会做。
你只在一个地方提到某个要求，它不会总是自动推广到所有地方。
如果你需要统一格式、统一规则、统一适用范围，要明确写出范围。

例如，不要只说“把这个 section 格式化一下”，而要写：

把这个格式规则应用到文档的每一个 section，而不只是第一个。

6. 语气更直接

Opus 4.7 的写作和沟通默认更直接、少寒暄、少 emoji。如果你的产品语气偏温和、偏陪伴式，需要显式写出来：

使用温暖、协作式语气。在回答前先承接用户的提问方式，再进入结论。

7. 前端设计默认审美更强，但也更固定

官方文档特别提到，Opus 4.7 有很强的默认“审美偏好”，例如偏暖白背景、衬线展示字体、陶土/琥珀色点缀。这在 editorial、portfolio、品牌页里可能很好，但在 dashboard、企业软件、开发者工具里可能很违和。

稳定有效的做法有两种：

直接给出具体视觉规范，而不是泛泛地说“别太 AI 味”。
在实现前先让模型提出 3 到 4 个视觉方向，再选一个落地。

例如：

在开始实现前，先基于这个 brief 提出 4 个截然不同的视觉方向。
每个方向按「背景色 hex / 强调色 hex / 字体 / 一句话理由」输出。
等我选定后，再只实现那个方向。

通用提示原则

清楚直接，比委婉更重要

把 Claude 想成一个非常聪明、但刚入职且不了解你内部习惯的新同事。你说得越具体，它做得越稳。

一个很实用的检验标准是：

黄金法则

把你的 prompt 发给一个不了解上下文的人类同事。如果他也会困惑，Claude 大概率也会困惑。

给上下文，而不是只给命令

如果你能解释“为什么这样做很重要”，Claude 往往会做得更贴合。

例如，不要只写：

不要使用省略号。

而可以写：

你的回答会被 TTS 朗读，所以不要使用省略号，否则朗读体验会很差。

Few-shot 示例是最稳定的控制手段之一

如果你在意输出格式、语气、结构或边界条件，3 到 5 个高质量示例通常比一大段抽象要求更有效。

示例的原则：

贴近真实场景
覆盖边界情况
足够多样，避免让模型学到错误模式
用 <examples> / <example> 标签和正文指令隔离开

用 XML 标签组织复杂提示词

当提示词同时包含指令、背景、变量输入、文档、多组示例时，XML 风格标签非常有用。它的价值不是“高级”，而是降低歧义。

常见组织方式：

<instructions>...</instructions>
<context>...</context>
<documents>
  <document index="1">...</document>
  <document index="2">...</document>
</documents>
<input>...</input>

给 Claude 一个角色

角色提示很短，但通常很有效。尤其当你需要固定语气、专业视角或评判标准时，更推荐放在 system prompt。

import Anthropic from "@anthropic-ai/sdk"
 
const client = new Anthropic()
 
const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  system: "你是一名擅长 TypeScript 和代码审查的工程师，回答要准确、直接、可执行。",
  messages: [
    {
      role: "user",
      content: "如何按某个键对对象数组排序？",
    },
  ],
})
 
console.log(message.content)

长上下文提示技巧

当输入很长，尤其是 20k+ token 的文档、多文档检索、数据分析任务时，提示词结构会明显影响效果。

1. 长文档放前面，问题放后面

官方经验是：大块文档内容尽量放在前面，真正的问题和指令放在后面。复杂多文档场景里，这样做能显著提升表现。

2. 文档和元数据一起结构化

推荐模式：

<documents>
  <document index="1">
    <source>annual_report_2025.pdf</source>
    <document_content>{{ANNUAL_REPORT}}</document_content>
  </document>
  <document index="2">
    <source>competitor_analysis_q2.xlsx</source>
    <document_content>{{COMPETITOR_ANALYSIS}}</document_content>
  </document>
</documents>
 
请基于这些材料分析重点结论，并给出下一季度建议。

3. 先抽引文，再做判断

在长文档任务里，要求 Claude 先提取相关原文，再继续分析，会让结果更稳、更可核查。

例如：

先从文档里提取与问题最相关的原文片段，放进 <quotes> 标签中。
然后仅基于这些引文，在 <analysis> 标签中完成你的判断。

4. 让模型正确“认识自己”

如果你的应用里需要 Claude 正确说明自己的身份或模型名，可以在系统提示里显式给出：

当前助手是 Claude，由 Anthropic 创建。当前模型为 Claude Opus 4.7。

如果你的应用会让模型自己引用 API model string，也可以直接写明：

默认应使用 Claude Opus 4.7；对应的模型字符串是 claude-opus-4-7。

输出控制与格式约束

正向规定输出格式，比负向禁止更有效

与其说“不要用 markdown”，不如直接说：

请用自然流畅的完整段落作答，避免列表化表达。

如果你对格式要求更强，可以写得更具体：

写报告、分析或技术说明时，优先使用完整段落和自然过渡。Markdown 仅用于简短标题、行内代码和代码块。除非用户明确要求，否则避免项目符号和编号列表。

Prompt 的格式风格会影响输出风格

如果你的提示词本身充满列表、标题和 markdown，Claude 也更容易输出成同样风格。你想得到“自然 prose”，提示词自己也可以更接近 prose。

数学表达与 LaTeX

较新的 Claude 模型更倾向输出 LaTeX。若你的产品不需要数学公式语法，最好显式关掉：

仅使用纯文本表达数学内容。不要使用 LaTeX、MathJax、$...$、\(...\) 或 \frac{}{} 这类公式标记。

文档、演示稿、视觉内容生成

官方文档指出，Claude 在生成 presentation、animation、可视化文档这类产物时表现很好，但若你想得到真正可用的产物，仍然应把设计目标写明确：

请围绕这个主题创建一份专业演示稿，包含清晰的视觉层级、适度动画和一致的版式风格。

从 prefill 迁移出去

从 Claude 4.6 和 Mythos Preview 开始，最后一轮 assistant prefill 不再是推荐做法；在 Mythos Preview 上甚至会直接报错。

常见迁移方式：

想约束输出结构：优先用 Structured Outputs、tool schema，或直接要求符合某个固定结构。
想去掉开场白：直接在 system prompt 里写“直接回答，不要前言”。
想避免不必要拒答：明确写清任务上下文，通常已不需要 prefill 绕过。
想续写中断回答：把上次中断的文本放进用户消息，让模型“从这里继续”。
想做上下文注水：把原本 prefill 的提醒信息迁移到 user turn、tool 或 context compaction 流程。

工具调用最佳实践

想让 Claude 真动手，就直接说“做”

很多“模型只给建议不执行”的问题，本质上是提示词模糊。

例如，不要说：

你能建议一下这个函数怎么优化吗？

而要说：

请直接修改这个函数，提高它的性能。

如果你想把“默认行动”写进系统提示，也可以加：

默认优先执行变更，而不是只给建议。如果用户意图略有模糊，先通过读取文件、查看上下文来补齐信息，再继续执行，而不是停留在空泛建议层面。

反过来，如果你的产品更保守，可以写成：

除非用户明确要求，否则不要直接改文件或实施变更。遇到模糊需求时，优先给信息、研究结论和建议。

并行工具调用是重要加速器

Claude 新模型很擅长并行读文件、并行检索、并行跑独立命令。如果你的工具环境允许，值得在提示词里明确鼓励。

例如：

如果多个工具调用互不依赖，请并行发起。只有当后一步依赖前一步结果时，才串行执行。不要猜测缺失参数，也不要用占位符调用工具。

如果你更想保守一点，也可以写成：

请按顺序逐步执行操作，在每一步之间短暂停顿，以保证稳定性。

Thinking 与推理策略

1. 过度 thoroughness 可能是个问题

官方特别提醒，Opus 4.6 及后续模型会比早期模型做更多前置探索。这通常有好处，但也可能导致：

查太多上下文
开太多研究分支
thinking token 暴涨
响应延迟明显增加

如果你遇到这种情况：

删除过去为了“防偷懒”而加入的激进提示词
把“默认用某工具”改成“在有帮助时使用某工具”
必要时降低 effort

例如：

当你决定方案时，选择一个方向并持续推进。除非出现直接推翻当前判断的新信息，否则不要反复重开路线。

2. 优先使用 adaptive thinking

对支持新 thinking 的模型，优先使用 claude-agent-adaptive-thinking 中的 adaptive 模式，而不是旧的 budget_tokens。

适合 adaptive thinking 的典型场景：

多步工具调用
复杂编码任务
长链路 agent loop
难度差异很大的混合任务流

如果你需要提示 Claude 在工具调用后认真反思下一步，可以加：

在收到工具结果后，先评估这些结果的质量和局限，再决定下一步最合适的动作。必要时利用 thinking 做计划和迭代，然后再继续执行。

3. 通常不要把 reasoning 过程写得太死

官方建议是：与其手写很死板的 step-by-step 推理流程，不如给更一般性的高层要求，例如“认真思考”“先自检再提交”。Claude 经常能自己组织出比人类手写模板更好的推理路径。

有用的附加句式包括：

“在结束前，按这些验收标准自查一遍。”
“如果你发现结论和证据不一致，优先修正结论。”
“如果结果依赖代码事实，先读文件再下结论。”

Agentic System 设计建议

长链路任务要强调状态管理

Claude 新模型在长任务里擅长“逐步推进”，但你仍然需要通过 prompt 和工作流设计帮它保持状态。

推荐做法：

让它把测试状态、任务状态写入结构化文件，例如 tests.json
把进度、假设、下一步写入自由文本，例如 progress.txt
使用 git 作为阶段性状态记录
鼓励它优先做可验证的小步前进，而不是一下子铺太大

例如，可让它维护这样的状态文件：

{
  "tests": [
    { "id": 1, "name": "authentication_flow", "status": "passing" },
    { "id": 2, "name": "user_management", "status": "failing" }
  ],
  "next": "investigate user_management failures"
}

多 context window 任务要提前设计

如果你的 agent 系统会自动 compact context，或允许把状态存到文件、memory、工具里，那么最好在提示词里提前告诉 Claude：

当上下文接近上限时，请在窗口刷新前把当前进度、未完成事项和关键状态写入持久化位置。不要因为接近 token 上限而提前放弃任务。

对于跨多个上下文窗口的任务，官方建议：

第一窗口先搭框架，例如写测试、脚手架、初始化脚本
后续窗口围绕 todo list 迭代
提供便于恢复现场的验证工具
某些情况下，重新从文件系统“冷启动发现状态”比依赖 compaction 更好

自主性与安全性要同时写清楚

没有约束时，Claude 可能会做一些难以回滚的动作，例如删文件、强推 git、改共享系统。对于这类高风险动作，最好明确要求先确认。

可以直接放进系统提示：

请评估每个动作的可逆性和影响范围。编辑文件、运行测试这类本地可回滚操作可以直接执行；但凡涉及删除、强制推送、修改共享系统、对外发送信息或其他难以撤销的动作，先征求确认。

研究型任务适合显式要求“假设树”和“证据校验”

对复杂调研任务，Claude 很适合用“多假设并行 + 持续校准”的方式推进。

例如：

请结构化地搜索信息。随着调研推进，维护几个相互竞争的假设，并记录各自置信度。定期自我质疑当前方法，并把研究结论持续写入研究笔记。

子代理的适用条件也要写出来

Claude 对 subagent 的使用已经很强，但也可能过度分派。比较稳的规则是：

可并行、上下文隔离、互相独立的工作流，适合子代理
单文件修改、顺序依赖强、上下文连续性强的任务，更适合主代理直接做

可以写成：

当任务之间可以并行、需要隔离上下文、或属于互不依赖的独立工作流时，使用子代理。对于简单任务、单文件改动、强顺序依赖任务，直接处理，不要为了分派而分派。

避免过度工程化、测试导向作弊和幻觉

Claude 在 agentic coding 里常见的几个坏倾向是：

新建太多临时文件
为了“可扩展”而过度抽象
为了过测试而硬编码
没读文件就对代码做判断

这些都可以用 prompt 明确压住：

避免过度工程化。只实现被明确要求或确实必要的改动，不要额外加抽象、配置项、helper、脚本或未来需求预留。

请实现一个高质量、通用、可维护的真实解法，不要为通过测试而硬编码，也不要用临时脚本或变通方式绕过问题。

不要对未打开过的代码做推断。如果用户提到某个文件，必须先读取该文件再回答。所有关于代码的判断都应建立在实际调查基础上。

能力专项建议

Vision

Opus 4.5 / 4.6 的视觉理解比早期模型更强，尤其适合多图场景、截图理解、UI 测试与视频抽帧分析。官方特别提到，给模型一个裁剪工具或等价 skill，通常能进一步提升视觉任务效果，因为它可以“放大观察重点区域”。

Frontend

Claude 在前端生成上已经很强，但如果没有设计约束，仍然容易滑向“AI 味很重”的通用模板。官方给出的方向和仓库里的 frontend-design skill 思路高度一致：不要默认字体、不要紫色渐变套版、不要千篇一律组件组合，要显式要求风格独特、字体有性格、配色有主张、动效有重点。

可直接复用这样的约束片段：

<frontend_aesthetics>
避免落入通用 AI 生成网页的审美：不要使用过度常见的字体、陈词滥调的配色和模板化布局。请选择更有辨识度的字体与主题，用更完整的视觉系统和少量高质量动效来建立页面个性。
</frontend_aesthetics>

迁移建议

从旧模型迁移到 4.6/4.7 时，重点看这几项

明确写出你真正想要的行为，不要依赖旧模型时代的“模糊暗示”。
如果过去为了防偷懒、防少调用工具而加了很多激进提示词，迁移时要适当减弱。
把手工 budget_tokens thinking 迁移到 adaptive + effort。
最后一轮 assistant prefill 逐步迁移掉。
对输出风格、语气、进度更新方式、工具触发方式重新做评测，不要假设旧 prompt 在新模型上会“自动等价”。

Sonnet 4.5 迁移到 Sonnet 4.6 的重点

Sonnet 4.6 默认 effort 是 high，这会让它比 Sonnet 4.5 更可能增加延迟和 token 消耗。因此迁移时最好显式设置 effort。

经验建议：

大多数应用先从 medium 开始
高吞吐、低延迟场景先从 low 开始
复杂 agent / coding 任务再考虑 high

如果你原来使用的是 extended thinking with budget_tokens，官方建议尽量迁移到 adaptive thinking：

import Anthropic from "@anthropic-ai/sdk"
 
const client = new Anthropic()
 
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 64000,
  thinking: {
    type: "adaptive",
  },
  output_config: {
    effort: "high",
  },
  messages: [
    {
      role: "user",
      content: "继续完成这个多步编码任务，并在必要时调用工具。",
    },
  ],
})
 
console.log(response.content)

迁移中的一个常见误区

如果新模型表现“没那么主动”或“想得不够深”，不要立刻堆更多 prompt。先检查是不是 effort 过低、thinking 模式没切到 adaptive、或旧提示词里有互相冲突的约束。

最佳实践清单

明确写出目标、边界、完成标准和输出格式。
需要行动时直接要求“执行”，不要只写“建议”。
复杂 prompt 用 XML 标签分块组织。
需要稳定格式时，多用 few-shot 示例，少靠抽象描述。
对新模型优先使用 adaptive + effort，并在真实任务上评测。
希望 Claude 少想一点，先降 effort；希望它多想一点，先升 effort。
长任务要设计状态文件、验证工具和跨窗口恢复策略。
高风险动作必须要求先确认。
明确限制过度工程化、硬编码和未读文件先下结论。
迁移新模型时，把旧 prompt 当成“待重新评测资产”，不要当成永远正确的真理。

wwsun

探索

Claude Agent Prompting 最佳实践

适用范围

快速原则

Claude Opus 4.7 的关键变化

1. 响应长度更按任务复杂度自适应

2. effort 比过去更重要

3. Adaptive thinking 的触发频率可被提示词影响

4. 工具调用和子代理都更克制

5. 指令理解更字面化

6. 语气更直接

7. 前端设计默认审美更强，但也更固定

通用提示原则

清楚直接，比委婉更重要

给上下文，而不是只给命令

Few-shot 示例是最稳定的控制手段之一

用 XML 标签组织复杂提示词

给 Claude 一个角色

长上下文提示技巧

1. 长文档放前面，问题放后面

2. 文档和元数据一起结构化

3. 先抽引文，再做判断

4. 让模型正确“认识自己”

输出控制与格式约束

正向规定输出格式，比负向禁止更有效

Prompt 的格式风格会影响输出风格

数学表达与 LaTeX

文档、演示稿、视觉内容生成

从 prefill 迁移出去

工具调用最佳实践

想让 Claude 真动手，就直接说“做”

并行工具调用是重要加速器

Thinking 与推理策略

1. 过度 thoroughness 可能是个问题

2. 优先使用 adaptive thinking

3. 通常不要把 reasoning 过程写得太死

Agentic System 设计建议

长链路任务要强调状态管理

多 context window 任务要提前设计

自主性与安全性要同时写清楚

研究型任务适合显式要求“假设树”和“证据校验”

子代理的适用条件也要写出来

避免过度工程化、测试导向作弊和幻觉

能力专项建议

Vision

Frontend

迁移建议

从旧模型迁移到 4.6/4.7 时，重点看这几项

Sonnet 4.5 迁移到 Sonnet 4.6 的重点

最佳实践清单

关系图谱

目录

最近更新

Chain-of-Thought 思维链

Direct Preference Optimization, 直接偏好优化

Mixture of Experts，混合专家模型

Pre-training

RLHF 基于人类反馈的强化学习

2. `effort` 比过去更重要