Prompt 版本记录模板

长期使用的 prompt 不应该只保存在聊天记录里。每次改动都要能回答：为什么改、改了什么、验证了什么、还剩什么风险。

1. Prompt 版本卡

# Prompt Version

## 基本信息

- 名称：
- 版本：
- 日期：
- 负责人：
- 适用场景：
- 关联模型：
- 关联工具：
- 关联 RAG 索引：
- 关联 schema：

## 当前 prompt

[粘贴完整 prompt，或链接到 prompt 文件]

## 成功标准

- [必须达成的质量标准]
- [格式或 schema 要求]
- [安全边界]
- [成本和延迟约束]

## 不支持范围

- [明确不做什么]
- [需要人工复核的情况]
- [应该拒答或升级的情况]

2. 改动记录

改动原因不要只写“优化效果”。应该写清楚触发因素：

• 输出格式漂移。
• 关键字段遗漏。
• RAG 引用错误。
• 工具误选。
• 安全边界失败。
• 成本或延迟过高。
• 用户反馈指出问题。
• 模型或 API 版本变更。

3. 失败样例记录

## Failure Case

- case_id:
- 发现日期：
- 来源：人工测试 / 生产日志 / 用户反馈 / Eval
- prompt 版本：
- 模型版本：
- 输入摘要：

### 期望行为

[应该输出什么、拒绝什么、调用什么工具或引用什么来源]

### 实际行为

[实际输出或 trace]

### 失败类型

- [ ] 幻觉
- [ ] 格式错误
- [ ] 关键字段遗漏
- [ ] 引用不支持结论
- [ ] 工具调用错误
- [ ] 权限或安全失败
- [ ] 成本或延迟异常
- [ ] 其他：

### 归因

[prompt / schema / RAG / 工具 / 模型 / 权限 / 评估集 / 数据源]

### 修复方案

[准备怎么改]

### 是否加入回归集

是 / 否。原因：

4. 发布前检查

每次 prompt 改版上线前至少检查：

• 旧版本和新版本使用同一批 Eval 样例比较。
• 严重安全失败为 0。
• 结构化输出通过 schema。
• 高风险场景仍然要求人工复核。
• RAG 引用能支持关键结论。
• 工具调用 trace 没有越权或循环。
• 成本和 P95 延迟没有不可接受上涨。
• 失败样例已经归档。
• README 或使用说明已更新。

5. 回滚记录

## Rollback

- 回滚日期：
- 从版本：
- 回滚到版本：
- 原因：
- 影响范围：
- 后续处理：

6. 最小目录建议

prompts/
  summarize_contract/
    prompt.md
    schema.json
    changelog.md
    eval_cases.jsonl
    failures/
      case_001.md

prompt、schema、eval 和失败样例放在一起，后续排查会轻很多。