# Prompt 版本记录模板

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

## 1. Prompt 版本卡

```markdown
# Prompt Version

## 基本信息

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

## 当前 prompt

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

## 成功标准

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

## 不支持范围

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

## 2. 改动记录

| 版本 | 日期 | 改动原因 | 主要改动 | 关联失败样例 | 验证结果 |
| --- | --- | --- | --- | --- | --- |
| v1.0 |  | 初版 |  |  |  |
| v1.1 |  |  |  |  |  |

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

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

## 3. 失败样例记录

```markdown
## Failure Case

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

### 期望行为

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

### 实际行为

[实际输出或 trace]

### 失败类型

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

### 归因

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

### 修复方案

[准备怎么改]

### 是否加入回归集

是 / 否。原因：
```

## 4. 发布前检查

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

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

## 5. 回滚记录

```markdown
## Rollback

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

## 6. 最小目录建议

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

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