让 AI 编码遵守规格的 Prompt 模板

快速结论

在 prompt 里写明允许修改的文件范围、必须遵守的契约、必须提交的测试证据，以及禁止 AI 自行扩展的内容。这样 reviewer 才知道模型有没有越界。

你应该先看什么

• 先给 Scope，再给 Constraints，最后给 Output Format。
• 明确禁止模型“顺手重构”或改动无关模块。
• 要求输出测试证据、未解决问题和回滚注意项。

可直接复用的示例

Prompt Skeleton
Goal:
Allowed files:
Must preserve:
Required tests:
Do not change:
Return format: diff + risks + evidence

按任务类型的 Prompt 变体

基础模板是通用结构，但不同任务类型需要调整侧重点。以下三种变体覆盖了 AI 辅助编码中最常见的场景：新功能实现、重构和 Bug 修复。

# 变体 1：新功能实现

Goal: 实现 [功能描述]，行为与规格一致。
Spec reference: [规格文档链接或粘贴核心验收标准]
Allowed files: [列出允许新建或修改的文件路径]
Must preserve:
  - [不能改变的接口签名或行为]
  - [不能修改的现有测试]
Do not change: [明确禁止触碰的模块]
Required output:
  - 实现代码
  - 覆盖所有验收标准的测试（Given/When/Then 格式注释）
  - 你做出的任何假设列表

# 变体 2：重构（不改行为）

Goal: 重构 [模块]，提升 [具体指标：可读性/性能/可测试性]。
Behavior contract: 重构后所有现有测试必须通过，不得新增公开接口。
Allowed files: [仅限目标模块]
Must not change:
  - 公开方法签名
  - 返回类型
  - 错误码
Required output:
  - 重构后代码
  - 现有测试运行结果（截图或日志）
  - 你删除或合并的内容及理由

# 变体 3：Bug 修复

Goal: 修复 [bug 描述]，不引入回归。
Reproduction: [复现步骤或测试用例]
Root cause hypothesis: [你的初步判断，让模型对齐]
Allowed files: [尽量收窄到 bug 所在文件]
Do not change: [不相关的模块，即使你看到可以"顺手优化"的地方]
Required output:
  - 修复代码（最小变更）
  - 覆盖 bug 场景的回归测试
  - 如果根因与假设不符，说明实际根因

重构变体中最重要的约束是"行为契约"——明确告知模型，它的工作是移动代码，而不是改变行为。没有这条约束，模型往往会在重构时顺便调整逻辑，产生难以发现的语义变化。Bug 修复变体的关键是"最小变更"要求——没有这条，模型常会在修复 bug 的同时重构周边代码，使 diff 难以审查。

没有规格约束时 AI 会犯什么错误

AI 编码工具能力很强，但它在没有明确规格约束时会系统性地做出某些错误决策。了解这些模式，有助于判断哪些约束必须写进 prompt，哪些可以省略。

• 范围蔓延：模型会把它认为"显然需要"的逻辑一起实现。你要求实现用户注册，它会顺手加上邮件验证、限速逻辑和密码强度校验——这些可能不在本次范围内，也可能与已有实现冲突。解决方式：在 prompt 中明确写出 Non-goals，与规格中的非目标保持一致。
• 错误码猜测：没有明确指定时，模型倾向于返回最"常见"的 HTTP 错误码，而不是规格中定义的语义错误码。一个幂等写入失败应该返回 409 还是 422？没有规格，模型会猜——而且每次猜的可能不一样。解决方式：在 prompt 中粘贴错误码映射表。
• 忽略幂等要求：模型默认实现非幂等版本，因为这更简单。如果规格要求重复调用返回原始结果而不是重新执行，必须在 prompt 中明确写出幂等键机制和期望行为。
• 测试覆盖率虚高：模型生成的测试倾向于覆盖主流程，边界情况和失败路径经常被跳过。这会产生高覆盖率数字但低置信度的测试套件。解决方式：在 prompt 中要求"为每条验收标准写一个测试，包括失败路径"。
• 向后兼容性破坏：模型在修改已有接口时不会自动考虑现有消费者。它会改字段名、改返回结构，因为从局部看"更清晰"。解决方式：在 Must preserve 中明确列出字段名和响应结构约束。

这些不是模型的能力缺陷，而是信息缺失的后果——模型无法知道你的系统中哪些是已有契约、哪些是本次范围边界。规格就是传递这些信息的载体。

对照规格审查 AI 输出

AI 生成的代码需要用规格来审查，而不是用"看起来合理吗"来审查。以下是一套系统性的审查流程，确保 AI 输出在合并前符合规格要求。

• 逐条验收标准验证：取出规格中的每一条验收标准，在 diff 中找到对应的实现路径。找不到的，要么是漏实现，要么是实现逻辑分散在多处——两者都需要追问。不要用"大概覆盖了"代替逐条确认。
• 边界情况覆盖检查：规格中列出的每个 Edge Case，在测试文件中应该有对应的测试用例。如果测试文件中找不到，对应的边界情况就没有被验证。检查测试文件中的 Given/When/Then 注释是否与规格中的场景匹配。
• 错误路径完整性：检查实现中的每个 error return 或 throw，确认其对应的 HTTP 状态码和错误体格式与规格一致。常见问题：模型返回了正确的状态码，但错误体格式与规格不符，导致消费方解析失败。
• 契约影响检查：检查 diff 是否修改了现有公开接口的签名、响应字段或枚举值。如果有，核对规格的 Contract Impact 部分是否预期这个变更，并确认弃用窗口是否已设置。
• 禁止事项核对：检查 prompt 中 Do not change 列出的模块或字段是否在 diff 中出现。模型有时会在"修复"一个 bug 时顺带修改了被禁止触碰的部分。

这个审查流程的时间投入远低于联调阶段发现问题的修复成本。一次有规格作为基准的代码审查，通常比没有规格的审查快 3 倍——因为审查者知道"正确"是什么样子，而不是靠直觉判断。

落地建议

下次用 AI 写代码前，先加三个约束到 prompt 里：允许改哪些文件、哪些字段不能动、需要提交什么测试证据。加了这三条之后，review diff 会变得非常快。

相关文章

• 如何编写遵守规格的 AI 提示词
• 规格模板示例
• 如何编写可测试软件规格
• 什么是规格优先开发？