提示词写法：让 AI 一次写对的魔法模板
先给答案：AI 能不能一次写对，取决于你的提示词里装的是「信息」还是「愿望」。 AI 编程提示词这一课讲的就是怎么装信息——上一课你把想法理成了四件套清单，这一课把清单落成 AI 一读就懂的文字：落笔有一个三要素模板，写偏了有一个两轮纠偏法则，每次都要重复的规矩有一个叫 AGENTS.md / CLAUDE.md 的沉淀处。
听起来像大部头学问，其实零基础 12 分钟就能走完。四款工具（Claude Code、Codex、OpenCode、WorkBuddy）全部适用——这一课讲的是给 AI 递信息的通用写法，不是某一家的私有语法。
工作流导读立的五条纪律，上一课展开了第一条「先规划再动手」，这一课接着展开第二条：怎么把清单写成 AI 一次写对的提示词。
学完你能做什么
- 用「位置 / 症状或目标 / 完成标准」三要素模板，把上一课的需求清单落成一条具体的 AI 编程提示词
- 手头有现成材料时不再描述，直接递过去：文件用
@引用、截图直接贴、报错原文粘进对话 - 写偏了当场拉回：同一件事纠正两次还不对，就清空会话把教训并进一条新提示词重写
- 把每次都要重复的规矩（构建命令、代码惯例、坑）沉淀进 AGENTS.md / CLAUDE.md，新会话自动加载
- 分清真信息与「魔法词」：「一步步思考」「重要！」这类加压用语，官方明确说不是关键词
你现在的困境
- 提示词写了一大段，AI 交回来的还是不对——你说不清它到底缺了哪句话
- 「用中文注释」「不要引入新库」这些规矩，每次开新会话都要重打一遍，漏一次就翻车
- 听说提示词有「魔法词」，不知道哪些真有用、哪些是玄学，只好每句都加「请一定要仔细」
什么时候用这一招
当你需要：
- 把上一课的四件套清单变成 AI 真正照着做的文字
- 修 bug、加功能这类日常任务少一轮返工
- 让同一个项目里每次会话都自动带上你的规矩
而且不想：
- 每条提示词都从零写起，越写越长还没重点
- 靠「重要！」「必须！」喊话压着 AI 听话
- 在同一轮对话里改到第五遍，还舍不得重来
🎒 开始前的准备
- 读完 先规划再动手：把一句话想法变成需求清单，手头留着那份四件套清单——本页直接拿它当原料
- 装好并用过至少一款工具：Claude Code、Codex、OpenCode 或 WorkBuddy
- 12 分钟和一杯水 ☕
核心思路
好提示词不是文笔好，是信息够。 Claude Code 官方最佳实践把这一条放在最前面：AI 开工前会先读你的代码，文件布局、惯例、测试框架它自己能找到；它找不到的是从来没写进代码里的东西——你开会定下的规矩、你脑子里的画面、「修好」在你心里的标准。具体的提示词之所以有效，是因为它补上了这些信息。
官方还给了一个「这句话写不写」的判断标准，两个问题：
- 它读代码能找到吗？
- 它真的会去找吗？
两个都是「是」，就别写——写了反而稀释重点。这跟往行李箱里塞东西是一个道理：塞得越满，真正重要的东西越容易被埋住。
上一课那张官方对照表里的例句，拆开看正好是三条信息：
| AI 缺的信息 | 例句里对应的部分 |
|---|---|
| 位置：去哪看 | 「查 src/auth/ 里的 token 刷新」 |
| 症状：出了什么事 | 「用户反馈会话超时后登录失败」 |
| 完成标准：修成什么样 | 「先写一个能复现问题的失败测试，再修好它」 |
还有一条容易漏：两个合理做法之间的偏好，代码里同样读不出来。 错误提示用弹窗还是行内提示，两种都合理，AI 选哪个全看运气；你偏要行内的，就提前写明——官方原话就是「在乎它选哪个，就先说」。
一句话记住这一课：提示词是递信息，不是许愿。
跟我做
（拿上一课的四件套清单当原料，四步走完：它先变成一条信息完整的提示词，再变成一套不用每次重写的长期配置。）
第 1 步：用三要素模板把清单落成一条 AI 编程提示词
为什么：清单是写给你自己理清思路的，提示词是喂给 AI 的——同一个信息，排布不同，AI 的第一反应完全不同。三要素模板把官方对照表的规律固化成填空题。
把四件套清单按这个模板重排（本页第一个魔法模板，直接复制去填）：
症状或目标：<谁、在什么情况下、遇到什么问题 / 想要做出什么>
相关位置：<文件、目录或报错原文；从零开始就写「从零开始」>
完成标准：<什么为真时算完成，要可验证>
硬约束：<不引入新库 / 保持现有风格 / 单文件交付……>WorkBuddy 用户：把填好的模板贴进创建任务时的「补充说明」——官方同样建议在任务描述里明确目标、范围、约束和预期输出。
填完自查一遍：每一行都是 AI 读代码读不出来的信息吗？读得出来的（比如「项目用的是 TypeScript」）删掉。
你应该看到：一条四行以内的提示词。发出去之后，AI 的第一个动作是去读你点名的文件，而不是反问「哪个 bug？」——这就是信息到位的样子。
- 小检查：我的「完成标准」一行是可验证的（能通过 / 不再复现 / 能打开），不是「做好了」
第 2 步：有现成的材料，直接递过去别描述
为什么：描述会失真，原件不会。官方建议的原话就是「已经有 AI 需要的东西，就递过去，别描述」——你花三句话转述的报错，不如原文一行。
四款工具都有「递」的通道，按材料类型对号入座：
| 材料 | 怎么递 |
|---|---|
| 文件 | Claude Code：输入 @ 加路径，文件内容直接进消息；Codex：@ 提及文件；OpenCode：桌面/网页端选择 Attach file、粘贴或拖进输入框；WorkBuddy：@ 引用文件、文档、规则 |
| 截图 / 设计稿 | Claude Code：直接贴进提示词；WorkBuddy：Ctrl/Cmd + V 粘贴截图；OpenCode：图片附件（先确认模型支持图片输入） |
| 报错输出 | 把输出原文粘进对话；Claude Code 还可以用管道直接喂 |
Claude Code 官方给的管道写法（报错日志不用打开复制，一句话问它）：
cat error.log | claude -p "这是怎么回事"💡 递材料 ≠ 免写提示词
递了原件，第 1 步的三要素照样要写——原件回答「位置」和「症状」，「完成标准」和「硬约束」仍然只有你知道。两样合起来，才是一条完整的提示词。
你应该看到：AI 引用的是你递的原件——复述文件内容、读出报错的关键行，而不是凭你的转述猜。
- 小检查：这条提示词里至少有一处是「递过去的原件」，不是我的转述
第 3 步：写偏了当场拉回，两轮纠不对就清空重写
为什么：再好的提示词也不能发射后不管。官方建议盯住 AI 开工的第一分钟，它一跑偏就打断——比写完再返工便宜得多。纠正还有个规律：同一件事纠正两次还不对，第三次大概率没用，因为对话里已经留下两条失败记录，AI 每一轮都在重读它们。
纠偏动作分三档，按跑偏程度升级：
- 当场打断：Claude Code 里按
Esc停下当前动作，已做的保留，然后发纠偏消息 - 回滚重来：
/rewind（或在空输入框连按两次Esc）打开回滚菜单，把代码、对话或两者一起退回更早的提示词 - 清空重写：纠正同一件事两次失败，就
/clear清空（或开个新会话），把两次学到的教训并进一条新提示词——官方原话：这几乎总是比第三轮纠正更好
纠偏消息别只发「不对」，也有模板（本页第二个魔法模板）：
停一下。你现在在做的是 <它正在做的>，我要的是 <正确的方向>。
先别改代码，用三句话向我确认你接下来的做法，我确认后再动手。Codex 官方补了一条会话纪律：一个聊天装一个连贯任务，别把整个项目塞进同一个会话——上下文越堆越厚，结果只会越来越差。
你应该看到：多数跑偏一次就拉回；拉不回的那次，你果断清空重写，新提示词一次到位。
- 小检查：回想一次我「改到第三轮」的经历——用两轮法则重演，会在哪一步清空重写？
第 4 步：把每次都重复的规矩沉淀进项目说明书
为什么：写了几条好提示词之后你会发现：「安装用 pnpm」「测试跑 vitest」「别动 src/legacy/」这些话每条提示词里都得带一遍。Codex 官方最佳实践的原话：提示词模式一旦跑通，下一步就是别再手动重复——这正是 AGENTS.md 存在的意义。 Claude Code 的对应文件叫 CLAUDE.md，OpenCode 读的也是 AGENTS.md。同一个机制：文件放在项目里，每个会话自动加载。
说明书里装什么？两份官方清单合并后就是四类：
| 类别 | 写什么 | 例 |
|---|---|---|
| 命令 | 怎么装依赖、跑测试、跑单个测试、类型检查 | pnpm install / pnpm vitest run path/to/file.test.ts |
| 惯例 | 错误处理用哪个 helper、哪些目录的模式不能抄 | 「用 src/lib/errors.ts，不抛裸字符串」 |
| 坑 | 环境变量、看起来没用其实有用的目录 | 「集成测试需要 DATABASE_URL」 |
| 完成的定义 | 怎么验证做完 | 「改完跑对应测试，通过才算完」 |
本页第三个魔法模板——说明书骨架（AGENTS.md / CLAUDE.md 通用）：
# 项目说明书
## 命令
- 安装依赖：<命令>
- 跑单个测试：<命令>
- 类型检查：<命令>
## 惯例
- <错误处理、命名、目录规矩，只写代码里看不出来的>
## 坑
- <环境变量、易误判的目录>
## 完成的定义
- <怎么验证做完：跑什么、看到什么算过>两条官方忠告，比模板本身更重要：
- 短而准，胜过长而全。 Claude Code 的记忆指南建议不超过 200 行；Codex 的说法是「短而准确的文件，比满是模糊规则的长文件有用」。从最基础的写起，只在注意到重复犯错之后才加新规则。
- 同样的错犯两次，让它复盘并更新说明书。 这是 Codex 官方给的具体动作——错的根源往往是说明书里缺了一条。
💡 WorkBuddy 用户
WorkBuddy 的任务对话同样支持 @ 引用「文件、文档、规则」。把常用规矩存成一份规则文档，创建任务时 @ 它，效果等于一份轻量说明书。
注意一个跨工具差异：OpenCode V2 只认 AGENTS.md，不拿 CLAUDE.md 当后备。多工具混用时，说明书放哪、层级怎么叠，进阶细节在 AGENTS.md 与 CLAUDE.md：给 AI 留一份项目说明书。
你应该看到：新会话不再需要你重打规矩——问一句「这个项目怎么跑测试」，它引用的是说明书里的命令。
- 小检查：说明书里每一条，都过得了核心思路那两个问题（代码里读不出 / 它不会自己去找）
检查点 ✅
- 我能背出三要素：位置、症状或目标、完成标准——外加一句硬约束
- 我递过原件：
@过文件、贴过截图或粘过报错原文，而不是用文字转述 - 纠正同一件事两次失败后，我清空重写过提示词，而不是发第三轮
- 我的重复规矩进了 AGENTS.md / CLAUDE.md，新会话自动带上
- 我删掉了提示词里的加压用语，换成了具体信息
踩坑提醒
❌ 把「魔法词」当开关
「一步步思考」「要彻底」，给规则加「重要！」甚至全大写——官方明确说这些是普通提示词文本，不是关键词；控制思考强度的是 effort / 推理强度档位，不是形容词。更糟的是，给总被忽略的规则堆强调，只会让模型把规则过度泛化。该做的不是加压，是把信息写具体；真的一次都不能例外的规则，用工具自带的强制机制（权限规则、钩子）——那是 成本与安全 的主题。
❌ 每条提示词都背着全部家当
Codex 官方把「把长期规则堆进提示词，而不是搬进 AGENTS.md」列为头号常见错误。提示词装这次任务的信息，说明书装长期规矩——混着写有两个代价：提示词越来越长、重点被稀释；换个会话，规矩全丢。
❌ 想要完整版，却只写了最小要求
AI 倾向保守理解你的话，做「满足字面要求的最小东西」——它看不到你心里期待多大。想要空状态、错误提示、保存流程都做全的版本，就在提示词里把范围列出来（官方给的短语是 be ambitious，后面跟你要的完整清单）。这条在上一课的进阶技巧提过，落笔位置就在这里。
进阶技巧（可选）
让 AI 替你写说明书。 Claude Code 和 Codex 的 CLI 都有 /init，从代码库生成一份起步说明书，你的活儿主要是删——删到只剩代码里读不出的信息。Claude Code 还有 /doctor 建议删减、/context 确认文件真的加载了。
从说明书到技能。 同一套提示词反复用、同一个流程反复纠正？Codex 官方的经验法则：该把它打包成 skill 了。这是「沉淀」的下一级，等你的说明书稳定之后再考虑。
本课小结
✅ AI 编程提示词的完整链条你走通了：三要素落笔（位置 / 症状或目标 / 完成标准）→ 原件直递（@ 文件、贴截图、粘报错）→ 两轮法则纠偏（打断 → 回滚 → 清空重写）→ 长期规矩沉淀（AGENTS.md / CLAUDE.md）。
✅ 你知道了好提示词的判断标准不是长，是每句话都是 AI 读代码读不出的信息——两个问题一过，读得出来的全删。
✅ 你分清了信息和加压：魔法词不是开关，effort 档位才是；真规矩进说明书或强制机制，不靠「重要！」。
关键概念回顾：
| 概念 | 一句话 | 在哪深入 |
|---|---|---|
| 三要素 | 位置 / 症状或目标 / 完成标准 | 本页第 1 步 |
| 递原件 | @ 引用、贴截图、粘报错原文 | 本页第 2 步 |
| 两轮法则 | 纠偏两次失败 → 清空重写 | 本页第 3 步 |
| 项目说明书 | AGENTS.md / CLAUDE.md，每会话自动加载 | AGENTS.md 与 CLAUDE.md |
| 魔法词误区 | 加压用语不是信息 | 本页踩坑提醒 |
下一课预告
提示词写得再好，代码跑起来还是会报错——而报错原文恰恰是最值钱的下一条提示词材料。下一课：报错循环：把错误信息原样喂回去。
你会学到：
- 为什么报错要「原样」喂回去，转述会丢什么
- 怎么让 AI 自己走完「改—跑—读输出—再修」的循环，直到通过
- 修不动时怎么换思路，不在死胡同里打转