AI 编码治理：用规格驱动的 Prompt 设立边界

用 spec-driven prompts 治理 AI 辅助编程：提示词必须包含什么、AI 必须遵守哪些边界，以及让“这是 AI 写的”变成可核验声明的审计链。

发布于 2026-03-10 · ✓ 已更新 2026-05-06 · 阅读约 8 分钟 · 作者：Spec Coding 编辑部 · 审校：编辑与事实核查政策

现场笔记：治理发生在模型运行之前

最贵的错误，是等到 PR 评审时才问“AI 本来该不该碰这个流程”。账单、权限、迁移和 API 契约这类改动，治理决策应该在生成之前就写进提示词包。

AI 工作分类：
风险：高
原因：触碰退款状态和 webhook 重试行为
允许输出：实现 diff 加测试
必须证据：replay 测试、重复防护测试、回滚说明
人类责任人：账单技术负责人

治理从提示词开始的地方开始

大多数 AI 编程治理的争论都卡在错误的层面上。大家争论的是模型能不能被信任。那是第二个问题。第一个问题是：团队能不能用书面形式说清楚，到底要求模型做什么。如果我们连这份工件都拿不出来，后面所有环节都算不上治理，而是带着合并按钮的“凭感觉”。人类争论的 spec，必须和模型读到的是同一份 spec。否则就是传话游戏，而审计链止步于某一位工程师的显示器。

我实际在用的三层提示词结构

每一次 AI 辅助的改动都会经过一份三层提示词。每一层都是独立的工件，都有各自的 owner。

• System 角色层。助手是谁、语言和框架约定、仓库地图、commit 格式。很少改动。
• Feature spec 层。当前这个 story：用 Given/When/Then 写的验收标准、涉及的数据模型、对外暴露的 API。由产品负责人签字。
• Boundaries 层。明确的“不要做”清单：src/api/orders/ 以外的文件不能动、不新增依赖、schema 冻结、提交 diff 之前跑一遍测试套件。

只要缺了任何一层，产出就不具备可评审性。它只是一份草稿，还有人欠我一份 spec。

验收标准必须进提示词

让 AI 编程从新奇玩意儿变成我信得过的东西，关键招数就是把验收标准原封不动地粘进提示词。不是意译，而是产品负责人批准过的那份 Given/When/Then 原文。模型先依照这些标准写测试，再去实现，代码评审的问题就从“这段代码写得好不好”变成“测试是不是对得上业务签字的 spec”。

Feature: Add POST /orders/{id}/refund endpoint
  Given an authenticated admin user and an order in state "paid"
  When they POST /orders/{id}/refund with a valid amount
  Then the order transitions to state "refunded"
  And a refund event is emitted to the billing queue
  And the response is 200 with the refunded order payload

  Given an order in state "shipped"
  When an admin attempts a refund
  Then the API returns 409 with code "order_not_refundable"
  And no billing event is emitted

当这段内容放进提示词之后，spec 违规就不再是评审的口味问题，而是一份 diff：测试文件要么表达了这些用例，要么没有。

一份新增端点的真实提示词模板

下面是我用来新增一个 API 端点的模板结构。它放在 prompts/feature.new-endpoint.v4.md，PR 会链到这份文件的具体版本。

SYSTEM
You are a senior engineer on the Orders service.
Stack: TypeScript, Fastify, Drizzle, Vitest.
Repo map: see prompts/context/repo-map.md.
Commit style: Conventional Commits.

FEATURE SPEC
{{ inject: specs/orders/refund-endpoint.md@sha=ab12cd }}

BOUNDARIES
- Only modify files under src/api/orders/** and tests/api/orders/**.
- Do not add dependencies. Use existing utilities in src/lib/.
- Do not change database schema or migrations.
- Write Vitest cases for every Given/When/Then in the spec before implementation.
- Run `pnpm test --filter orders` and paste the output in your response.
- If the spec is ambiguous, stop and ask. Do not guess.

关键就在 inject 这一条指令。spec 是按内容寻址的：只要 spec 一变，提示词的哈希就变，PR 上就能看到模型当时看到的 spec 是哪一版。

提示词就是代码

那些把提示词当作 Notion 页面里“口口相传”的团队，最后都会陷入混乱。我把提示词放进仓库里，挨着它产出的代码一起放。它们有 PR、有 diff，由签字通过 feature spec 的那些人审批。当有人放宽了某条边界，这次编辑会留下作者、日期和评审人。这样就能杜绝提示词漂移——那种没人署名的修改，会把一份有纪律的提示词一点点改成互相矛盾的一团乱麻。

审计链必须是真的链条，不是口头声明

“这是 AI 写的”本身没有任何意义，除非评审人能重建 AI 当时被告知了什么。每一个 AI 辅助的 PR 都要带上四个链接：提示词版本、spec 版本、会话日志、模型自己报告的那一次测试运行。任何一个缺失，PR 就打回。一年之后，当某次事故追溯到这个端点，有人打开 PR，就能准确看到当时生效的是哪一份 spec。

我在 AI 产出的 PR 上用的评审清单

• 测试是否覆盖了每一条 Given/When/Then，还是模型跳过了其中某一条？
• diff 是不是待在边界清单之内，有没有改动被告知不要动的文件？
• 它有没有引入提示词未授权的依赖、环境变量或配置？
• diff 里有没有“看起来合理”的方案，是在解决 spec 根本没描述过的问题？
• 如果模型提过澄清性问题，答案是不是留在了会话日志里？

最后这一条比字面上重要得多。如果有人在聊天里回答了却没更新 spec，那 spec 此刻就是在撒谎，谎报审批过的内容。

真正会咬人的几种失败模式

• 提示词漂移。工程师在过程中改提示词，却从不把改动合回去。规范版本的提示词和实际在用的提示词就此分道扬镳。
• Spec 漂移。产品更新了 spec，但提示词注入的还是旧版。模型按一份没人同意的 spec 写出了“正确”的代码。
• 评审疲劳。AI PR 来的速度比人类能读完的速度还快。评审人开始盖橡皮图章。一份被橡皮图章放行的 AI PR，比一份被橡皮图章放行的人类 PR 还糟糕，因为评审人是唯一剩下的治理环节。

提示词漂移靠版本控制解决。Spec 漂移靠按内容哈希注入 spec 来解决——spec 一变，提示词就必须显式升版。评审疲劳更难。我会限制每位评审人每天能处理的 AI PR 数量。吞吐量要上去，就加评审人，否则就少出货。

我盯的几个指标和一小时规则

四个数字能告诉我这套流程是否健康：AI 产出的 PR 在不经人类改代码的情况下合并的比例、评审后的返工率、spec 违规流到生产 vs 在评审中被拦下的比例，以及 spec 批准到合并的中位时长。

还有一条规则，我会发给每一位工程师：如果一小时之内 AI 依照 spec 还交不出一个能通过测试的实现，停下。问题几乎一定出在 spec 上。不是标准互相矛盾、就是边界把一个必需的文件排除在外、再不然就是漏了某个用例。这一小时不是给模型的性能预算，而是 spec 的烟雾报警器。修 spec，升哈希，重新生成提示词。那些硬撑过一小时、试图和模型讨价还价的工程师，治理其实已经输了。

我希望你带走的那一点

AI 辅助编程之所以能被治理，是因为你治理了输入。想要什么样的代码，就怎么写 spec。把 spec 带着内容哈希放进提示词。用明确的禁止条款写边界。给提示词打版本。每一个 PR 都链到确切的 spec、提示词和对话记录。按 spec 做评审。如果你重建不出 AI 当时被告知了什么，你就没有 AI 治理。你只有 AI。

落地补丁：AI PR 上必须留下的四个链接

治理不是“我们会认真 review”。那句话在事故复盘里没有用。能用的是四个链接：规格版本、提示词版本、模型会话、测试证据。少一个，reviewer 就没法重建这段代码为什么会出现。

Required PR evidence:
- spec: docs/specs/refund-v2.md@8f31c2
- prompt: prompts/implementation/refund-v2.md@19a0bd
- session: ai-runs/2026-04-28/refund-v2-claude-sonnet.json
- tests: pnpm test --filter refund-v2, output attached
- reviewer: API owner + QA owner both checked acceptance criteria

边界是：不要把每次 autocomplete 都纳入治理。只要 AI 参与了行为设计、测试生成、迁移或跨文件实现，就要留下这条链。纯补全变量名不需要。

最后再看权限和数据

治理清单里我会单独留两行给权限和数据：这次代码有没有改变用户能看到的字段、状态或 API 响应？有没有写入新表、迁移旧数据、修改 owner 或审计事件？这些问题很土，但它们比“AI 是否可靠”更容易被 reviewer 验证。

还有一个简单判断：如果 PR 改了 API 字段、数据库表、权限状态、测试代码或回滚路径，就不能只靠口头说明。把 owner、证据和边界写进 PR 描述，reviewer 才能按事实判断，而不是按模型回答的语气判断。

可复制产物：AI 编码评审包

在 AI 生成 diff 进入代码评审前使用。它把提示词范围、允许变更和证据要求合并成一个可审查产物。

AI 编码评审包：AI 编码治理：用规格驱动的 Prompt 设立边界

本次要做的决策：
- 确认 AI 只在批准范围内生成变更，并为每条验收标准提供证据。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

AI 边界：生成变更必须留在书面范围内，每条验收标准都要能找到证据。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

二次审阅记录：治理要减少评审雾气

这次把页面重点压到具体门禁上。治理如果只是没人看的政策文档，就会失败。它有效的时候，评审者在逐行读代码之前，就能判断生成 diff 是否被允许。

门禁检查：
- 风险等级是否写明？
- 人类责任人是否写明？
- 允许修改的文件或模块是否写明？
- 生成前是否写明必须证据？
- 紧急修复有没有例外路径？

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。