主题
Prompt
什么是 Prompt？
Prompt 是交给 AI 的当前任务说明。它不只是聊天开头的一句话，而是一份临时任务协议：告诉 Agent 要解决什么问题、可以使用哪些上下文、边界在哪里、什么结果才算完成。
这里的 Agent 泛指能理解任务、读取上下文、调用工具并产出结果的 AI 工具或平台。不同 Agent 工具的界面、模型、文件引用语法、权限系统和自动化能力不同，但 Prompt 的核心目标是一致的：降低误解，减少无效探索，让结果可验证。
Prompt 不替代项目规则、流程文档或外部工具配置：
md
长期项目规则 -> AGENTS.md / 项目规则文档
可复用任务流程 -> Skill / Workflow / Playbook
外部工具与实时信息 -> MCP / 插件 / API 集成
当前任务目标 -> PromptAgent 如何理解任务？
多数 Agent 会综合多类信息做决策：
- 当前 Prompt：本次任务的目标、范围、约束和输出要求。
- 上下文：打开的文件、选中的代码、对话历史、仓库文件、错误日志、截图或外部资料。
- 项目规则：
AGENTS.md、团队规范、代码风格、测试要求、安全边界。 - 可用能力：文件读写、终端命令、浏览器、搜索、MCP、内部插件、子任务代理等。
- 工具限制：是否能联网、是否能写文件、是否能执行命令、是否需要人工确认。
因此，好的 Prompt 不需要把所有背景都塞进去，而是要把“本次任务必须遵守的信息”说清楚。通用做法是：目标明确、上下文足够、范围有限、约束可执行、验收可验证。
基本结构
推荐使用下面的顺序：
md
目标 -> 背景 -> 范围 -> 约束 -> 验收标准 -> 输出要求示例：
md
目标：修复用户列表页面切换分页后数据未更新的问题。
背景：
- 用户从第 1 页切到第 2 页后，表格仍显示旧数据
- 最近改动过列表缓存逻辑
范围：
- 优先检查 `apps/web/src/pages/users/**`
- 必要时可修改该页面直接使用的 hooks 或测试文件
- 不修改公共组件库、接口定义或无关页面
约束：
- 保持现有请求缓存方案
- 不新增全局状态
- 不修改生成文件
- 不执行发布、删除数据或重置仓库等高风险操作
验收标准：
- 切换分页后列表数据正确刷新
- 保留现有加载态和错误态
- 补充或更新相关测试
- 相关 lint 和测试通过
输出：
- 说明根因
- 概述修改内容
- 给出验证结果和未覆盖风险什么时候写短 Prompt？
任务足够小、上下文就在当前文件里、风险很低时，短 Prompt 就够了。
md
把当前函数里的错误提示改得更清楚，不改变逻辑。md
解释这段代码的执行流程，重点说明数据从哪里来、在哪里被修改。md
把这段英文技术说明翻译成自然中文，保留 API、Hook、Component 等常见术语。短 Prompt 的前提是上下文明确。如果 Agent 需要猜项目结构、业务目标或验收标准，就应该补充信息。
常见任务写法
提问与解释
md
解释 `apps/web/src/features/auth` 的登录流程。
请重点说明：
- 用户提交表单后经过哪些模块
- Token 存在哪里
- 刷新登录状态的逻辑在哪里
- 哪些地方可能导致登录态丢失
不要修改代码。功能开发
md
在订单列表中新增筛选功能。
范围：
- 优先修改 `apps/web/src/pages/orders/**`
- 复用项目已有筛选组件和 URL Query 同步方式
- 不修改后端接口契约
要求：
- 支持按订单状态和创建时间筛选
- 刷新页面后保留筛选条件
- 补充相关测试
- 完成后说明修改内容和验证结果Bug 修复
md
修复用户编辑页保存后页面数据未更新的问题。
请先定位根因，再做最小范围修改。
要求：
- 不修改接口契约
- 保持现有缓存和错误处理逻辑
- 添加或更新回归测试
- 运行相关 lint 和测试
- 输出根因、修改内容和验证结果代码审查
md
审查最近对支付模块的改动。
重点检查：
- 权限与数据泄露风险
- 金额、币种和精度处理
- 幂等性与重复提交
- 异常处理
- 测试覆盖不足
不要直接修改代码。按严重程度输出问题、位置、原因和建议。重构
md
重构用户资料模块中重复的表单提交逻辑。
目标：
- 消除重复代码
- 不改变现有行为
- 不修改 API 契约
- 保持组件对外接口兼容
请先说明重构方案，确认风险点后再修改。
完成后运行相关测试，并说明验证结果。测试修复
md
修复用户模块中失败的测试。
要求：
- 先区分生产代码问题、测试问题和环境问题
- 不要通过删除断言、跳过测试或放宽关键断言来规避失败
- 优先修复根因
- 输出失败原因、修改内容和测试结果文档整理
md
重写这组 AI Agent 文档，让描述更通用。
要求：
- 不强绑定某个具体工具
- 可以举例，但不要写成只有某个具体 Agent 工具适用
- 重点讲清概念、适用场景、使用方式和边界
- 保持现有站点的 Markdown 风格常见问题
目标太模糊
不推荐：
md
优化一下这个项目。推荐：
md
优化 Dashboard 页面的首次加载性能。
范围：
- 仅分析 Dashboard 页面及其直接依赖
- 不修改构建工具、公共组件库或后端接口
目标：
- 减少首次渲染时不必要的请求和重复计算
- 保持现有功能与页面结构不变
输出：
- 性能瓶颈
- 优化方案
- 修改内容
- 验证方式范围太大
不推荐：
md
检查整个仓库并修复所有问题。推荐：
md
检查认证模块中与 Token 刷新相关的逻辑。
重点关注：
- 并发请求
- Token 过期处理
- 错误重试
- 类型安全
不要修改认证模块以外的代码。只有目标，没有验收标准
不推荐：
md
把表格做得更好用。推荐：
md
改进用户表格的可用性。
要求：
- 表头固定
- 支持按用户名排序
- 空数据时显示统一 Empty State
- 移动端可横向滚动
- 不修改接口层
- 补充相关组件测试只给实现方案，没有说明问题
不推荐：
md
把这里改成 useMemo。推荐：
md
这个列表在输入搜索词时会明显卡顿。请先确认性能瓶颈，如果重复计算是主要原因，再使用合适的缓存方式优化。
要求：
- 不改变搜索结果
- 不引入全局状态
- 说明为什么采用当前方案Agent 更擅长在目标清楚时选择实现方式。如果直接指定实现，可能会掩盖真正问题。
与项目规则的配合
项目长期规则应放在 AGENTS.md、团队规则文件或工具支持的项目指令中；Prompt 只补充本次任务特有的信息。
适合放在项目规则中的内容：
- 包管理器、构建和测试命令
- 代码风格、提交规范、目录约定
- 生成文件、敏感文件和高风险操作边界
- 不同目录对应的负责人、规范或流程
适合放在 Prompt 中的内容：
- 本次要解决的问题
- 本次允许修改的范围
- 本次必须保留的行为
- 本次需要特别关注的风险
- 本次完成后的输出格式
与 Skill / Workflow 的配合
有些 Agent 工具支持 Skill、Workflow、Command、Playbook、Recipe 或类似机制，用来保存可复用任务流程。不同工具名称不同，本质都是把“重复出现的一类任务步骤”沉淀下来。
Prompt 可以明确要求使用某个流程：
md
使用项目中的前端页面开发流程，为订单页面新增筛选功能。也可以只描述任务，让 Agent 根据工具能力和项目规则自动判断：
md
为订单页面新增筛选功能，遵循项目已有前端开发规范。Prompt 不需要重复流程文件中的全部步骤，应聚焦本次任务的目标、范围和验收标准。
与 MCP / 外部工具的配合
当任务依赖仓库外信息时，可以在 Prompt 中说明要使用哪些外部信息，以及哪些操作不允许。
md
修复与订单状态同步有关的问题。
请先：
- 查看关联 Issue 和最近相关 PR
- 确认订单状态字段在 API 文档中的定义
- 不查询生产环境用户数据
- 不执行写入、发布或部署操作关键不是“尽可能多地接入工具”，而是只授予任务必要的信息和权限。
推荐模板
md
目标：
<希望解决的问题或完成的功能>
背景：
- <已知现象、业务背景、相关错误、用户反馈>
范围：
- <允许查看或修改的目录、模块、文件>
- <不允许修改的目录、模块、文件>
约束：
- <技术约束、兼容性要求、安全限制>
- <禁止操作或需要先确认的操作>
验收标准：
- <可验证的行为结果>
- <测试、lint、构建或人工验证要求>
输出：
- <需要说明的内容，例如根因、方案、修改内容、验证结果、风险>总结
Prompt 的作用是把当前任务说清楚，而不是承载所有项目知识。
md
项目规则 -> 长期有效的仓库约定
Skill / Workflow -> 可复用任务流程
MCP / 外部工具 -> 仓库外信息和受控操作
Prompt -> 当前任务目标、边界和验收标准