AI SDD 开发规范-12-明确设计，保障设计足够准确、详细。避免模糊
2025/11/20大约 4 分钟
如何进一步明确设计，保障设计足够准确、详细。避免模糊
这是一个非常工程化、而且已经站在“AI 可执行设计”层面的问题。
你的核心诉求可以准确表述为：
如何把 Design 文档从“人能看懂的大概方案”，升级为“人和 AI 都无法误读的执行说明书”。
下面我不从“多写点细节”这种泛泛之谈说起，而是给你一套可操作、可检查、可强制执行的设计文档强化方法论，并且天然适配你当前的 AI 编程工作流（DESIGN.md + GEMINI.md + 风险扫描）。
一、先给一个总原则（非常关键）
Design 文档的目标不是“描述怎么做”，而是“消灭歧义空间”。
任何一段设计，只要存在以下情况之一，就一定不够好：
- 可以被两种合理方式实现
- AI 能“自作主张”补全细节
- 资深工程师需要“凭经验理解”
二、设计文档最容易模糊的 6 类位置（重点）
你可以把这 6 类当成强制扫描点。
明确信息
- 避免包名、类名、方法名不明确
2）避免方法参数、返回值不明确
3）jar 包依赖关系不明确
1️⃣ 行为语义模糊（Behavior Ambiguity）
❌ 常见写法：
“失败时进行重试”
问题：
- 重试几次？
- 哪些失败？
- 是否有副作用？
✅ 强化写法：
当请求返回 HTTP 5xx 或网络异常时：
- 进行最多 3 次重试
- 重试间隔为 200ms、500ms、1000ms
- 重试期间不得产生额外副作用2️⃣ 边界条件缺失（Boundary Gaps）
❌：
“正常情况下返回结果”
问题：
- 什么是“正常”？
- 空值算不算？
✅：
- 当查询结果为空时：
- 返回空数组（[]）
- HTTP 状态码仍为 2003️⃣ 非功能性要求被隐含（Hidden NFR）
❌：
“保证性能”
问题：
- 性能标准是什么？
- 超过怎么办？
✅：
- 单次接口 P99 响应时间 ≤ 200ms
- 超出阈值时：
- 打印 WARN 日志
- 不影响主流程4️⃣ 时序与因果不清（Temporal Ambiguity）
❌：
“处理完成后发送通知”
问题：
- 哪一步算完成？
- 事务内还是外？
✅：
- DB 事务提交成功后
- 异步发送通知
- 通知失败不得回滚主事务5️⃣ 责任边界模糊（Ownership Ambiguity）
❌：
“系统负责校验参数合法性”
问题：
- 哪一层？
- 哪些参数？
✅：
- Controller 层：
- 校验参数是否为空、格式是否合法
- Service 层：
- 校验业务规则6️⃣ 失败路径未设计（Failure Path Omission）
❌：
“异常情况下记录日志”
问题：
- 哪些异常？
- 是否抛出？
✅：
- 对于可恢复异常：
- 记录 ERROR 日志
- 返回业务错误码
- 对于不可恢复异常：
- 直接抛出三、设计文档的「强制结构模板」（AI 可执行版）
这是核心交付，建议你直接采用。
DESIGN.md（Strict / AI-Executable）
1. 设计目标（明确可验）
本设计的唯一目标是：
- 在不修改现有接口的前提下
- 支持订单的自动超时关闭❗ 非目标必须写清楚。
2. 输入 / 输出契约（Contract First）
### 输入
- orderId: Long（必填）
- timeoutMinutes: Int（范围 1～1440）
### 输出
- success: Boolean
- errorCode: String（仅失败时）3. 核心流程（逐步、不可跳跃）
1. 校验参数合法性
2. 查询订单
3. 若订单不存在：
- 返回 NOT_FOUND
4. 若订单已关闭：
- 直接返回 success
5. 更新订单状态为 CLOSED
6. 提交事务
7. 异步发送通知❗ 禁止使用“等”“然后”“相关处理”等词。
4. 状态变化与不变量（State & Invariants）
- 状态只能从 OPEN → CLOSED
- 不允许 CLOSED → OPEN
- 状态变更必须持久化5. 并发与一致性策略（必须）
- 使用数据库行锁保证同一订单只被关闭一次
- 不引入分布式锁6. 异常与失败设计（必填）
| 场景 | 行为 |
|----|----|
| DB 查询失败 | 抛出异常 |
| 更新失败 | 回滚事务 |
| 通知失败 | 记录日志，不重试 |7. 日志 / 监控 / 可观测性
- 状态变更成功：INFO
- 状态变更失败：ERROR8. 风险与隐性约束声明（对接 TACIT）
- 不允许修改订单状态枚举
- 不允许影响历史订单四、一个非常有效的“反模糊”技巧
🔴 设计完成后，做一次 “敌对实现审查”
给 AI 下指令：
请尝试用最容易误解设计文档的方式来实现，
并指出哪些地方可以被合理地误读。你会非常快发现：
- 哪些地方你“以为说清楚了”
- 实际根本没说清
五、强制性流程建议（与你体系强相关）
你可以形成一个闭环：
DESIGN.md
↓（模糊扫描）
AI 提出歧义点
↓
补充设计
↓
风险扫描 Checklist
↓
允许执行