这篇讲什么
多数”AI 写出垃圾代码”的故事其实是”我写了垃圾 prompt”的故事。让 AI 写代码时，杠杆率最高的一步就是结构化：目标、约束、验收、交接规则。四块少一块，模型就用假设填空——通常很通用，有时是错的，偶尔是灾难。这篇给你模板、一个走完的例子、以及一旦你坚持结构化就会消失的失败模式。
这篇适合谁看
任何让 AI 写代码的人：Cursor、Claude Code、Codex、顺手用的 ChatGPT、agent 和补全都算。AI 输出”看起来还行”但 review 或上线时翻车的工程师尤其受益。
什么时候适合用
任何非琐碎的编程 prompt 之前——新功能、重构、跨文件 bug 修复。真·一行小改或补全跳过，结构化在那种场景下是过度工程。
开始前准备
- 想清”应该动哪些文件、不该动哪些”。范围模糊比目标模糊毁掉更多 PR。
- 心里有一条具体验收测试。写不出来就说明你也不知道”完成”长啥样。
- 知道项目约定：命名、错误处理、async 风格。不给 AI 就会猜。
- 决定要”先 plan 再 code”还是直接出 code。先 plan 多花 30 秒，目标模糊时省 30 分钟。
具体步骤
- 目标：一句话、具体、可衡量范围。
- 差：“优化登录流。”
- 好：“给
/api/login加限流：单 IP 15 分钟内 5 次以上失败返回 429。”
- 约束：语言、框架、要动的文件、不许动的文件、要镜像的现有模式。
- “用
src/middleware/rate-limit.ts里现有的 helper。不许加新依赖。不要碰其他 API 路由。”
- “用
- 验收：一个测试或一种可观察行为证明它对。
- “
src/api/__tests__/login.test.ts新增单测：15 分钟内第 6 次失败请求返回 429，错误格式与现有 auth.ts 一致。”
- “
- 交接规则：给 AI 多少自治权。
- “先 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：列要动的文件和测试名。批准后再写代码。这条 prompt 在任何现代编程 agent 上都能产出能用的 plan。同一套骨架对重构、bug 修复、依赖升级都适用。
第一次实操怎么跑
- 选一个你平时一句话就描述完的编程任务。先写那个一句话版本。
- 用四块结构重写。别忍着想简化——结构化的回报在”齐”。
- 分别在两次对话里发给同一个编程 agent。对比输出。
- 看差距。通常结构化版本能上线，一句话版本要重写。
完成后检查
- AI 遵守每条约束了吗？diff 一下涉及文件；约束外的都是 bug，不管那个改动多聪明。
- 验收测试存在且通过吗？“看着对”不能替代”测试通过”。
- AI 加了你没要的东西吗？多送的”贴心”功能是常见失败模式，要回滚。
- 读代码。即便结构化了，AI 输出也是”可审的初稿”，不是”可合的最终版”。
怎么复用这套流程
- 四块模板存片段。同模板、新内容。
- 维护
AGENTS.md或CONTRIBUTING.md写项目约定——AI 会读进上下文。 - 干净 PR 的 prompt 和翻车的 prompt 都记下来。规律一周内浮现。
- 季度复测模板。模型行为会变，春天能用的秋天可能要调。
建议的操作流程
目标（一句话、具体）+ 约束（动/不动、要镜像的模式）+ 验收（一个测试或行为）+ 交接（先 plan 还是直接出）→ 执行 → 合并前对照四块复核。
容易踩的坑
- 一句话 prompt。“加限流”每次写出来的限流器都不一样。
- 没验收。没有测试，“完成”会漂到”模型觉得差不多”。
- 缺约束。AI 会自己挑约定；有时挑错，常常和你代码库不一致。
- 不写交接规则。先 plan 能避免 80% 的”AI 写了 200 行我得全扔”。
- 复用昨天的 prompt 不更新约束。代码库会漂，prompt 也得跟着漂。
- 把结构化当官僚主义。差距正出在结构上；简洁是另一种能力，不和结构冲突。
FAQ
- 补全式助手也适用？: 部分适用。补全偏好简短。四块结构在 Composer、Cursor Agent、Claude Code、Codex、Aider 上都用。
- 不知道约束怎么办？: 让 AI 先提，你批准或改。“先提 3 条约束、批准后再写代码”是合法的第一条消息。
- prompt 该多长？: 典型任务 100-300 字。约束堆起来更长；过短反而可疑。
- 信任的模型能跳过交接规则吗？: 简单任务可以。跨文件或要上线的，一律保留”先 plan”。