当 Prompt 工程遇上软件工程：给你的 AI Agent 上版本管理
2025-03-22
如果你的 AI Agent 出了问题，你能回滚到上一个版本吗？
一个真实的痛点
某天下午，我更新了一个 Agent 的分析流程，加了几条看起来很合理的规则。第二天发现，它的输出质量明显下降——产出的文档里多了大量冗余内容，且遗漏了原本能覆盖到的边界场景。
问题是：我改了什么？具体改了哪一行？改之前是什么样子？
如果这是一段 Python 代码，答案显而易见——git log、git diff、git revert。但这是一段 prompt。你把它改了就改了，没有历史，没有 diff，没有回滚。
Prompt 正在经历代码曾经经历的演化
回看软件工程的历史，代码管理经历了清晰的阶段：
| 阶段 | 代码 | Prompt |
|---|---|---|
| 蛮荒 | 一个大文件，谁都往里面加 | 一个超长 system prompt |
| 模块化 | 拆分成函数和模块 | 拆分成 Agent/Skill/Command |
| 版本化 | SVN/Git 管理历史 | ??? |
| 工程化 | CI/CD、Code Review、SemVer | ??? |
把 Agent 定义当做代码管理
版本化
每个能力组件（Skill、Command、Rule）都有独立的版本号，遵循 Semantic Versioning：
- MAJOR：Breaking change——比如输出格式变了，下游消费者需要适配
- MINOR：新增能力——比如分析流程多了一个维度
- PATCH：修复和优化——比如改善了某个边界场景的处理
CHANGELOG
每个 Skill 目录下都有一个 CHANGELOG.md，格式遵循 Keep a Changelog：
## [2.1.0] - 2024-03-15 ### Added - 新增"共享写入方法调用方兼容性检查"步骤 ### Changed - 风险评估维度从 3 个扩展到 4 个
Code Review
所有 Agent 定义的修改都通过 PR 流程，像审查代码一样审查 prompt 变更。
事实上，审查 prompt 变更比审查代码变更更重要——因为一行 prompt 的改动可能影响所有后续输出的行为模式。
质量门禁：不只是跑测试
我设计了一个六维度的质量检查清单：
| 维度 | 检查内容 | 类比 |
|---|---|---|
| 结构完整性 | 必选章节是否齐全 | 编译通过 |
| 流程可执行性 | Procedure >= 3 步且可操作 | 单元测试通过 |
| 示例充分性 | Examples >= 2 个，含完整端到端 | 集成测试通过 |
| 业务无关性 | 换一个项目能不能用 | 可移植性检查 |
| 输出结构性 | 产出有明确 schema | API 契约验证 |
| 约束明确性 | 明确声明"不做什么" | 安全审计 |
依赖管理：Skill 之间的版本约束
当系统中有几十个 Skill 时，它们之间的依赖关系会形成一张网。通过 SKILL.md 的 metadata 来声明依赖：
upstream: - problem_definition # 谁给我提供输入 - task_decomposition downstream: - test_case_authoring # 谁消费我的输出 - regression_planning
一些教训
教训 1：过度版本化也是病
最初我给每个 Rule 都加了独立版本号，结果发现 Rule 的变更频率很低，独立版本号带来的管理开销远大于收益。
教训 2：CHANGELOG 比 git log 有用 10 倍
Git commit message 通常是"fix: xxx"这种简短描述。而 CHANGELOG 可以解释"为什么做这个改动"。两者不可替代。
教训 3：不要假装在做软件工程
最常见的失败模式是"创建了 CHANGELOG 文件但从来不更新"。如果引入流程但不执行还不如不引入。
教训 4：AI 可以自己管理自己的版本
我建了一个"meta-plugin"——一个专门用来管理其他 plugin 内容的插件。让 AI Agent 管理 AI Agent 的定义。
这一切值得吗？
如果你的 AI Agent 只有一个 prompt 文件，用了就扔——不值得。
如果你的 AI Agent 系统有多个角色、几十个能力模块、多人协作维护、长期迭代演进——绝对值得。
核心洞察很简单：AI Agent 的定义文件就是代码。它需要代码的所有管理实践。
这是"AI Agent 工程化实践"系列的第二篇。下一篇将深入讨论 Skill 设计哲学。