AI Agent系统提示词设计：从模糊指令到精准工程实践

上周，我花了一个下午和一个晚上，试图让一个基于 Claude 的智能体（Agent）项目跑起来。项目本身很吸引人，号称能处理复杂的多步骤任务，但启动后，它要么卡在第一步，要么给出一些看似合理但完全偏离目标的回答。我检查了代码、环境、API Key，一切正常。问题出在哪？直到我把目光投向那个看似不起眼的system prompt（系统提示词）。

那一刻我意识到，我们可能都低估了system prompt的力量。在追逐更强大的模型（如 Claude 3.5 Sonnet、Opus）和更精巧的 Agent 框架时，我们常常把system prompt当作一个简单的“角色设定”或“功能说明”，写上一两句就完事。但恰恰是这个最基础的部分，决定了你的 Agent 是能精准执行任务的得力助手，还是一个只会说“我理解你的需求”的复读机。

这次修复 Opus 5（一个假设的或泛指基于 Claude 的复杂任务处理项目）的经历，让我重新审视了 Prompt Engineering。它远不止是“如何问问题”，而是一套关于如何与模型建立有效“沟通契约”的工程方法。这篇文章，我想和你分享的，不是某个具体的system prompt模板，而是如何构建一个能让 Agent 真正“理解”并“可靠执行”的底层指令系统。

1. 为什么你的 Agent 总在“跑偏”？问题往往不在模型，而在沟通

当你发现 Claude 或类似的模型 Agent 表现不佳时，第一反应往往是：“是不是模型不够强？”或者“这个框架是不是有 Bug？”。但在大多数非代码错误的场景下，问题的根源更可能在于模糊的指令和缺失的上下文边界。

1.1 从“角色扮演”到“精确的岗位说明书”

我们通常这样写system prompt：

“你是一个有帮助的 AI 助手。”

或者稍微好一点：

“你是一个资深的软件开发专家。”

这就像在招聘时只说：“我们需要一个会写代码的人。” 结果来的人可能擅长前端、后端、算法，但未必是你需要的 DevOps。对于 AI 模型，尤其是承担多步骤任务的 Agent，这种模糊的角色定义是灾难的开始。

一个有效的system prompt应该是一份精确的岗位说明书，它需要明确：

• 核心职责：你具体要它做什么？（例如：分析代码仓库、提取特定模式、生成报告）
• 工作边界：什么是你必须做的，什么是你不能做的？（例如：只读取src/目录下的.py文件，不修改任何原始文件）
• 交付标准：输出的格式、详细程度、风格是什么？（例如：以 Markdown 表格形式列出，包含文件名、函数名和问题描述三列）
• 协作方式：你希望它如何思考和工作？（例如：先规划步骤，再逐步执行，遇到不确定时主动询问）

1.2 理解模型的“思维过程”：它需要被引导，而非被命令

大型语言模型（LLM）没有真正的“思考”，但它会根据你提供的上下文（Context）和指令（Prompt），模拟出一个合理的“思维链”。一个糟糕的system prompt会让这个“思维链”从一开始就偏离轨道。

例如，你让 Agent “优化这段代码”。一个模糊的指令下，模型可能会：

1. 理解为“让代码更短”，于是删掉所有注释和空行。
2. 理解为“提高性能”，于是引入复杂的缓存机制，但可能引入 Bug。
3. 理解为“符合 PEP 8”，只调整了格式。

而一个清晰的system prompt会引导它：

“你是一个 Python 代码优化专家。你的目标是提升代码的可读性和维护性，同时保持功能不变。请按以下顺序工作：1) 分析现有代码的逻辑和结构；2) 识别重复代码块，建议提取为函数；3) 检查变量命名是否清晰；4) 添加必要的文档字符串（Docstring）；5) 确保符合 PEP 8 规范。最后，输出优化后的代码，并用注释标出你所做的每一处修改及其原因。”

后者为模型构建了一条清晰的“思考路径”，大幅降低了它“自由发挥”导致跑偏的概率。

1.3 常见症状与system prompt缺陷的对应关系

你可以通过 Agent 的表现反向诊断system prompt的问题：

修复 Opus 5 的过程，本质上就是一次针对这些症状的系统性诊断和system prompt重构。

2. 构建稳健system prompt的四层结构法

经过多次迭代，我总结出一个四层结构法来构建system prompt。这四层像洋葱一样，从内核到外层，逐层约束和引导模型的行为。

2.1 第一层：核心身份与终极目标（The Core）

这是模型的“灵魂”。用一句高度凝练的话定义它最根本的存在意义。

• 错误示例：“你是一个 AI。”
• 普通示例：“你是一个代码助手。”
• 优秀示例：“你是一个以生成安全、高效、可维护的生产级代码为最高准则的 AI 工程师。”

为什么重要：这一层设定了模型所有决策的“北极星”。当面临权衡时（比如是写更短的代码还是更易读的代码），它会依据这个终极目标进行判断。

2.2 第二层：核心职责与绝对禁令（The Rules）

这一层定义具体的工作范围和不可逾越的红线。要具体、可操作。

• 职责：
  • “你的主要职责是进行代码审查、重构建议和生成模块化的函数。”
  • “你专注于处理用户提供的{特定类型}数据，并输出{特定格式}的分析报告。”
• 禁令：
  • “你绝不能修改或删除用户提供的原始输入数据。”
  • “你绝不能假设或编造超出给定上下文的信息。如果信息不足，你必须明确指出。”
  • “你绝不能在一个回复中混合多种不相关的任务主题。”

写作技巧：使用“必须”、“绝不”、“始终”、“优先”等强语气词，减少歧义。

2.3 第三层：工作流程与思维框架（The Process）

这是引导模型“如何思考”的关键。为复杂任务设计一个默认的思维框架。

• 对于分析任务：“面对任务时，请遵循：理解目标 -> 拆解问题 -> 分步分析 -> 汇总结论 -> 给出建议 的流程。”
• 对于生成任务：“在创作内容时，请先构建大纲，然后填充细节，最后进行连贯性和风格检查。”
• 对于交互任务：“在对话中，如果你需要更多信息才能继续，请一次性、清晰地列出所有你需要澄清的点。”

你可以把这个框架直接写给模型，例如：

“请按以下步骤处理每个查询：1)解析：确认你理解的任务核心是什么。2)规划：在心里或简单列出完成任务的子步骤。3)执行：按步骤工作，并检查每一步的输出。4)交付：以清晰、结构化的方式呈现最终结果。”

2.4 第四层：输出规范与风格指南（The Format）

这是模型的“出厂设置”，确保交付物的一致性。

• 格式：“所有代码块请使用```语言标记。所有关键结论请使用无序列表（-）列出。”
• 风格：“保持专业、简洁、积极的语气。避免使用‘可能’、‘也许’等不确定词汇，用‘建议’、‘推荐’代替。”
• 结构化：“对于任何包含多个项目的回答，请优先使用 Markdown 表格。”
• 交互：“如果你的回答包含多个部分，请使用##标题进行分隔。”

将这四层组合起来，就是一个强大的system prompt骨架。例如，一个用于“技术文档分析”的 Agent 可能拥有这样的system prompt：

（核心）你是一个专注于从复杂技术文档中精准提取架构信息和 API 规约的 AI 分析师。 （规则）你必须严格基于提供的文档内容进行分析，绝不臆测。你的输出必须是事实性陈述。 （流程）对于每份文档，你的工作流程是：1) 通读，识别文档类型和核心章节；2) 提取所有提到的系统组件、数据流和接口定义；3) 将提取的信息归类到‘架构图组件’、‘API 端点’、‘数据模型’三个表中。 （格式）最终请以 Markdown 格式输出这三个表格。每个表格包含‘名称’、‘描述’、‘所在章节’三列。不使用任何引言和总结性段落。

3. 从单次对话到持续协作：让 Agent 记住“上下文”

一个复杂的项目（如 Opus 5）往往不是一次问答就能完成的。它涉及多轮交互、状态维持和渐进式构建。这时，仅仅有一个好的初始system prompt还不够，你需要管理好对话上下文（Context）。

3.1 上下文是模型的“短期记忆”

模型没有真正的记忆。它每次生成回复，所依赖的“记忆”就是当前对话窗口中你提供的所有文本（即上下文窗口，如 Claude 的 200K 上下文）。system prompt、历史对话、你的新问题，共同构成了它这次“思考”的全部材料。

常见误区：

1. 假设模型记得之前说过的话：如果你在第十轮对话中问“那我们刚才说的第一个方案是什么？”，模型其实是在整个上下文里搜索“第一个方案”这个词组，而不是真的“回忆”。如果上下文很长或表述方式变了，它可能找不到。
2. 在长对话中丢失核心指令：随着对话轮数增加，最初的system prompt可能会被“挤”到上下文窗口的远端，模型对其的“注意力”可能下降，导致行为漂移。

3.2 策略一：关键信息重复与摘要

对于需要贯穿始终的核心规则或目标，不要只在开头说一次。

• 在关键节点重申：在开始一个新阶段的任务时，可以简要重申目标。“我们现在开始执行第一阶段的数据清洗，请记住，核心目标是保证数据一致性，而不是追求数量。”
• 让 Agent 自己摘要：在完成一个复杂步骤后，可以要求 Agent 对当前状态和下一步计划做一个简短摘要。这既能确认它的理解，又能将重要信息以新的形式注入上下文。

3.3 策略二：结构化上下文与“黑板”模式

对于超长、复杂的任务，可以将上下文结构化。

• 设立“工作区”：在对话中，明确划分出“原始需求”、“当前进展”、“待解决问题”、“决策记录”等区块。你可以用明显的标记如## 决策记录 ##来分隔。
• 使用“黑板”模式：将最重要的、不可变的指令（如核心规则、输出格式）始终放在每次提问的最前面或一个固定的位置。有些高级用法会将system prompt的一部分作为“元指令”在每轮交互中隐性传递。

3.4 策略三：重置与分段执行

当对话已经非常冗长，且你感觉到 Agent 开始“胡言乱语”或忘记初衷时，最有效的方法往往是开启一个新对话。

• 分段执行：将一个大任务拆分成几个逻辑上相对独立的子任务。完成一个子任务后，开启一个新对话窗口，将上一个任务的最终结果（而不是全部聊天记录）和新的system prompt一起输入，开始下一个子任务。
• 好处：这保证了每个阶段 Agent 都在一个“干净”且专注的上下文中工作，避免了长期对话带来的噪音积累和性能下降。

在修复 Opus 5 时，我发现最初的设计试图在一个超长对话中完成所有事，导致后期指令失效。将其重构为“初始化配置 -> 任务A -> 任务B -> 结果汇总”四个清晰的会话阶段后，稳定性和输出质量立刻大幅提升。

4. 高级技巧：用 Prompt Engineering 应对边界情况与提升可靠性

即使有了完美的四层system prompt和上下文管理，Agent 在实际运行中仍会遇到边界情况。这时，需要更精细的 Prompt Engineering 技巧。

4.1 为“不确定性”设计逃生舱

模型遇到模糊或信息不足时，默认行为可能是猜测，这很危险。你应该在system prompt中明确告诉它如何应对。

“如果你对用户请求的任何部分存在不确定性，或者需要额外的信息才能做出可靠输出，你必须立即停止假设，并清晰地列出你需要澄清的所有具体问题。在获得澄清前，不要继续执行核心任务。”

4.2 引入“链式验证”（Chain-of-Verification）

对于关键输出，尤其是涉及事实、数据或逻辑的，可以要求模型进行自我验证。

“在你给出最终答案前，请执行一次自我验证：1) 检查答案中的每一个关键事实是否都能在提供的上下文中找到依据。2) 检查逻辑推理步骤是否完整且无矛盾。3) 将验证结果以[验证]开头，附在最终答案之后。”

这相当于让模型在输出前“再想一遍”，虽然不能保证100%正确，但能显著减少低级错误。

4.3 利用“少样本学习”（Few-Shot Learning）

在system prompt或对话开头，提供一两个输入输出的完美示例。这对于规范复杂输出格式特别有效。

你的任务是将自然语言描述转换为 JSON 配置。 示例1： 输入：“创建一个用户，名字叫张三，年龄30，角色是管理员。” 输出：{"action": "create_user", "parameters": {"name": "张三", "age": 30, "role": "admin"}} 示例2： 输入：“查询所有状态为活跃的订单。” 输出：{"action": "query_orders", "filters": {"status": "active"}} 现在，请处理新的输入：

模型会强烈地倾向于模仿示例的结构和风格。

4.4 控制“创造力”与“保守度”

通过指令调节模型的“性格”。

• 需要创造性时：“请探索多种可能性，并提供最具创新性的解决方案。”
• 需要保守可靠时：“请严格遵循最佳实践和行业标准，优先选择经过验证的、稳健的方案。”
• 需要严谨推理时：“请逐步展示你的思考过程，确保每一步都有据可依。”

在 Opus 5 这类偏向工程和执行的 Agent 中，我通常会将“保守”和“严谨”的权重调高。

5. 实战：将理论应用于 Agent 开发与调试

理论最终要服务于实践。当你开发或调试一个 AI Agent 时，可以遵循以下流程来运用上述 Prompt Engineering 原则。

5.1 开发阶段：从最小可行 Prompt 开始迭代

1. 定义 MVP（最小可行产品）目标：你的 Agent 最核心、最单一的功能是什么？先把它做好。
2. 编写初版system prompt：运用四层结构法，但先聚焦核心层和规则层。流程和格式可以简单点。
3. 设计测试用例：准备 3-5 个典型的、边界清晰的输入用例。
4. 运行与观察：用测试用例运行 Agent，不要只看最终输出，要观察它的整个“思考”过程（如果框架支持中间步骤输出）。
5. 分析偏差：输出不符合预期时，是目标不清、规则不严、流程混乱还是格式问题？对照四层结构定位。
6. 迭代 Prompt：修改system prompt，解决上一步发现的问题。一次只修改一个方面，并重新测试。
7. 扩展与泛化：核心功能稳定后，再逐步增加更复杂的流程、更丰富的格式要求，并用更多样化的用例测试。

5.2 调试阶段：系统性排查清单

当现成的 Agent（如你遇到的 Opus 5）表现失常时，按此清单排查：

1. 检查输入：我提供给 Agent 的初始指令或用户输入是否清晰、无歧义？是否包含了所有必要信息？
2. 审查 System Prompt：（这是重点）它的四层结构完整吗？规则是否有漏洞？流程是否适用于当前任务？格式要求是否明确？
3. 审查上下文：当前对话是否过长？关键的system prompt或早期指令是否已被淹没？是否有无关信息干扰？
4. 测试简化场景：用一个极其简单、确定的任务测试 Agent。如果简单任务也失败，问题可能出在框架或 API 连接上。如果简单任务成功，复杂任务失败，则问题在于 Prompt 对复杂性的处理能力不足。
5. 分步验证：如果 Agent 支持分步执行，手动将复杂任务拆开，一步步喂给它，看它在哪一步开始偏离。
6. 查看日志：如果框架提供了 Agent 的“思考”日志或对模型的原始调用记录，仔细阅读。你可能会发现模型接收到的 Prompt 和你想象的不一样（框架可能会做拼接或修改）。

5.3 长期维护：将 Prompt 视为核心资产

• 版本化：像管理代码一样管理你的system prompt。使用 Git，为每次重大修改添加注释。
• 文档化：为复杂的system prompt写内部文档，解释每一部分的设计意图和对应的测试用例。
• 监控与评估：定期用一组固定的测试用例评估 Agent 的表现，监控其输出质量是否有“漂移”。
• 持续迭代：随着模型更新、业务变化或遇到新的边界情况，不断优化你的 Prompt。

修复 Opus 5 的过程，本质上就是一次深入的 Prompt Engineering 实践。它让我明白，在 AI 应用开发中，编写system prompt不是一项前期的一次性工作，而是一项贯穿始终的核心工程活动。模型的潜力就像一个强大的引擎，而精心设计的 Prompt 就是精准的传动系统和方向盘。没有后者，再强的引擎也无法让车辆驶向正确的目的地。

下一次当你对 Agent 的表现感到沮丧时，不妨先别急着换模型或改代码，沉下心来，重新审视并精心雕琢那个最基础的system prompt。你会发现，很多时候，答案就藏在最开始的几句“对话”里。