提示词版本管理：把Prompt当代码管，团队协作的必修课

一个熟悉的场景

线上客服 Agent 突然开始胡说。排查两小时后发现：三天前某位同事在飞书文档里”优化了一下语气”，把”不确定时请说明不知道”删掉了。没有 diff，没有审阅，没有回滚点。

提示词已经是生产代码了，但多数团队还在用管理会议纪要的方式管理它。这篇给一套能落地的方案。

第一步：把 Prompt 从文档搬到仓库

推荐的目录结构：

prompts/
  customer-service/
    system.md            # 主系统提示
    policies/
      refund.md          # 可组合的策略片段
      escalation.md
    examples/
      few-shot.jsonl
    manifest.yaml        # 模型、温度、版本元数据
  sales-assistant/
    ...

关键点：系统提示用 Markdown，少用代码字符串。Markdown 可读、可 diff、方便产品经理直接改；代码里只做模板变量的插值。

manifest.yaml 记录不可分割的运行时参数：

version: 2.3.1
model: gpt-5-mini
temperature: 0.3
max_tokens: 1200
owner: wanglin
eval_set: customer-service-v4
changelog: "收紧退款承诺边界，禁止主动许诺补偿"

第二步：版本号规则要能表达”风险等级”

用三段式，但含义要和代码版本略有不同：

• 主版本号：改变行为边界（新能力、新拒绝规则、新增工具权限）→ 必须全量评测 + 灰度
• 次版本号：调整表达方式（语气、格式、示例增删）→ 抽样评测 + A/B
• 修订号：错别字、字段名拼写、无行为影响的整理 → 直接上线

这条规则的价值在于：让”要不要跑评测”这件事不用讨论。看到 2.x → 3.0，自动触发完整回归。

第三步：diff 审阅，关注的不是”改了什么”而是”删了什么”

代码评审里新增代码更受关注，提示词评审恰好相反——删除的约束是最危险的。

建议在 PR 模板里固定三问：

1. 删除了哪些约束？为什么？
2. 本次改动对应哪条线上问题或需求？
3. 关联的评测集版本与通过率是多少？

第二问能挡掉大量”我觉得这样更好”的随意改动。

第四步：评测集是版本管理的另一半

没有评测集的版本管理只是”存档”，不是”管理”。最低要求：

• 每个 Prompt 有对应的评测集，覆盖正常、边界、对抗三类用例
• 每次次版本号以上的改动，跑评测并记录通过率
• 评测集本身也要版本化——评测集变了，历史通过率就不可比

一个常见陷阱：团队改了 Prompt 也改了评测集，然后说”通过率提升了”。规范做法是评测集升级必须单独 PR，且用旧评测集同时跑一遍新旧 Prompt，做一次交叉验证。

第五步：灰度与回滚

线上不要直接替换。分三层：

阶段	流量	观察指标	时长
影子	10%，双跑不发	输出差异率、成本	1–2 天
小流量	5% 真实流量	满意度、任务完成率、转人工率	3 天
全量	100%	同上游 + 兜底告警	持续

回滚必须是配置项，不是发版。Prompt 版本号存在配置中心，回滚只需改一行配置并清缓存，10 秒内生效。如果回滚需要走 CI/CD 发版，那你的 Prompt 管理还没做对。

第六步：可观测性

每条线上请求的日志里必须带上：prompt_version、model、temperature。否则出了问题你连”是哪个版本”都查不出来。

建议在管理后台做一个”版本对比看板”：同一天的样本量、平均长度、拒绝率、转人工率按版本并列。这是发现”新版本更啰嗦但成功率没提升”的唯一办法。

小结

把 Prompt 当代码管，不是增加流程负担，而是把隐性的口头约定变成显性的规则。从最小可用开始：先建仓库 + 版本号 + 回滚配置，这三件事能解决 80% 的事故；评测集和 diff 流程可以第二个月再补。