把提示词当代码管：vibe 项目的 Prompt 版本管理实战

一、你的提示词已经是生产代码了，只是没人把它当代码管

打开一个典型的 vibe 项目，提示词通常躺在三个地方：硬编码在某个 chat.ts 的字符串里、躺在某个管理后台的文本框里、或者散在协作文档的某一段。三处有一个共同点：改了就生效，生效了没人知道改了什么，出了问题没人能说清线上跑的到底是哪个版本。

提示词有三重身份。第一，它是代码：它直接决定程序的行为，改一个词就能让输出从 JSON 变成散文，威力不亚于改一行核心逻辑。第二，它是配置：线上文本框一点就生效，绕过了你精心搭建的 CI/CD。第三，它是资产：一个调了三个月、踩过几十个坑的分类 prompt，是团队真正的 know-how，丢了就得重交学费。

三重身份意味着它配得上三重管理：像代码一样进 git、像配置一样可回滚、像资产一样有负责人和变更记录。做不到这三点，你的 prompt 就是薛定谔的代码——跑着，但没人知道它到底是什么版本。

判断标准很简单：如果线上 prompt 出了问题，你能在 10 分钟内说出「是哪个版本、谁改的、改了什么、怎么回滚」，这套管理就是合格的。说不出来，就得建。

二、先给提示词建个家：prompts/ 目录与命名规范

第一步是把提示词从代码字符串里搬出来。原则：一个 prompt 一个文件，全部收拢到仓库根目录的 prompts/ 下。调用方不再手写提示词字符串，而是按 ID 从文件加载。

推荐的目录结构：

prompts/
  system/        # 系统提示词：角色、分类器、审核
    classifier.md
    summarizer.md
    moderator.md
  user/          # 用户提示词模板：带变量的
    review-rubric.md
    reply-draft.md
  evals/         # 每个 prompt 的黄金测试集
    classifier-golden-200.jsonl
  registry.json  # 注册表：id → 当前版本 → 文件
  CHANGELOG.md  # 人话写的变更记录

命名规范只有三条：按场景分目录（system/user 按用途，场景多了再按业务拆）；文件名用小写短横线，一眼能看出它是干什么的；版本号不进文件名，版本信息写在文件头的元数据里。文件名带版本（比如 classifier-v2.md）是灾难的开始：调用方引用的是旧文件名还是新文件？两个文件谁最新？三个月后你自己都分不清。

registry.json 是调用方唯一的入口：

{
  "classifier": {
    "current": "1.3.0",
    "file": "system/classifier.md",
    "status": "active"
  },
  "summarizer": {
    "current": "2.0.1",
    "file": "system/summarizer.md",
    "status": "active"
  }
}

业务代码里只认 classifier 这个 ID，加载哪个版本由注册表决定。这样回滚的时候你改的不是业务代码，而是一行配置——这就是后面「一键回滚」的基础。

三、元数据头：每个 prompt 的身份证

每个 prompt 文件的开头，用 YAML frontmatter 写一张「身份证」：

---
id: classifier
version: 1.3.0
status: active    # active | canary | deprecated
owner: lee
updated: 2026-10-06
model: gpt-4o-mini
temperature: 0.2
change: 「请严格输出 JSON」改为「只输出 JSON，不要解释」，修复解析失败
evals: evals/classifier-golden-200.jsonl
baseline:
  accuracy: 0.87
  parse_failure_rate: 0.02
  latency_p95_ms: 1200
---

你是一个客服工单分类器。只输出 JSON，不要解释……

字段一个都别省，每个都有用：id 是调用方引用的唯一标识；version 遵循语义化版本（下一节细讲）；status 标记这个版本是在线、灰度中还是已废弃；owner 是出问题时第一个该被 @ 的人；model 和 temperature 写死调用参数，避免「prompt 没变但模型换了」这种隐性变更；change 用一句话写清这次改了什么、为什么改——这是给三个月后的自己看的；evals 指向它的黄金测试集；baseline 记录这个版本发布时的指标基线。

baseline 是最容易被忽略、关键时刻最救命的字段。回滚的时候你不需要重新跑一遍测试，直接看文件头：「好」的标准是准确率 0.87、解析失败率 0.02——回滚后对照这个数，达标了就是真恢复了。

四、语义化版本：给 prompt 的改动分级

直接照搬 semver，三段版本号，每段含义固定：

• major（X.0.0）：行为变更。改输出格式、增删约束条件、换角色定位、换模型。例子：分类器从「输出 JSON」改成「输出 Markdown 表格」。必须走 PR + 全量 eval + 灰度。
• minor（x.Y.0）：措辞优化。同义改写、加 few-shot 例子、调段落顺序，不改变输出契约。例子：把「请分类」改成「请将工单分到以下四类」。走 PR + eval 对比，可以小流量灰度。
• patch（x.y.Z）：typo 和标点。改错别字、补标点、调注释，不碰任何实质措辞。例子：把「帐号」改成「账号」。直接合并，但也要 commit 留记录。

升级流程是反过来的：先判断改动属于哪一级，再定版本号，最后定发布流程。顺序不能反——先定「我想发个 minor」再去套改动，是给自己挖坑。

最常见的作死操作，是把行为变更标成 patch。「就加了一句话」——第八节的真实教训里，这句话让准确率掉了 12 个点，而它当时被标成了 patch。记住：版本号的诚实度，决定了回滚时你对 diff 的信任度。标错版本，等于在事故现场给你自己指了一条错路。

五、变更走 PR：禁止随手改线上 prompt

立一条铁律：任何 prompt 改动都走分支 + PR，直接改线上文本框等同于直接改生产数据库。没有例外通道，只有「救火后 24 小时内补 PR」的例外流程——先灭火可以，但火怎么灭的必须回填记录，否则下次救火的人两眼一抹黑。

一个合格的 prompt PR 长这样：

1. 分支名带版本：prompts/classifier-1.3.0，从分支名就知道改的是哪个 prompt、目标版本是多少。
2. PR 描述写清三件事：改了什么（diff 链接）、为什么改（背景和动机）、预期影响（输出契约变没变、影响哪些调用方）。
3. 评审人看三张清单：输出契约有没有变（格式、字段、约束）；eval 基线对比（新版本在黄金集上的分数）；有没有破坏其他调用方（搜一下这个 id 被哪里引用）。
4. 合并前跑 eval：CI 里对新旧两个版本跑黄金测试集，分数贴在 PR 里，跌超阈值自动打回。
5. 合并后更新注册表和 CHANGELOG：registry.json 里的版本号、CHANGELOG.md 里的人话记录，两处都更新才算完。

评审 prompt 和评审代码有一个本质区别：代码评审能看出逻辑对错，prompt 评审看不出效果好坏。「这句话读起来更顺了」不等于「模型表现更好了」。所以 PR 流程里 eval 结果的权重必须高于评审人的语感——语感投票，数据一票否决。

六、A/B 并跑与一键回滚

prompt 的效果没法靠「读一遍」判断，只能靠线上小流量验证。新版本先切 10% 流量跑 24 小时，指标不跌再全量。这套东西不需要自研，注册表里加两行配置就行：

{
  "classifier": {
    "stable": "1.2.0",
    "canary": "1.3.0",
    "traffic": { "stable": 0.9, "canary": 0.1 }
  }
}

调用方按 ID 查注册表，按权重随机选版本，并把实际命中的版本号打进日志。日志里有版本号，事故复盘时才能回答「出问题的请求到底跑的是哪个版本」——没有这条日志，A/B 就是白做。

回滚清单，打印出来贴墙上：

1. 告警触发或指标跌破阈值，第一步是冻结 canary 流量，不是先找原因。止血优先于诊断。
2. 把注册表里 canary 的流量权重改成 0，stable 回到 1.0。这是一次配置变更，不需要重新部署。
3. 确认线上命中的版本号全部回到 stable，观察 10 分钟指标曲线。
4. 把出问题的版本在注册表里标 deprecated，frontmatter 的 status 同步改掉，防止有人手滑再切回去。
5. 写事故记录：版本号、跌了多少、什么时候发现的、初步猜测的原因。猜测允许写「待查」，但数字必须写。

回滚演练每季度做一次：随机挑一个 prompt，模拟 canary 翻车走完这五步，计时。目标是从告警到恢复 10 分钟以内。演练时才发现注册表改完要 5 分钟才生效，总比线上事故时才发现强。

七、git 是底线，evals 是尺子

git 能解决的问题：谁改的、什么时候改的、改了什么、一键回到任意历史版本。这是底线，没有商量余地。prompt 文件进 git 仓库，和业务代码同仓库，git log -- prompts/system/classifier.md 应该能拉出它完整的变更史。

但 git 解决不了一个问题：「感觉变差了」。上周分类还挺准，这周好像有点怪——这种感觉需要变成数字，否则 PR 评审就是玄学评审。evals 就是干这个的。

做法不复杂：攒 50 到 200 条真实输入和期望输出，存成 JSONL，这就是黄金测试集。每次改 prompt，在新旧两个版本上各跑一遍，对比分数：

def eval_prompt(version, golden):
    correct, failed = 0, 0
    for case in golden:
        out = call_llm(load_prompt("classifier", version), case["input"])
        try:
            pred = json.loads(out)["category"]
        except Exception:
            failed += 1
            continue
        correct += (pred == case["expected"])
    return {
        "accuracy": correct / len(golden),
        "parse_failure_rate": failed / len(golden),
  }

old = eval_prompt("1.2.0", golden)
new = eval_prompt("1.3.0", golden)
assert new["accuracy"] >= old["accuracy"] - 0.03, "准确率跌超 3 个点，打回"

盯四个指标就够了：准确率（任务本身做得对不对）、解析失败率（输出契约守没守住，这是 prompt 事故里最常见的死法）、延迟 p95（prompt 变长通常意味着变慢变贵）、单次调用成本（token 数 × 单价）。合并门槛：准确率跌超 3 个点直接打回，其他指标明显恶化也要在 PR 里解释。

跑 eval 的两个时机：PR 合并前必跑（拦住坏的改动）；每周定时跑（拦住模型侧的漂移——你没改 prompt，但服务商更新了模型，效果照样会变）。第二条是血泪经验：很多人第一次听说「我什么都没改，但效果变了」，都是从这里开始的。

八、真实教训：多加了一句话，分类准确率掉了 12 个点

今年 9 月，一个客服工单分类器。v1.2.0 在线上跑了三周，准确率 87%，解析失败率 2%，大家都很满意。周一下午，我想让它「更严谨一点」——有些工单信息不全，模型会硬猜。于是加了一句话：「如果信息不足，请先列出缺失的字段，再做判断。」

当时我觉得这是纯优化：没改格式、没改分类体系，就是多一句提醒。按第四节的标准，这妥妥是个 major（加了新的行为约束），但我手一滑标成了 patch，PR 描述里写了「措辞微调」。评审的同事看了一眼：「读起来没问题。」合了。

按流程走了 canary：10% 流量，v1.3.0。周一晚上风平浪静。周二早上 9 点，客服群里有人说「今天的自动分类好像有点怪，好多工单一看就不对」。我打开看板：准确率从 87% 掉到 75%，解析失败率从 2% 涨到 9%。12 个点，一夜之间。

定位过程是这样的。9:04，git log -- prompts/system/classifier.md：最近三天只有一次提交，diff 3 行——加的那句话，加上版本号从 1.2.0 改成 1.3.0。9:06，在 200 条黄金集上重跑两个版本：1.2.0 还是 87%，1.3.0 是 74%，和线上对得上，确认就是这次改动的问题，不是模型漂移。9:08，看了几十条 canary 日志，根因清楚了：新加的那句话诱导模型先输出分析文字（「缺失字段：订单号……」），而下游解析器要求「纯 JSON」。模型一旦开始分析，就停不下来解释，JSON 被包在一段话里，解析失败，走降级逻辑乱分类。我想让它「更严谨」，结果亲手破坏了「只输出 JSON」的输出契约。

9:09 开始回滚：注册表里把 canary 流量从 10% 改成 0，stable 回到 1.0。9:12，线上命中的版本号全部回到 1.2.0，准确率曲线开始爬升，9:20 回到 87%。从发现到恢复，10 分钟。出问题的版本标成 deprecated，事故记录里写下：v1.3.0，准确率 -12pt，解析失败率 +7pt，原因：新增指令破坏 JSON 输出契约。

复盘时我算了一笔账：如果没有版本管理，这句话会淹没在过去三周 40 多次「随手改」里——有些改在代码字符串里，有些改在后台文本框里。定位要先回答「线上跑的到底是哪个版本」，这个问题本身可能就要花半天。而那次我只花了 4 分钟定位，因为 diff 只有 3 行。

这次事故真正的原罪不是那句话写得不好——那句话的出发点是对的，信息不足确实不该硬猜。原罪是两点：第一，把行为变更标成了 patch，绕过了本该有的全量 eval 和评审警惕；第二，灰度期间没人盯看板，10% 流量的 canary 跑了一整夜，直到客服先发现。后来我们补了两条规则：canary 上线后前 2 小时必须有人盯指标；解析失败率是 prompt 的「心跳线」，涨超 2 个点直接自动冻结 canary，不等人看。

prompt 的破坏力不对称：一句话能让三个月调优的效果一夜归零。所以管理 prompt 不是形式主义，是给破坏力上保险。版本号诚实、eval 跑全、回滚能在 10 分钟内完成——这三条做到了，剩下的都是优化。

九、今晚就能动手的三件事

不用等新项目，不用买新工具，今晚花一小时就能把架子搭起来：

1. 建 prompts/ 目录，把散落的提示词搬进去。从代码字符串里、从后台文本框里、从文档里，一个一个搬，一个文件一个 prompt。搬的时候别改内容，先原样搬，搬完跑一遍确认行为没变。
2. 给每个 prompt 加上元数据头。id、version（先标 1.0.0）、owner、change（写「初始版本，从某某处迁移」）、evals（先空着）。头加上了，版本管理才算开始。
3. 攒第一版黄金测试集，跑出第一个基线数字。从线上日志里捞 50 条真实输入，人工标期望输出，跑一遍记下准确率。这个数字是你的「好」的标准，以后每次改动都跟它比。

三件事做完，你就有了：版本（git + frontmatter）、评审入口（PR）、尺子（evals 基线）。A/B 和自动回滚可以下周再加——先有底线，再谈优化。很多团队的 prompt 管理死在「想一次做到完美」，而完美是迭代出来的，不是一次设计出来的。

最后说句大实话：这套东西看起来是流程，实际上是教训的封装。每一个字段（owner、baseline、change）背后，都是一次「要是当时写了就好了」的事故。你可以现在花一小时搭架子，也可以等第一次线上翻车后花一天补——反正这学费早晚得交，区别只是主动还是被动。