关键要点
- 每个生产Prompt至少需要一张单行卡片（用途、模型、日期、作者）
- 每个被修改的Prompt需要一个版本块
- 每个被测试的Prompt需要一个测试套件头
- 将文档存储在与Prompt相同的位置——单独的文档会被遗弃
- 变更理由（"为什么"）是最重要的字段
未文档化的Prompt为何让团队陷入困境
📍 In One Sentence
未文档化的Prompt以三种方式让团队失败：静默回归、重复创建和知识流失——每种都可以通过每个Prompt5至10分钟的文档化来预防。
💬 In Plain Terms
当Prompt没有关于它做什么或为什么这样写的记录时，团队无法安全地修改它、在编辑后恢复它，或在没有上下文的情况下将其移交给新成员。
未文档化的Prompt以三种方式让团队失败：静默回归（无变更记录）、重复创建和知识流失。 每种失败都可以通过每个Prompt5至10分钟的文档化来预防。
最昂贵的失败是静默回归。团队修改生产Prompt以修复一个问题，无意中破坏了另一个，却没有基准进行对比。
为每个使用超过一次、存储在共享基础设施中或部署到生产环境的Prompt建立文档。
⚠️ 静默回归风险
没有版本块和黄金样例，修改生产Prompt的团队没有基准。每次编辑都是对之前状态的猜测。
6种Prompt文档化模板
6个模板覆盖了Prompt的完整生命周期。 每个模板设计为10分钟以内可完成填写。
- 1单行卡片
Why it matters: 目的：为任何复用Prompt提供最基础的记录。字段：Prompt名称、用途（1句话）、目标模型、创建日期、作者。 - 2版本块
Why it matters: 目的：跟踪随时间变化的Prompt历史。字段：版本号、修改日期、作者、变更内容（1句话）、变更原因（1句话）、测试结果摘要。 - 3测试套件头
Why it matters: 目的：在编写测试前定义验收标准。字段：测试目标、通过标准、黄金样例（2至3个输入/输出对）、已知失败模式。 - 4决策日志
Why it matters: 目的：记录从Prompt文本中不明显的设计决策。字段：已做出的决策、考虑过的替代方案、选择此方案的原因、日期。 - 5变更理由
Why it matters: 目的：说明Prompt被修改的原因。字段：问题陈述、所做变更、预期改进、实测结果。 - 6API配置块
Why it matters: 目的：记录生产环境中使用的模型参数。字段：模型、temperature、max_tokens、top_p、stop_sequences、system prompt版本、user prompt版本。
📌 模板选择指南
新Prompt → 单行卡片。修改的Prompt → 版本块。测试的Prompt → 测试套件头。做出设计决策 → 决策日志。失败后修改 → 变更理由。部署到生产 → API配置块。
Prompt文档的存储位置
将Prompt文档存储在与Prompt相同的系统中。
- Git：适合将Prompt存储为文件的工程团队。提交消息作为版本块。免费。
- PromptHub：具有版本历史、审查者签名和测试结果存储的专用Prompt管理。
- Notion：适合将Prompt作为文档管理的团队。缺乏版本控制和测试集成。
- Braintrust：将测试套件头和评估结果与Prompt版本一起存储。
💡 共同存放文档
存储在单独系统（Notion、Confluence、Google Docs）中的文档会在几天内变得陈旧。只有与Prompt一起存在的文档才能保持最新。
常见文档化错误
❌ 完全没有文档
Why it hurts: Prompt在编辑后无法恢复，团队无法理解为什么Prompt以特定方式编写
Fix: 至少使用单行卡片模板——3个字段，不到2分钟
❌ 文档与Prompt分开存储
Why it hurts: Prompt变更时文档变得陈旧；团队忘记更新
Fix: 将文档存储在与Prompt本身相同的文件或Git提交中
❌ 缺少"为什么"字段——只描述Prompt做什么
Why it hurts: 未来的编辑者不了解约束条件，无法安全重构
Fix: 为每个模板添加"理由"字段：1-2句话说明为什么选择这种结构
❌ 没有版本块
Why it hurts: 无法知道生产环境中运行的Prompt是否与文档化版本匹配
Fix: 为每个生产Prompt文件添加版本和修改日期
常见问题
为什么Prompt需要文档化？
没有文档的Prompt无法被审查、审计或重现。团队无法诊断回归问题，无法回滚到已知可用的版本。
最少文档是什么？
单行卡片：用途（一句话）、目标模型、创建日期、作者。填写只需2分钟。
Prompt文档应该存储在哪里？
与Prompt本身相同的位置。Git适用于代码文件，PromptHub提供内置版本历史的结构化存储。
新Prompt应该使用哪个模板？
从单行卡片开始。进入生产 → 版本块。多个测试用例 → 测试套件头。非显而易见的设计决策 → 决策日志。
应该多久更新一次文档？
每次Prompt文本更改时更新。每次实质性编辑都要添加版本号递增和变更理由。
可以在PromptHub中使用这些模板吗？
可以。PromptHub存储的字段直接映射到版本块和API配置块模板。以模板为草稿，复制字段到PromptHub即可。
Prompt文档变更理由需要多详细？
三行：变更了什么（一句话）、为什么（变更解决的问题）、以及哪个测试确认它有效。