risky-changes

高风险变更

某个筛选器曾通过所有测试，却在实时数据中禁用了约 99% 的功能。测试用于检查代码是否正确；研究和实时测量则用于检查变更是否有用。

适用场景

当出错代价高昂或会影响客户时，请采用此流程：

• 公共 API 字段、筛选器或响应格式调整
• 丢弃、转换或重新排列上游数据
• 计费、定价、上限或配额
• 默认值、阈值或提供方请求参数
• 对外部数据或用户行为未经验证的假设

如果不确定某项变更是否符合条件，请采用此流程。

1. 识别假设

列出此项变更所依赖的假设，并标明哪些已有证据支持，哪些仍未经验证。

2. 实现前进行研究

使用可用的研究工具和可靠来源。分别调查每个不同的问题，至少涵盖以下内容：

• 领先产品如何处理这一设计决策？
• 真实世界的数据是什么样的：出现频率、形态和边缘情况如何？
• 用户或 Agent 实际需要什么？

如果证据与某项假设相矛盾，请在编写代码前重新考虑设计。如果无法开展研究或研究结果不明确，请说明这一缺口；不要将该假设视为已验证。仍有重要假设未经验证时，不要发布。

3. 测量真实行为

针对真实端点或提供方运行 10–20 个以上符合实际情况的案例：

• 根据真实用法设计案例，并改变主题、参数、语言和边缘条件。
• 为每个案例定义基准指标：速度、质量、准确性，以及新行为出现的频率。
• 尽可能使用确切数值。对于主观质量，采用盲测并依据明确标准进行评判。
• 如果变更前后都能测量，请进行比较。
• 只读的生产环境分析也算测量。

将案例和结果保存在项目的 evals 文件夹中，例如 docs/evals/YYYY-MM-DD-<endpoint>-<focus>.md。如有需要，请创建该文件夹。没有这份记录，就不能认为变更已得到验证。单元测试不能代替实时测量。

4. 发布前确认产品负责人批准

对于影响客户所见内容或付费金额的决策，应连同支持该决策的研究和测量结果一并提交。就这些决策取得产品负责人的批准；不要将其隐藏在计划或代码默认值中。如果现有批准涵盖即将发布的实际行为，则该批准有效。

5. 部署后验证

在一天内，通过只读生产环境分析或实时扫描，在真实流量上测量这项变更。若结果与预期不符，请立即报告。