OpenSpec是一款基于SPEC范式的、轻量的代码提示词辅助工具，帮助你优化提示词，更精准的表述代码编写意图

链接：https://github.com/Fission-AI/OpenSpec

核心思想：把原来“一句话”就要AI干的活儿，细化成“四个文档”。

以此提高AI代码编写质量，主要有如下四个文档：

1. proposal：为什么要做
2. specs：需求和场景
3. design：技术设计
4. tasks：具体实施清单

Prompt 的设计艺术

Prompt Engineering 不是“写一句让 AI 更聪明的话”，而是把一个模糊目标转化为清晰、可执行、可验证、可迭代的任务协议。

Sidebar Navigation

1. AI Coding
2. AI 使用
3. AI 文章解读
4. AI 模型
5. Agent
6. Agent 是什么？
7. Codex
8. Harness
9. Memory
10. Prompt
11. Prompt Engineering 的本质
12. Prompt 的基本组成
13. Prompt 的六大核心技术
14. Prompt 的五大设计原则
15. Prompt 的五种高级模式
16. Prompt 工程化
17. Prompt 模板
18. Prompt 安全
19. Prompt 评估与优化
20. 常见问题
21. RAG
22. 如何让 AI 生成指定格式的输出
23. 端侧模型

AI Coding

在 AI Coding 中，Prompt 不应只是：

text

复制

而应至少说明：

1. 项目背景和已有代码；
2. 需要修改的文件或模块；
3. 功能目标和非目标；
4. 技术约束和兼容性要求；
5. 验收标准和测试方式；
6. 是否允许修改代码、配置或数据库；
7. 是否需要先提出方案再实施。

一个更可靠的编码任务可以写成：

text

复制

对于复杂功能，推荐采用：

text

复制

这也是 OpenSpec 等规范驱动工具的核心思想：将聊天中的临时意图沉淀为项目可共享的工作文档。

AI 使用

高质量使用 AI 的关键不只是“会提问”，还包括：

1. 明确目标；
2. 提供必要上下文；
3. 划定权限和边界；
4. 规定输出协议；
5. 对结果进行验证；
6. 通过反馈持续迭代。

可以把 AI 看作一个能力很强但不会自动承担业务责任的协作者。用户需要负责目标、上下文、权限和最终验收。

AI 文章解读

让 AI 解读文章时，不要只说“总结一下”。可以明确解读视角：

text

复制

AI 模型

不同模型的能力、上下文长度、工具支持、成本和延迟不同。Prompt 不能完全弥补模型能力差异，因此生产系统应记录：

1. 模型名称和版本；
2. Temperature、Top P 等参数；
3. 上下文和检索版本；
4. 工具定义和调用结果；
5. Prompt 版本；
6. 评估集和评估结果。

同一个 Prompt 在不同模型上可能表现不同，迁移模型时必须重新进行回归测试。

Agent

Agent 不只是“能聊天的模型”，而是由以下部分组成的闭环：

text

复制

Agent Prompt 需要额外规定：

1. 可使用哪些工具；
2. 何时使用工具；
3. 工具参数如何校验；
4. 哪些操作需要用户确认；
5. 失败时如何重试或降级；
6. 什么时候停止；
7. 如何汇报执行结果。

Agent 是什么？

一个实用的 Agent 定义是：

Agent 是以大语言模型为决策核心，能够在给定权限范围内感知环境、规划步骤、调用工具并根据反馈完成目标的系统。

它通常由六部分组成：

Goal任务目标Context当前上下文和状态Planner生成或调整计划Tools与外部世界交互Memory保存必要的历史信息Evaluator检查结果是否合格

Agent 不是越自主越好。高风险操作应使用最小权限、预览和确认机制。

Codex

在 Codex 等 AI Coding 工具中，Prompt 最好包含：

1. 需要阅读的文件；
2. 不允许触碰的文件；
3. 代码风格和项目约定；
4. 实施步骤；
5. 测试命令；
6. 完成后的报告格式。

示例：

text

复制

Harness

Harness 是包裹模型的执行框架。它负责把 Prompt、工具、状态、权限、日志和评估连接起来。

一个 Agent Harness 通常包含：

text

复制

因此，Prompt 只是系统的一部分。即使 Prompt 写得很好，如果 Harness 没有：

1. 超时控制；
2. 重试限制；
3. 工具权限隔离；
4. 输出 Schema 校验；
5. 日志和追踪；
6. 成本控制；

系统仍然可能不可靠。

Memory

Memory 用于保存跨轮次、跨任务或跨会话的信息。应区分：

1. 短期记忆：当前对话和当前任务上下文；
2. 工作记忆：当前 Agent 的计划、工具结果和中间状态；
3. 长期记忆：用户偏好、项目约定和历史事实；
4. 外部知识库：通过检索按需加载的文档。

不要把所有历史聊天全部塞进 Prompt。更好的方法是：

1. 提取稳定事实；
2. 删除过期或重复内容；
3. 为记忆增加来源和时间；
4. 在使用前检索相关记忆；
5. 允许用户查看、修改和删除记忆。

Prompt

一、Prompt Engineering 的本质

很多人误以为 Prompt 是：

“写一句让 AI 更聪明的话。”

其实，Prompt 的本质是：

控制模型可用的上下文、任务边界、决策路径和输出结构。

在抽象层面，语言模型根据输入上下文预测后续 Token：

text

复制

Prompt 不能直接改变模型参数，但可以通过改变输入上下文影响输出概率分布。它主要完成四件事：

1. 缩小问题空间；
2. 提供完成任务所需的信息；
3. 规定结果的结构和质量标准；
4. 指定不确定、冲突和异常情况下的行为。

因此，Prompt 不是魔法咒语，也不是越长越好。它更像一份给模型执行的任务说明书。

Prompt 能做什么，不能做什么

Prompt 可以：

1. 明确任务目标；
2. 指定角色和受众；
3. 提供背景与示例；
4. 规定输出格式；
5. 要求检查和引用；
6. 约束工具使用行为。

Prompt 不能保证：

1. 模型掌握不存在的知识；
2. 模型永远不产生错误；
3. 外部工具一定成功；
4. 复杂业务规则无需程序校验；
5. 一个版本在所有模型上都同样有效。

二、Prompt 的基本组成

最稳定、最容易复用的结构是 R-C-T-O-C：

text

复制

1. Role：角色

角色用于设置工作视角、专业范围和责任边界：

text

复制

好的角色定义不只写头衔，还应说明：

1. 服务对象；
2. 负责事项；
3. 专业范围；
4. 能力边界。

2. Context：背景

背景回答“模型需要知道什么”：

text

复制

背景应与任务相关。无关信息越多，模型越容易抓错重点，也会增加成本和延迟。

3. Task：任务

任务使用明确动词：

text

复制

“设计一个系统”太宽泛；“设计一个支持 10 万并发的任务调度架构，并说明调度、执行、重试和监控模块”更容易执行。

4. Output：输出

输出协议应说明格式、章节、长度和语言：

text

复制

5. Constraints：约束

约束用于定义边界、禁止项和验收标准：

text

复制

R-C-T-O-C 示例

text

复制

Role控制工作视角和能力边界Context提供任务所需背景Task明确要完成的动作Output规定输出结构和格式Constraints限制范围并定义验收标准

三、Prompt 的六大核心技术

1. Zero-shot Prompt

不给示例，直接描述任务：

text

复制

优点：简单、快速、成本低。缺点：复杂任务中格式和判断标准可能不稳定。

适合：

1. 简单总结；
2. 一般改写；
3. 创意生成；
4. 规则清晰的简单问答。

2. Few-shot Prompt

提供输入和期望输出示例：

text

复制

适合：

1. 分类；
2. 数据抽取；
3. 固定风格生成；
4. JSON 或表格输出；
5. 边界规则不容易文字描述的任务。

示例必须和真实任务相似，并覆盖正常、边界和异常情况。示例本身也会消耗上下文，因此不应无止境增加。

3. Chain-of-Thought 与分步推理

复杂任务通常适合分解步骤：

text

复制

分步任务有助于提高复杂问题的稳定性。但在实际产品中，不必要求模型暴露完整的内部思维过程。更稳妥的做法是要求：

1. 简要说明依据；
2. 输出中间检查结果；
3. 展示公式、引用或决策依据；
4. 对最终答案进行自检。

4. Self-consistency

Self-consistency 的思想是：对同一问题生成多个候选答案，再通过投票、打分或规则选择更一致的答案。

text

复制

它更适合逻辑推理、数学计算和复杂决策，不适合所有任务。代价是更多 Token、时间和调用次数。生产系统应设置最大候选数和成本上限。

5. ReAct

ReAct 将推理和行动结合起来，适合 Agent：

text

复制

简化示例：

text

复制

不要把内部思考日志直接暴露给用户。可以将工具调用记录和简短决策依据作为可审计信息。

6. Tree-of-Thought

Tree-of-Thought 让模型探索多个候选路径，再依据评价标准选择方案：

text

复制

适合：

1. 架构设计；
2. 复杂规划；
3. 方案比较；
4. 多约束决策。

使用时必须提供选择标准，否则模型只是生成更多文字，不一定得到更好的决策。

四、Prompt 的五大设计原则

1. 清晰性

坏 Prompt：

text

复制

好 Prompt：

text

复制

2. 上下文充分但不过载

模型不会自动知道你的项目背景。应提供：

1. 业务目标；
2. 用户和使用场景；
3. 技术栈；
4. 已有实现；
5. 输入数据；
6. 约束和历史决策。

但不要把所有资料不加筛选地塞进上下文。应先检索、摘要、去重和排序。

3. 输出结构化

输出结构决定结果能否被人稳定阅读或被程序继续处理：

text

复制

对生产系统而言，Prompt 约束不够，还应在代码层使用 JSON Schema、类型校验和业务校验。

4. 任务拆解

不要：

text

复制

改为：

text

复制

5. 防止幻觉

text

复制

五、Prompt 的五种高级模式

模式 1：Ask-first Prompt

适用于需求不完整的任务：

text

复制

不要让模型无条件提出大量问题，否则会降低效率。应限定“只有会改变范围、行为、兼容性或验收标准的问题才需要询问”。

模式 2：Checklist Prompt

让模型在输出前进行检查：

text

复制

Checklist 适合代码评审、文档审查和结构化生成。

模式 3：Step Prompt

text

复制

模式 4：Critic Prompt

让模型分别生成和评审：

text

复制

更可靠的系统可以让独立的评审模型或规则引擎进行检查，避免同一个模型“自己生成、自己认可”。

模式 5：Debate Prompt

适用于方案评估：

text

复制

辩论不是为了制造冲突，而是为了显式呈现不同方案的假设和代价。

六、Prompt 工程化

真正的 AI 系统通常是：

text

复制

因此，Prompt 只是 AI 应用的一部分。更完整的概念是 Context Engineering（上下文工程），它关注：

1. 在正确的时间提供正确的信息；
2. 控制上下文的优先级、来源和时效；
3. 管理记忆、检索、工具结果和历史状态；
4. 使模型在有限上下文窗口内获得最大有效信息。

Prompt Template

固定结构与动态变量分离：

text

复制

模板变量应进行转义、长度限制和类型校验，避免用户输入破坏模板结构。

配置和版本管理

Prompt 应像代码一样管理：

1. 放入版本控制；
2. 设置版本号和负责人；
3. 保存变更原因；
4. 记录模型和参数；
5. 配套测试集；
6. 支持灰度和回滚；
7. 记录生产质量指标。

七、Prompt 模板

1. 通用问答模板

text

复制

2. RAG 问答模板

text

复制

3. 文本总结模板

text

复制

4. 代码修改模板

text

复制

5. 结构化抽取模板

text

复制

6. 方案评审模板

text

复制

八、Prompt 安全

1. Prompt Injection

外部网页、用户输入、检索文档和工具结果都可能包含恶意指令，例如“忽略之前的要求”。必须声明可信级别：

text

复制

2. 最小权限

Agent 只能获得完成任务所需的最小工具权限：

1. 只读任务不要授予写权限；
2. 写文件前展示目标路径和内容摘要；
3. 删除、发布、付款和发送消息前必须确认；
4. 限制命令执行目录和参数；
5. 限制重试次数、运行时间和预算。

3. 敏感信息保护

Prompt 和日志中不得泄露：

1. API Key；
2. Cookie 和 Token；
3. 密码；
4. 身份证、手机号等个人信息；
5. 未授权的企业内部资料。

应在输入、上下文、工具结果和输出四个阶段进行脱敏与过滤。

九、Prompt 评估与优化

Prompt 优化不应只凭感觉。推荐建立“样本—输出—评价—迭代”的闭环。

1. 建立基线

准备一组有代表性的测试集：

1. 常规样本；
2. 边界样本；
3. 缺失信息样本；
4. 冲突信息样本；
5. 恶意注入样本；
6. 超出能力范围的样本。

2. 定义指标

根据任务选择指标：

准确率结论是否正确完成率是否完成了任务目标格式合规率是否符合指定格式引用覆盖率关键结论是否有依据幻觉率是否出现资料外事实拒答准确率无依据时是否正确拒答延迟响应耗时成本Token 和工具调用成本

3. 迭代规则

一次只改变一个主要因素，例如：

1. 增加角色说明；
2. 增加一个示例；
3. 调整输出 Schema；
4. 增加资料不足规则；
5. 增加自检步骤；
6. 改变上下文排序。

每次修改后都要运行回归测试，避免一个场景变好、另一个场景变差。

4. 评估模型不是唯一答案

LLM-as-a-judge 可以辅助评估，但不能完全取代人工和程序规则。可靠评估通常组合：

1. 程序化校验；
2. 参考答案比对；
3. 引用和事实检查；
4. 人工抽样；
5. 独立模型评审；
6. 线上用户反馈。

5. 发布前检查

text

复制

十、常见问题

Prompt 是不是越长越好？

不是。有效信息越多越好，无关信息越少越好。过长的 Prompt 可能增加成本、延迟和注意力分散。应通过检索、摘要、去重和结构化降低噪声。

角色设定能显著提升模型能力吗？

角色主要改变表达视角和任务关注点，不能凭空增加模型没有的知识。真正重要的是任务、上下文、约束和评估标准。

一定要让模型“逐步思考”吗？

复杂任务适合分步执行和自检，但不必要求输出完整的内部思维过程。更适合要求简要依据、验证结果和结构化中间产物。

为什么已经要求输出 JSON，模型仍然输出 Markdown？

Prompt 约束本身不是强制解析器。生产系统应结合：

1. 原生结构化输出能力；
2. JSON Schema；
3. 解析失败重试；
4. 字段类型校验；
5. 不合格结果拒绝或降级。

Few-shot 示例越多越好吗？

不是。示例应具有代表性，覆盖关键边界，并保持格式一致。无关或冲突示例会降低效果。

如何选择 Prompt 还是微调？

如果问题主要是任务描述、输出格式、上下文和流程控制，优先优化 Prompt 和上下文工程。如果需要稳定学习大量领域表达、分类习惯或固定风格，再评估微调，同时仍需保留输入校验和输出评估。

RAG

RAG（Retrieval-Augmented Generation，检索增强生成）通过先检索资料，再让模型基于资料回答问题：

text

复制

RAG Prompt 的关键不是简单地把文档拼到问题前面，而是明确：

1. 文档来源和可信度；
2. 文档时间和版本；
3. 文档之间的优先级；
4. 如何处理缺失与冲突；
5. 如何引用证据；
6. 如何防止检索文本中的 Prompt Injection。

推荐输出：

text

复制

RAG 的效果同时取决于检索质量和生成质量。应分别评估：

1. 召回率；
2. 相关性；
3. 上下文完整性；
4. 引用正确率；
5. 最终答案准确率。

如何让 AI 生成指定格式的输出

1. 明确格式而不是笼统要求

不要只说：

text

复制

而要说明：

text

复制

2. 给出 Schema

json

复制

3. 说明缺失值和异常值

text

复制

4. 说明禁止项

text

复制

5. 使用程序校验

Prompt 不能替代验证。应用层应：

1. 解析输出；
2. 校验 JSON；
3. 校验字段类型；
4. 校验业务规则；
5. 失败时重试或转人工；
6. 保存原始结果用于排查。

端侧模型

端侧模型运行在个人电脑、手机、边缘设备或本地服务器上，优势包括：

1. 数据不必离开本地；
2. 延迟更低；
3. 可离线运行；
4. 调用成本可控；
5. 更容易进行本地定制。

限制包括：

1. 模型规模受硬件限制；
2. 复杂推理能力可能较弱；
3. 上下文长度、并发和吞吐受设备影响；
4. 工具调用与多模态能力可能不完整。

端侧模型的 Prompt 应更加重视：

1. 短而清晰的指令；
2. 少量高质量示例；
3. 严格限制上下文长度；
4. 更简单的输出格式；
5. 本地缓存和降级策略；
6. 端侧隐私和模型文件保护。

可以采用大小模型协作：

text

复制

结语

Prompt Engineering 的核心不是寻找一句神奇的提示词，而是持续回答五个问题：

1. 模型到底要完成什么任务？
2. 它需要哪些可靠上下文？
3. 哪些事情不能做？
4. 结果应该长什么样？
5. 如何判断结果是否合格？

一个优秀的 Prompt 通常具备以下特征：

1. 目标明确；
2. 上下文相关；
3. 指令有优先级；
4. 输出可验证；
5. 异常有处理方式；
6. 工具权限受控制；
7. 结果可以评估；
8. 版本能够回滚。

从“会提问”到“会设计任务协议”，是 Prompt 从个人技巧走向 AI 系统工程的关键一步。