把生成代码的提示词存成轻量决策记录

AI 改完页面，PR 写一句「agent polish」就合并。半年后，有人追问地址表单为什么先校验邮编、再校验城市，代码能告诉你执行顺序，却未必能解释当时的取舍。

作者提出一个很轻的办法：把实际用于交付的提示词，作为微型架构决策记录（ADR）随代码保存。重点不是收集聊天记录，而是让后来的人和 agent 看见需求、约束与明确放弃的方案，少靠代码差异猜故事。

为什么看提交记录还不够

提交记录擅长回答「改了什么」，提示词则可能解释「为什么只改到这里」。

原文举了三个例子：

• 「只修改 ShippingForm.tsx」，解释了为什么 Checkout 里的问题没有一起处理。
• 「不增加依赖」，解释了为什么没有引入 zod。
• 「沿用现有错误文案键」，解释了为什么保留看起来别扭的 i18n 字符串。

这些约束往往不会完整体现在代码差异里。下一个 agent 如果只看到结果，可能把刻意保留的处理当成冗余，顺手「简化」，重新引入已经处理过的问题。

提示词记录最有用的部分，是那些无法从最终代码直接推断的边界。

作者强调必须保留提示词原文。把它概括成「改善体验」，会丢掉 agent 当时实际遵守或忽略的限制。不过，提示词记下的是要求，不代表实现一定满足了要求，仍然需要检查代码。

一份不到约 15 行的记录，怎么进入开发流程

作者把记录控制在约 15 行以内，包含目标、提示词原文、涉及文件、被否决的方案和后续事项。下面这份模板解决的是「该记什么」，并非一份已经填写完整的记录：

## Prompt ADR — ShippingForm zip-before-city (2026-11-05)

**Goal:** Require zip before city on blur for US addresses.
**Prompt (verbatim):** …
**Files touched:** `ShippingForm.tsx`, `shippingValidation.ts`
**Rejected alternatives:** city-first (matches old mock); shared schema with Checkout (too wide for this PR)
**Follow-ups:** none / link issue

重点看 Rejected alternatives：它留下的不只是选择结果，还有「为什么没选另一条路」。Prompt (verbatim) 后的省略号则必须在实际使用时替换成提示词原文。

存放位置也要固定。作者首选同一个 PR 中的 docs/prompt-adrs/YYYY-MM-DD-short-slug.md；也接受 PR 正文里的 ## Prompt used，但合并时要复制进文档。只存在聊天历史、agent transcript 或聊天截图里，都不符合他们的要求。

作者还把写记录放在改代码之前，用下面这段提示词约束工作顺序和范围：

You’re editing `ShippingForm` US address validation only.

Before you change code, write `docs/prompt-adrs/YYYY-MM-DD-shipping-zip-before-city.md` with:
- Goal (one sentence)
- This prompt pasted verbatim
- Files you expect to touch
- Alternatives you will NOT do in this PR

Then implement. Do not expand scope. If you need Checkout changes, stop and say so.

要看最后一句：需要改 Checkout 时先停下来说明，不能自动扩大范围。作者表示，如果 agent 跳过记录文件，他们会在审查 UI 之前退回 PR；只有「assisted by AI」勾选项，或者只有「improved UX」这样的泛化描述，也不接受。

我的判断

我赞成把「没做什么」留在仓库里。对表单校验、错误文案这类看似琐碎却容易反复修改的 UI 逻辑，这比一句「AI 辅助完成」更能帮助维护。

但原文提供的是作者的工作经验，没有给出缺陷率、审查耗时或返工次数的对照数据。「花两分钟」也是作者的行动建议，不能当成经过验证的平均成本。

它还有两个前提。第一，后续维护者和 agent 得能找到并阅读记录，PR 链接与固定目录才有价值。第二，提示词得覆盖真正影响交付的约束。如果过程中多次追加要求，只保存开工时的一条提示词，仍然会漏信息；原文没有说明这种情况如何整理。

相比完整 ADR，这种做法更容易随小改动执行；相比认真填写的 PR 描述，它的增量主要是保留提示词原文，并让记录随仓库长期存在。它适合补充决策背景，但不能单凭提示词判断实际行为。

能拿来做什么

• 下一次合并 agent 修改的表单时，附上一份短记录，写清校验触发时机、适用地址范围和提示词原文，让后来的人能追溯行为来源。
• 在 PR 中明确写出未采用的方案，例如这次不与 Checkout 共用校验 schema，并说明范围原因，减少后续重复讨论。
• 如果团队已有 PR 模板，可以先加入 ## Prompt used，约定合并时归档到 docs/prompt-adrs/，同时在 PR 中保留路径。
• 审查 AI 编程结果时，把提示词约束与实际改动逐项核对，尤其检查文件范围、新增依赖和错误文案键是否符合要求。