编写 AI 可执行的规范
好的规范对人类和 AI 代理都有效。这 12 个模式帮助您编写清晰、可操作且没有歧义的规范。
每个模式都与第一原则相关联：上下文经济（适合工作记忆）、信噪比（每个词都重要）、意图优于实现（捕获为什么）、桥接差距（人类 + AI 理解）和渐进式披露（在需要时添加复杂性）。
1. 使用一致的结构
在每个规范中保持相同的章节顺序：## 问题、## 解决方案、## 成功标准，以及可选的 ## 权衡。
一致的结构帮助人类和 AI 快速解析规范。当每个规范遵循相同的模式时，不需要猜测在哪里找到信息。
## 问题
由于多步骤表单，用户入职平均需要 14 分钟。
## 解决方案
将流程压缩到 2 个屏幕，并将配置文件丰富延迟到注册后。
## 成功标准
- 平均入职时间 < 5 分钟
- NPS 增加 10 分
- 完成率 > 92%
2. 展示示例，而不仅仅是描述
具体示例胜过抽象描述。显示实际的 API 调用、CLI 命令和数据格式，而不是用散文描述它们。
AI 模型从示例中学习。真实的有效负载和调用减少幻觉并使规范立即可操作。
POST /api/invite {"email":"ceo@example.com","role":"admin"}
→ 201 {"id":"usr_123","status":"pending"}
3. 声明不在范围内的内容
明确列出您不构建的内容。这可以防止范围蔓延，并使 AI 代理不会实现您不想要的功能。
不在范围内：
- 移动应用平等性
- OAuth 提供商扩展
- 高级分析仪表板
4. 在实现之前定义成功
在描述如何构建某物之前编写可衡量的完成标准。这指导实现朝着正确的目标。
使用 3-5 个可测试的标准，具有具体的数字或阈值。
## 成功标准
- P95 摄取延迟 < 2s
- 合成压力测试中零数据丢失（100 万事件）
- 使用关联的跟踪 ID 记录错误
5. 捕获意图，而不是逐步说明
解释为什么做出设计选择，而不仅仅是构建什么。即使实现细节改变，意图也保持稳定。
避免使用详细的任务列表或函数名称进行微观管理。专注于推理。
我们选择最终一致性以支持摄取吞吐量。严格排序不是此用例的要求。
6. 使用前置元数据进行元数据
机器可读的前置元数据（状态、优先级、标签、依赖）使工具能够自动查询、过滤和排序工作。
---
status: in-progress
priority: high
tags: [api, ingestion]
depends_on: [052-branding-assets]
---
7. 用简单的语言写
清晰的散文对人类和 AI 都更容易理解。使用短段落（≤4 句），主动语态，并消除填充词。
当前的批处理器无限重试。这隐藏了系统性故障并增加了成本。我们将重试上限设为 5 次并发出结构化错误事件。
8. 使用真实示例而不是合成示例
来自日志、测试或生产的真实数据比编造的示例更好。真相减少了幻觉风险。
当您确实使用合成示例时，请清楚标记它们。
边缘情况（真实）：用户在发票生成中期删除了组织 → 孤立发票
边缘情况（合成）：模拟 10K 并发注册以测试速率限制器
9. 明确记录约束
硬限制（SLA、内存上限、截止日期）需要可见。这可以防止过度工程并保持解决方案可行。
在深入设计细节之前添加 约束 部分。
约束：
- 内存上限：每次 lambda 调用 256MB
- 冷启动预算：<300ms
- 迁移窗口于 2025-12-15 关闭
10. 清楚标记未知
对不完整的区域使用大写标记（TBD、OPEN QUESTION、PUNT），而不是让它们含糊不清。
这向 AI 代理发出不确定性存在的信号，并防止错误的信心。
OPEN QUESTION：我们是流式传输部分结果还是等待完整批次？
TBD：合作伙伴层的速率限制策略
11. 实现后更新规范
当您构建某物时，更新规范以反映您实际做的事情。记录计划与现实之间的差异。
这使规范成为单一真实来源。未来的 AI 代理依赖当前信息，而不是陈旧的计划。
实现差异：放弃了 Redis 缓存层—Postgres 查询调整到 14ms P95，缓存不必要。
12. 维护单一真实来源
规范应该是权威参考。不要在 wiki、文档或注释中复制信息。
链接到其他资源而不是复制。归档被取代的规范而不是悄悄编辑它们。
已归档：033-cache-layer-design 被当前摄取规范取代。
应用模式
以这些步骤开始每个规范：
- 问题和成功标准 - 定义您要解决的问题以及如何知道它完成了（模式 1 和 4）
- 约束和边界 - 记录硬限制和不在范围内的内容（模式 3 和 9）
- 示例 - 在抽象描述之前尽早添加具体示例（模式 2 和 8）
- 意图和理由 - 解释为什么做出设计选择（模式 5）
- 标记未知 - 在迭代时使用 TBD/OPEN QUESTION（模式 10）
- 调和现实 - 实现后更新规范以匹配您构建的内容（模式 11）
此工作流程确保规范保持精益、清晰并与现实同步（模式 12）。
模式快速参考
| 模式 | 上下文经济 | 信噪比 | 意图优于实现 | 桥接差距 | 渐进式披露 |
|---|---|---|---|---|---|
| 1. 一致结构 | ✓ | ✓ | |||
| 2. 展示示例 | ✓ | ✓ | |||
| 3. 不在范围内 | ✓ | ||||
| 4. 成功优先 | ✓ | ✓ | |||
| 5. 捕获意图 | ✓ | ||||
| 6. 前置元数据 | ✓ | ✓ | |||
| 7. 简单语言 | ✓ | ||||
| 8. 真实示例 | ✓ | ||||
| 9. 记录约束 | ✓ | ||||
| 10. 标记未知 | ✓ | ||||
| 11. 构建后更新 | ✓ | ||||
| 12. 单一来源 | ✓ | ✓ |
标记完成前的检查清单
- 在解决方案之前陈述问题
- 成功标准是可衡量的
- 每个 API/流程至少一个真实示例
- 边界和约束已记录
- 所有 TBD 已解决或跟踪
- 规范已更新以反映实现
常见错误
| 问题 | 为什么失败 | 修复 |
|---|---|---|
| 任务列表而不是理由 | 失去意图，难以适应 | 解释为什么，而不仅仅是什么 |
| 没有成功标准 | 无法验证或优先级 | 添加 3-5 个可衡量目标 |
| 抽象示例 | AI 产生幻觉细节 | 使用来自日志/测试的真实有效负载 |
| 隐藏约束 | 过度工程 | 在约束部分表面限制 |
| 实现后陈旧 | 误导未来工作 | 构建后立即更新 |