一句话总结
能产出”可直接合并”代码的 prompt 有四块：目标（一句话、具体）、约束（要动的文件、不许动的文件、要镜像的模式，以及明确”不要做什么”）、验收（一条能跑、能证明它对的测试或可观察行为）、交接（给 agent 多少自治权）。少一块，模型就用假设填空。再配上仓库里的 AGENTS.md/CLAUDE.md 和先 plan 模式，同一个任务——agent 在没有上下文时大约只有三分之一能做对——就能稳定地落地。
为什么结构比”会写 prompt”更重要
多数”AI 写出垃圾代码”的故事，其实是”我写了垃圾 prompt”的故事。瓶颈不在模型。截至 2026 年 6 月，Claude Opus 4.7 在 SWE-bench Verified 上拿 87.6%，GPT-5.5 在 Terminal-Bench 2.0 上拿 82.7%——这些模型完全写得出代码。它们做不到的，是猜出你哪些文件碰不得、你用的是哪种错误格式、你们团队所谓的”完成”是什么意思。
2025 年一项针对 agent 编程任务的研究发现：没有项目上下文文件时，agent 大约只有 30% 的任务能做对；同样的任务，配上写得好的上下文文件，正确率升到约 90%。差距不在模型能力，而在你递给模型的东西的结构。
这篇适合任何让 agent 写代码的人——Cursor、Claude Code、Codex，或顺手用的 ChatGPT。任何非琐碎改动之前都该掏出完整模板：新功能、重构、跨多文件的 bug 修复。真·一行小改就跳过，结构化在那种场景下是过度工程。
四块结构
1. 目标——一句具体的话
一句话、具体、范围可衡量。这是”做什么”，不容含糊。
- 模糊：“优化登录流。”
- 具体：“给
/api/login加限流：单 IP 15 分钟内 5 次以上失败返回 HTTP 429。“
2. 约束——包含”不要做什么”
语言、框架、要动的文件、不许动的文件、要镜像的现有模式——再加上明确的反向约束。告诉模型”不要做什么”能一次砍掉一整类低质量输出，这也是 2026 年的 prompt 指南把反向约束看得和正向约束同等重要的原因。
- “用
src/middleware/rate-limit.ts里现有的 helper。不许加新依赖。不要碰其他 API 路由。错误格式跟auth.ts一致。“
3. 验收——一个测试或行为
一个测试、或一种可观察行为，能证明它对。如果你连验收点都说不出来，那你还不知道”完成”长啥样，模型自然也不知道。
- “
src/api/__tests__/login.test.ts新增单测：15 分钟内第 6 次失败请求返回 429，错误 JSON 与现行标准一致；现有 login 测试继续通过。“
4. 交接——给多少自治权
在你 review 之前，agent 能放多长的绳。
- “先 plan：列你打算改的文件和测试名。批准前别写代码。“
一个可以直接粘的例子
目标：
给 /api/login 加限流：单 IP 15 分钟内 5 次以上失败返回 HTTP 429。
约束：
- 用 src/middleware/rate-limit.ts；不要加新依赖。
- 不要碰其他 API 路由。
- 错误响应格式跟现有 auth.ts 一致。
- 只算失败请求；成功登录重置计数。
验收：
- src/api/__tests__/login.test.ts 新单测：15 分钟内第 6 次失败
返回 429，错误 JSON 与现行标准一致。
- 现有 login 测试继续通过。
- npm test 期间无 console warning。
交接：
先 plan：列要动的文件和测试名。批准后再写代码。这套骨架对重构、bug 修复、依赖升级都适用——换内容，留四块。
用”先 plan 模式”，不只是一句”先 plan”
当工具本身强制执行交接规则时，这一块才最有用。截至 2026 年 6 月：
- Claude Code plan 模式：按两下
Shift+Tab进入（第一下切到自动接受，第二下进 plan 模式），或用/plan命令。plan 模式下 agent 会读文件、写出一份编号的计划——点名要改的文件、迁移或新增环境变量这类副作用、以及它看到的风险——在你批准前不动任何东西。 - Cursor：Composer 在执行前会先给出一份改动计划；你可以审、可以来回改，满意了再放行。
先 plan 大约花 30 秒，却能挡掉最常见的浪费：agent 写了 200 行你得全扔。2026 年那些产出最干净 PR 的团队，靠的不是更聪明的 prompt，而是把”做计划”当成一等公民。
把常驻约束搬进 AGENTS.md
任何你会在每条 prompt 里重复的东西——命名约定、错误处理、测试命令、你代码库用的 async 风格——都该放进仓库的上下文文件，而不是塞进 prompt。
AGENTS.md 在 2026 年成了做这件事的开放标准。OpenAI 于 2025 年 8 月提出，2025 年 12 月捐给了 Linux 基金会的 Agentic AI Foundation；截至 2026 年 6 月，已有 6 万多个仓库在用，并被 Codex、Cursor、GitHub Copilot、Gemini CLI、Aider、Zed、Warp 等原生读取。Claude Code 读的是 CLAUDE.md（可以用 import 指向 AGENTS.md，或两个保持同步）。当 agent 反复犯同一个错时，去改这个文件，而不是每次会话重新解释一遍——这个反馈飞轮才是真正的效率来源。
prompt 长度：瞄准 150–300 字
典型任务，有效区间大约 150–300 字（英文按词计，中文相应更紧）。约束堆起来可以更长；短得反常，多半是你漏了一块。别想把整个项目塞进一条 prompt——2026 年的指南把这叫”指令诅咒”：要求太多，模型会在一堆指令里丢掉焦点。一次只给一个聚焦的任务，常驻规则交给上下文文件。
约束 vs 直觉：对”做什么”死板，对”怎么做”松手
把 prompt 分成两种语气。规格——也就是”做什么”——不容含糊，把期望结果说死。设计直觉——也就是”怎么做”——用非强制的措辞：当成建议而非命令，让模型在你其实没有硬性要求的地方自行判断。把两者搞混（把软偏好写成硬规则，或把硬要求留得含糊），正是结构化 prompt 仍会翻车的地方。
审查输出
结构化让输出”可审”，不等于”可合”。上线前：
- diff 每一个涉及文件。 约束之外的改动都是 bug，不管它看起来多聪明。
- 跑验收测试。 “看着对”不是”测试通过”。
- 回滚没要的额外功能。 你没要、它”贴心”加上的，是常见失败模式。
- 读代码。 即便结构化了，AI 输出也只是初稿。
容易踩的坑
| 坑 | 会发生什么 | 怎么办 |
|---|---|---|
| 一句话 prompt | ”加限流”每次写出来的限流器都不一样 | 四块都写齐 |
| 没验收 | ”完成”漂到”模型觉得差不多” | 写明一个测试或行为 |
| 缺约束 | agent 自己挑约定，常和你代码库不一致 | 列出动/不动的文件和要镜像的模式 |
| 不写交接规则 | agent 写了几百行你得扔掉 | 强制走先 plan 模式 |
| 复用过期 prompt | 代码库会漂，老约束指向已挪走的文件 | 每个任务更新约束 |
| 常驻规则塞进每条 prompt | prompt 臃肿，错误反复 | 搬进 AGENTS.md/CLAUDE.md |
FAQ
补全式助手也适用吗？ 部分适用。Tab 式补全偏好简短、吃光标上下文。完整四块结构用在 agent 模式上——Cursor Composer、Claude Code、Codex、Aider——也就是模型会跨文件做计划和改动的场景。
还不知道约束怎么办？ 让 agent 先提。“先提 3 条约束、批准后再写代码”是合法的第一条消息；它给出来后你批准或修改，再往下走。
写 AGENTS.md 还是 CLAUDE.md？
如果团队用 Codex、Cursor、Copilot 或 Gemini CLI，写 AGENTS.md——它是跨工具标准。Claude Code 读 CLAUDE.md，所以留一个、或让其中一个 import 另一个。内容是一样的：构建命令、测试命令、约定、以及不要做什么。
信任的模型能跳过先 plan 吗？ 真·简单的单文件任务，可以。但凡跨文件或要上线，不管模型多强都保留先 plan——代价是 30 秒，省下的是一整个被扔掉的 PR。
prompt 该多长？ 典型任务大约 150–300 字。短太多，多半漏了一块；长太多，把常驻规则挪进上下文文件。