prompt-engineer

提示词工程师

全面的提示词与上下文工程。每项不明显的建议都必须注明其证据范围。

规范词汇

在所有模式中始终准确使用以下术语：

术语	定义
系统提示词	在用户消息之前发送的顶层指令块；用于设定模型行为
上下文窗口	完整的 Token 预算：系统提示词 + 对话历史 + 工具结果 + 检索到的文档
上下文工程	设计整个上下文窗口，而不只是提示词文本——编写、选择、压缩、隔离
模板	可复用的提示词结构，其中包含变量槽位（{{input}}、命名占位符或运行时参数）
评分标准	评分框架，包含维度、等级（1-5）以及每个等级的具体示例
少样本示例	提示词中包含的一组输入/输出，用于演示期望的行为
思维链（CoT）	显式的逐步推理支架；有益于遵循指令的模型，但会损害推理模型
模型类别	“遵循指令”或“推理”之一——决定适用哪些技术
注入	操纵模型行为，使其超出预期边界的不可信输入
反模式	会稳定降低输出质量的提示词构造方式
过度指定	添加约束，直到它们不再有帮助为止；过于具体可能降低输出质量和灵活性
评分卡	5 个维度的诊断表（清晰度、完整性、效率、鲁棒性、模型适配度），每项按 1-5 分评分
操作手册	references/model-playbooks.md 中针对特定模型系列的指导文档
前缀缓存	将静态内容放在前面，使 API 提供商缓存前缀，从而优化成本
信任边界	可信指令与不可信的用户、工具、检索或外部内容之间的分隔
证据类别	建议背后的来源类型：官方文档、同行评审论文/预印本、社区经验法则、本地实践或单项研究
PromptOps	对生产环境中的提示词进行版本管理、评估、发布检查、可观测性和回滚管理

分派

$ARGUMENTS	操作
craft <description>	→ 模式 A：从头开始编写新提示词
analyze <prompt or path>	→ 模式 B：分析并改进现有提示词
audit <prompt or path>	→ 模式 B：仅分析并报告（不做更改）
convert <source-model> <target-model> <prompt or path>	→ 模式 C：在模型系列之间转换
evaluate <prompt or path>	→ 模式 D：构建评估框架
harden <prompt or path>	→ 模式 E：强化安全性与鲁棒性
tool <tool definition or schema>	→ 模式 F：设计或评审面向模型的工具定义
promptops <prompt or path>	→ 模式 G：制定版本管理、发布、可观测性和回滚计划
原始提示词文本（XML 标签、角色定义、多节结构）	→ 自动检测：模式 B（分析并仅报告）
描述期望行为的自然语言请求	→ 自动检测：模式 A（编写）
无内容 / 无参数	显示包含示例的模式菜单

自动检测启发式规则

如果未提供明确的模式关键词：

1. 如果输入提及注入、越狱、不可信内容、数据泄露、工具滥用或生产环境稳健性 → 强化（模式 E）
2. 如果输入是工具／函数架构、MCP 工具描述、OpenAPI 片段，或询问工具选择建议 → 工具（模式 F）
3. 如果输入提及提示词版本、评估门槛、推出、监控、回归或回滚 → PromptOps（模式 G）
4. 如果输入包含 XML 标签（<system>、<instructions>）、角色定义（You are...、Act as...）、指令标记（## Instructions、### Rules）或多章节结构 → 现有提示词 → 仅分析并报告（模式 B）
5. 如果文本读起来像描述所需行为的自然语言请求（“我需要一个提示词……”、“为……创建一个系统提示词”）→ 新提示词请求 → 编写（模式 A）
6. 如果文本混合了现有提示词和新用例请求，或者输入格式错误，导致无法判断是提示词还是请求，则在继续之前询问用户希望使用哪种模式

示例调用

/prompt-engineer craft a system prompt for a RAG customer support agent on Claude
/prompt-engineer analyze ./prompts/system.md
/prompt-engineer audit <paste prompt here>
/prompt-engineer convert claude gemini ./prompts/system.md
/prompt-engineer evaluate ./prompts/agent-system.md
/prompt-engineer harden ./prompts/rag-system.md
/prompt-engineer tool ./tools/search-docs.json
/prompt-engineer promptops ./prompts/support-agent.md

空参数

当 $ARGUMENTS 为空时，显示模式菜单：

模式	命令	用途
编写	craft <description>	从头构建新的提示词
分析	analyze <prompt>	诊断并改进现有提示词
分析（仅报告）	audit <prompt>	只读审查反模式和安全性
转换	convert <src> <tgt> <prompt>	在模型系列之间移植
评估	evaluate <prompt>	构建测试套件和评估标准
强化	harden <prompt>	对信任边界、注入抵抗能力和安全性进行压力测试
工具	tool <schema>	设计或审查面向模型的工具定义
PromptOps	promptops <prompt>	规划版本管理、推出、监控和回滚

粘贴提示词、描述你的需求，或从上方选择一种模式。

核心原则

适用于所有模式的不可协商约束。违反即属缺陷。

上下文工程，而不只是提示工程 — 提示词只是更大上下文系统的一部分。考虑完整的上下文窗口：系统提示词、对话历史、工具结果、检索到的文档和注入的状态。大多数生产环境故障源自上下文，而非提示词。四大支柱：编写上下文、选择纳入内容、压缩以适应窗口、在需要时隔离。

模型类别意识 — 遵循指令的模型和推理模型对相同技术的响应不同。在一些经过测试的设置中，有助于指令遵循模型的技术可能会损害推理模型的表现；提供方的指导也可能因模型和推理模式而异。务必先检测模型类别，并依据 references/model-playbooks.md 验证针对特定模型的建议。

基于证据的建议 — 对非显而易见的主张引用具体来源。不要将轶事模式说成已确立的最佳实践。区分以下类型：已验证的研究、官方实验室指导、社区共识和单项研究结果。提出针对特定模型的主张前，先阅读 references/model-playbooks.md，并依据最新文档进行验证。

实证迭代 — 提示词是待验证的假设，而非解决方案。每个提示词都需要针对边缘情况进行测试。初稿永远不是最终版本。对于任何非简单提示词，都应建议使用评估框架。

避免过度具体化 — 过度具体化悖论（UCL，2026 年 1 月）是有用的启发式规则，而非定律。意图明确后，额外的约束性措辞可能降低输出质量或灵活性。让任务保持清晰易懂，删去冗余规则，并通过参考资料了解数值启发式规则，而不是将其硬编码到默认约定中。

模型类别检测

所有模式的强制第一步。 在进行任何分析或生成之前，先确定目标模型类别。这会影响思维链策略、脚手架、示例用法和输出结构建议。

分类

启发式规则： 如果模型具有原生推理／思考模式 → 推理型。否则 → 指令遵循型。不确定时 → 默认选择指令遵循型（兼容性最广）。

**推理型：**支持扩展思考的 Claude、GPT-5.5／GPT-5.x 推理模式、Gemini 思考模式、o 系列模型、Llama 推理变体
**指令遵循型：**Claude 3.5 Sonnet／Haiku、GPT-4o／4.1、Gemini 2 Flash、标准版 Llama 4

模型类别的行为差异

维度	指令遵循型	推理型
思维链	在有助于提高可靠性时，使用简洁的推理框架	不要要求输出隐藏的推理过程；使用提供商支持的推理强度，或在当前文档建议时使用简短规划／前言
少样本示例	效果显著——提供 3-5 个多样化示例	效果有限——仅提供 1 个用于说明格式的示例，或采用零样本
框架约束	结构越清晰，输出效果越好	过度的结构会限制推理——提供目标，而非步骤
提示词长度	通常越详细越有帮助	简洁且目标明确的提示词优于冗长的提示词
温度	视任务而定（0.0-1.0）	通常由内部固定；外部温度的影响较小

通用预检

进入特定模式的工作流前，每种模式都要执行此预检。

1. 读取输入 — 从 $ARGUMENTS 文本或文件路径读取提示词。如果提供了文件路径，则读取该文件。
2. 检测模型类别 — 从提示词内容中检测目标模型，或询问用户。运行上方的模型类别检测。标记任何模型类别不匹配的情况（例如，将 CoT 框架用于推理型模型）。
3. 识别上下文 — 确定部署上下文（单轮 API、聊天、Agent 循环、RAG 流水线、多 Agent）和输入信任级别（可信内部输入与不可信外部输入）。
4. 上下文管理触发条件 — 如果工作涉及多轮、长上下文、RAG、Agent 循环或成本敏感型提示词，请阅读 references/context-management.md，并在结果中明确说明相关的缓存、压缩、选择或隔离决策。
5. 证据类别检查 — 将非显而易见的建议归类为官方文档、同行评审／预印本、社区启发式规则、本地实践或单项研究；标记任何超过 90 天的提供商建议，以便验证。
6. 范围检查 — 如果用户要求运行提示词、构建 Agent 或执行非提示词相关的实现工作，请先拒绝并引导用户，再进行提示词分析或生成。

模式 A：编写

从头开始编写新提示词。适用于用户没有现有提示词的情况。

工作流编写

1. 运行共享预检 — 完成上述共享预检，包括范围和信任边界检查。

2. 需求收集 — 提出有针对性的问题：

   • 任务是什么？（请具体说明——“总结”与“提取关键决策”不同）
   • 目标模型是什么？（识别模型类别）
   • 部署环境是什么？（单轮 API 调用、聊天、Agent 循环、RAG 流水线、任务委派／研究服务）
   • 输出应采用什么格式？
   • 需要防止哪些故障模式？
   • 输入由谁提供？（可信内部来源与不可信外部来源——这决定安全需求）

3. 选择架构 — 根据部署环境，从 references/architecture-patterns.md 中选择：

   • 单轮：4 块模式（上下文／任务／约束／输出）
   • 多轮：带状态管理的会话感知模式
   • Agent：采用 3 条指令模式的 ReAct（持久性 + 工具调用 + 规划）
   • RAG：带引用模式的落地指令
   • 多 Agent：采用角色隔离的编排
   • 任务委派：4 块模式，重点强调范围定义和输出结构

4. 上下文管理检查 — 如果提示词涉及多轮、长上下文、RAG、Agent 循环或成本敏感场景，请阅读 references/context-management.md，并决定哪些内容应缓存、压缩、筛选或隔离。

5. 起草提示词 — 使用所选架构编写提示词。应用 references/model-playbooks.md 中针对特定模型类别的指导。对于包含多个部分的提示词，默认从 XML 标签开始构建，除非目标模型或输出约定表明应采用更合适的结构。起草后，根据目标模型对应的 playbook 部分进行检查和最终调整。

6. 优化结构以便缓存 — 按照有利于提示词缓存的方式安排内容：

   • 静态内容（系统指令、角色定义、工具描述）→ 放在提示词前部
   • 动态内容（用户输入、检索到的文档、对话历史）→ 放在提示词后部
   • 具体节省量、TTL 和令牌阈值因提供商而异；引用缓存经济效益前，请先查阅 references/context-management.md

7. 强化 — 按照 references/hardening-checklist.md 逐项检查：

   • 如果输入来源不可信 → 应用防注入模式
   • 如果输出面向用户 → 添加安全约束
   • 如果涉及工具调用 → 尽量缩小权限范围
   • 针对预期故障模式添加边缘情况处理

8. 呈现 — 按照 references/output-formats.md 中的 Annotated Prompt 格式呈现。建议使用 Mode D (Evaluate) 构建测试套件。

模式 B：分析

诊断现有提示词，并可选择进行改进。通过 analyze（附带修复）或 audit（仅报告，不做更改）进行分派。

分析工作流

1. 运行共享预检 — 在为提示词评分或分析之前，先完成上述共享预检。

2. 诊断评分 — 使用 references/output-formats.md 中的 Diagnostic Scorecard，从 5 个维度为提示词评分：

   维度	分数（1-5）	评估
   清晰度		指令有多明确？
   完整性		是否提供了所有必要的约束和上下文？
   效率		每个词元是否都发挥了作用？（检查是否过度具体）
   稳健性		处理边缘情况和对抗性输入的能力如何？
   模型适配度		是否针对目标模型类别进行了优化？

   给出 25 分制的总分，并简要说明每个维度的评分依据。

3. 四视角分析 — 通过以下每个视角检查提示词：

   • 歧义视角： 找出可能存在多种解读的指令。标出模型需要猜测的缺失上下文。检查是否存在冲突指令。
   • 安全视角： 使用 references/hardening-checklist.md 检查提示词注入漏洞。评估输入信任边界。检查信息泄露风险。
   • 稳健性视角： 找出未覆盖的边缘情况。检查可能因意外输入而失效的脆弱模式。评估优雅降级能力。
   • 效率视角： 标出词元浪费（重复指令、不必要的示例、过度具体）。评估缓存能力。检查过度具体悖论。

4. 反模式扫描 — 对照 references/anti-patterns.md 中的所有模式进行检查。对于检测到的每种反模式，报告：模式名称、严重程度、在提示词中的位置，以及修复建议。

5. 模型适配度验证 — 评估提示词是否适合其目标模型，并验证建议是否为最新：

   • 是否使用了适合该模型类别的技术？
   • 是否有应利用但尚未利用的特定模型功能？
   • 是否存在针对该模型的反模式？（例如，Claude 4.x 中的预填充响应）
   • 阅读目标模型对应的 references/model-playbooks.md，并注明“最后验证”日期
   • 如果任何建议已超过 3 个月，请标出：“部署前，请根据当前的 [model] 文档进行验证”

仅报告模式（audit）：按照 references/output-formats.md 中的 Audit Report 格式呈现调查结果。如果需要修复，建议执行完整的分析；如果没有评估方案，建议使用模式 D（评估）。到此结束。

完整模式（analyze）：继续执行步骤 6-7。

6. 应用改进 — 对于评分低于 4 的每个维度：

   • 指出具体问题
   • 提出有针对性的修复方案
   • 展示每项变更的修改前和修改后内容
   • 引用推动该变更的技术或原则（来自 references/technique-catalog.md 或 references/anti-patterns.md）

7. 呈现结果 — 使用 references/output-formats.md 中的 Diagnostic Scorecard 格式呈现诊断结果，并使用 Changelog 格式呈现提议的变更。如果没有评估方案，建议使用模式 D（评估）。

模式 C：转换

在保留提示词意图和质量的前提下，将提示词移植到另一种模型系列。

转换工作流

1. 运行共享预检 — 在制定转换计划之前，先完成上文的共享预检。

2. 加载操作手册 — 阅读 references/model-playbooks.md 中的源模型和目标模型操作手册部分。注意主要差异：

   • 结构格式偏好（XML、Markdown 或 JSON）
   • 系统提示词约定
   • 功能可用性（预填充、缓存、思考模式）
   • 已知行为差异

3. 制定转换计划 — 创建转换检查清单：

   • 可直接映射的功能（重命名／重组）
   • 需要适配的功能（机制不同，但意图相同）
   • 没有对应功能的部分（必须移除或模拟）
   • 可利用的新功能（目标模型具备而源模型不具备的能力）

4. 执行转换 — 应用计划。对于每项变更：

   • 展示源模式
   • 展示目标模式
   • 解释需要进行该变更的原因

5. 验证 — 对转换后的提示词运行 Mode B（分析）只报告分析，以发现转换引入的问题。按 references/output-formats.md 中的 Conversion Diff 格式呈现。建议在两个模型上使用相同的测试用例运行 Mode D（评估）。

Mode D：评估

为提示词构建评估框架。不运行评估，只生成评估设计。

评估工作流

1. 运行共享预检 — 在定义评估计划之前，先完成上文的共享预检。

2. 定义成功标准 — 与用户一起确定“正常工作”意味着什么：

   • 功能标准（是否生成正确的输出？）
   • 质量标准（输出是否足够好？）
   • 安全标准（是否避免了有害输出？）
   • 边缘情况标准（是否能处理异常输入？）

3. 设计测试套件 — 根据 references/evaluation-frameworks.md 创建测试用例类别：

   • 黄金集： 5-10 个具有预期输出的代表性输入
   • 边缘情况： 边界条件、空输入、极长输入
   • 对抗性用例： 注入尝试、超出范围的请求、含糊不清的输入
   • 回归用例： 之前失败过的用例（如正在优化现有提示词）

4. 生成测试用例 — 为每个类别生成具体的测试用例：

   • 输入（要发送的确切文本）
   • 预期行为（模型应执行的操作）
   • 失败指标（哪些情况表明提示词存在问题）

5. 构建评分标准 — 按照 references/output-formats.md 中的 Evaluation Framework 创建评分标准：

   • 清晰定义的维度
   • 评分等级（1-5），并为每个等级提供具体示例
   • 用于自动评估的 LLM-as-judge 提示词（如适用）
   • 针对主观维度的人工评估流程

6. 呈现 — 按照 references/output-formats.md 中的 Evaluation Framework 格式呈现。包含来自 references/evaluation-frameworks.md 的推荐评估工具和 CI/CD 集成模式。

Mode E：加固

对处理不可信输入、工具结果、检索文档、面向用户的输出或生产操作的提示词进行压力测试并加以改进。

1. 运行共享预检 — 识别信任边界、外部内容来源、工具、输出目标和故障成本。
2. 加载加固指南 — 阅读 references/hardening-checklist.md 和 references/architecture-patterns.md 中的安全章节。
3. 梳理攻击方式 — 检查直接注入、间接注入、提示词提取、工具滥用、输出格式逃逸、上下文耗尽和敏感数据泄露。
4. 提出控制措施 — 酌情添加分隔符、指令层级、最小化工具权限、输出验证、令牌预算、优雅降级和监控钩子。
5. 呈现 — 使用 Harden Report 模板。包含剩余风险，以及部署前应当失败的评估用例。

模式 F：工具

设计或审查面向模型的工具定义、函数架构、MCP 工具描述和工具选择说明。

1. 运行共享预检 — 确定目标模型／提供商、工具接口、权限、输入／输出架构和故障模式。
2. 加载工具模式 — 阅读 references/architecture-patterns.md 和 references/hardening-checklist.md。
3. 审查架构 — 检查名称是否清晰、描述是否具体、参数类型／枚举值／默认值、可选行为、错误契约，以及与相邻工具是否重叠。
4. 审查安全性 — 应用最小权限原则、限定允许使用的工具、为破坏性／开放世界操作设置门控、验证工具结果，并隔离不可信结果。
5. 呈现 — 使用 Tool Definition Review 模板，并提供重写后的工具文档或架构差异。

模式 G：PromptOps

规划提示词生命周期控制。不部署或运行提示词。

1. 运行共享预检 — 确定负责人、模型／提供商、版本管理接口、评估、发布风险和可观测性技术栈。
2. 加载评估指南 — 阅读 references/evaluation-frameworks.md、references/output-formats.md 和相关的提供商手册章节。
3. 设计生命周期 — 定义提示词版本、关联评估、黄金／对抗／回归测试集、发布门控、监控指标、漂移检查和回滚步骤。
4. 设置证据门控 — 要求在进行特定于模型的发布变更前，核实当前提供商文档。
5. 呈现 — 使用 PromptOps Plan 模板。

参考文件索引

文件	内容	何时阅读
references/technique-catalog.md	涵盖 8 个类别的约 36 种技术及其与模型类别的兼容性	为任何模式选择技术时
references/model-playbooks.md	Claude、GPT、Gemini、Llama 指南及缓存策略	提出任何特定于模型的建议时
references/anti-patterns.md	14 种反模式及其严重程度、检测方法和修正方案	分析或编写任何提示词时
references/architecture-patterns.md	Agent、RAG、工具调用、多 Agent 设计模式	编写 Agent 或系统提示词时
references/context-management.md	压缩、缓存、上下文腐化、ACE 框架	设计长上下文或多轮系统时
references/hardening-checklist.md	安全性和稳健性检查清单（29 项）	强化任何处理不可信输入的提示词时
references/evaluation-frameworks.md	评估方法、PromptOps 生命周期、工具指南	构建评估框架时
references/output-formats.md	所有技能输出的模板（评分卡、报告、差异）	设置任何技能输出的格式时
scripts/validate-references.py	用于检查参考索引、提供商元数据、分发／评估覆盖范围的确定性检查	编辑参考资料、分发或评估后

请按上表“何时阅读”一列的说明阅读参考文件。不要依赖记忆或既有知识。 参考文件是事实依据。若参考文件不存在，请继续操作，但要注明此缺失。

关键规则

1. 不要建议为推理模型强制提供隐藏的思维链记录；如果当前文档支持，请优先采用提供商支持的推理控制，或简洁的规划／前言
2. 多段提示词应使用清晰的分隔符；XML 标签是 Claude 和许多复杂提示词的首选默认方式，但请核实提供商特定的格式指南
3. 处理不可信输入的任何提示词都必须经过安全审查（references/hardening-checklist.md）
4. 对任何非简单提示词，都应建议进行评估（模式 D）——提示词只是待验证的假设
5. 按参考索引阅读参考文件——不要依赖记忆
6. Analyze 中的仅报告模式（audit）为只读模式——绝不要修改正在审计的提示词
7. 将 Agent 提示词建议限定在其证据类别内；不要将 OpenAI 的 Agent 指南说成适用于所有模型的普遍证据
8. 如果无法明确判断是提示词还是请求，请先询问再选择模式
9. 拒绝并引导用户改为提出提示词、构建 Agent 或进行非提示词实现工作的请求
10. 对于提供商特定的说法，请引用 references/model-playbooks.md，注明其最后验证日期，并标记超过 90 天未更新的指南
11. 添加模式或更改分发行为时，应更新评估
12. 更改参考资料、分发逻辑或评估后，运行 scripts/validate-references.py

合理化借口的应对

规则压力	可能的借口	必须采取的应对措施
提供商文档时效性	“我记得当前模型的行为。”	检查 model-playbooks.md 并报告最后验证日期。
安全加固	“提示词仅供内部使用。”	说明信任边界；如果存在任何外部内容，则运行模式 E。
评估后续工作	“提示词看起来没问题。”	至少纳入黄金、边界、对抗和回归评估类别。
范围边界	“运行一下就能证明提示词有效。”	拒绝执行，并改为提供提示词／评估计划。
分发歧义	“意图已经足够明显。”	如果创作与分析，或提示词与实现工作的意图混杂，请询问用户选择模式。