design.md 关键性 + 查缺补漏

上篇博客《SDD 模式 AI Coding 实战感悟》讲了整体流程与踩坑。这篇是 SDD 系列第 5 篇——开发过程中的真实感悟，聚焦 3 个关键议题：调试 AI 代码的陷阱、design.md 的真正作用、design.md 查缺补漏清单。

写在前面：与第 1 篇的区别

【第 1 篇】SDD 模式 AI Coding 实战感悟
- 整体流程（spec → design → tasks → develop）
- 4 份文档的分工与时间投入
- 一个人跑全流程的真实感受
- 给后来者的 5 条建议

【本篇】SDD 开发感悟 2
- 开发过程中的具体场景
- 调试 AI 代码的 7 大问题（你列出 3 个 + 我补充 4 个）
- design.md 为什么是"关键"
- design.md 查缺补漏 10 项清单
- AI 进死巷的 8 大破局方法

核心洞察 3 条

【洞察 1】个人能力要让 AI 帮助快速成长
- AI 不是替代你思考
- 是你的"陪练"
- 5 大方式让 AI 加速你的成长

【洞察 2】调试 AI 代码的 7 大问题
- 自己没理解代码或设计
- AI 上下文被污染
- AI 能力不足
- + 我补充的 4 个（见下文）

【洞察 3】design.md 真的是 AI 开发的"关键
- 做好设计 = 代码完成 90%
- 但必须查缺补漏
- 时序、状态转换、异常处理等 10 项

---

第一部分：个人能力 + AI 加速成长

1.1 真正的问题不是 AI 写代码

【常见误解】
- "AI 写代码 = 我不用写代码"

【真相】
- AI 帮你写代码 = 你要审更多代码
- AI 帮你做决策 = 你要审更多决策
- AI 帮你设计 = 你要审更多设计

【本质转变】
- 你从"打字的人" → "审的人 + 改需求的人 + 定架构的人"
- 打字量减少，决策量增加

1.2 AI 加速个人成长的 5 大方式

方式 1：让 AI 解释你不懂的代码

【问法】
- "这段代码为什么这样写？"
- "这个设计选择背后的考量是什么？"
- "如果换成另一种实现，会怎样？"

【好处】
- 快速建立代码理解
- 不需要从头读所有代码
- 节省 70%+ 学习时间

方式 2：让 AI 给你"假设性挑战"

【问法】
- "如果 X 输入改了，会发生什么？"
- "如果 Y 性能不够，怎么优化？"
- "如果 Z 安全要求提高，要改哪些地方？"

【好处】
- 训练边界思维
- 发现设计的脆弱点
- 提前考虑异常

方式 3：让 AI 列出你的设计的所有妥协

【问法】
- "你做了哪些 trade-off？"
- "这个选择的代价是什么？"
- "有没有更简单的实现？"

【好处】
- 理解每个决策的成本
- 知道"为什么不是另一种"
- 知识沉淀

方式 4：让 AI 反向推导设计意图

【问法】
- "从这段代码反推 spec，应该是什么？"
- "如果让你写 spec，你会怎么写？"
- "这段代码的设计哲学是什么？"

【好处】
- 验证你的理解
- 发现隐藏的设计意图
- 学习优秀代码的设计

方式 5：让 AI 出题考你

【问法】
- "面试官会怎么问我这个项目？"
- "给我 10 个深度问题？"
- "我会卡在哪？"

【好处】
- 准备深度技术分享
- 找出自己的知识盲区
- 提升表达能力

1.3 AI 是陪练，不是替代

【错误用法】
- AI 写，我审 → 审不动（因为不懂）
- AI 做决定 → 决定质量低（因为没思考）
- AI 出活 → 不可持续（因为没成长）

【正确用法】
- AI 当"陪练"
- 我决定 + AI 实现
- AI 反馈 + 我学习
- AI 加速 + 我吸收

【最终目标】
- 我的能力提升
- AI 是杠杆，不是替代

---

第二部分：调试 AI 代码的 7 大问题

2.1 为什么调试 AI 代码特别难

【传统调试】
- 我写代码 → 我理解 → 我调试
- 知识在脑子里

【AI 调试】
- AI 写代码 → 我不一定理解 → 我调试
- 知识分散在我AI 和 AI 之间
- 上下文不连续

【调试陷阱】
- 我以为 AI 理解了
- AI 以为我理解了
- 实际两边都不完全理解

2.2 7 大问题 + 诊断方法

问题 1：自己没理解代码或设计 ⭐⭐⭐⭐⭐

【症状】
- AI 给出方案，但我不懂
- 调试时不知道为什么
- 改一行担心破坏其他地方

【诊断】
- 自己读一遍代码
- 自己画一遍设计
- 自己写测试验证

【解决】
- 不懂就问 AI
- 不懂就重新设计
- 不懂就换 AI 重写

【关键】
- 调试的前提是理解
- 不理解 = 调不通

问题 2：AI 的上下文被污染了 ⭐⭐⭐⭐⭐

【症状】
- AI 开始胡说八道
- AI 反复回到老问题
- AI 给的方案前后矛盾

【诊断】
- 检查对话历史（是否太长）
- 检查 spec / design 是否被修改过
- 检查 AI 是否还记得最初需求

【解决】
- 另起新 session + 完整 spec
- 清理无关历史
- 重新给 AI 完整背景

【预防】
- 每个 phase 一个 session
- 不要在长对话里反复切换
- 定期清理上下文

问题 3：当前 AI 能力不足 ⭐⭐⭐⭐

【症状】
- AI 给的方案太幼稚
- AI 不知道最新技术
- AI 写不出复杂逻辑

【诊断】
- 任务是否超出当前 AI 能力
- 是否需要更强的 AI 模型
- 是否需要人接手

【解决】
- 切小问题（拆给 AI）
- 切大任务（人接手）
- 升级 AI（用更强模型）

【接受】
- AI 有能力上限
- 不是所有事 AI 都能做

问题 4：spec / design 本身有歧义 ⭐⭐⭐⭐

【症状】
- AI 的解读和你不同
- 同一个需求有多种实现
- 调试时发现两边理解不一样

【诊断】
- 重读 spec，找歧义点
- 让 AI 复述需求，确认理解

【解决】
- 消除歧义（重新写 spec）
- 补充用例（user story）
- 加验收标准

【预防】
- spec 阶段串讲
- 让不同人复述，确认理解一致

问题 5：AI 用了错误的假设 ⭐⭐⭐

【症状】
- "我以为你懂这个"（AI 经常说）
- AI 假设了不存在的前提
- AI 没问关键问题就直接写代码

【诊断】
- 让 AI 列出所有假设
- 检查假设是否合理

【解决】
- 明确列出所有假设
- 不合理的假设 = 改 spec
- 让 AI 假设显式化

【预防】
- spec 写"前置条件"
- design 写"假设清单"

问题 6：测试用例不完整 ⭐⭐⭐

【症状】
- 漏了边界条件
- 漏了异常路径
- 测试覆盖率低

【诊断】
- 看测试用例覆盖了什么
- 列出"可能出错的场景"
- 手动跑边界条件

【解决】
- 补测试用例
- 手动验证关键路径
- 加 e2e 测试

问题 7：反馈给 AI 的信息不够 ⭐⭐⭐

【症状】
- "消息发送有问题"（太模糊）
- AI 给了几个方向都没命中

【诊断】
- 自己重新整理反馈
- 包含：上下文 + 触发动作 + 现象 + 预期 + 实际

【解决】
- 完整反馈（5 个要素）
- 提供截图 / 日志 / 错误码

【实例对比】
❌ 差："消息发送有问题"
✅ 好："成功创建 session 后，我刚发送消息，
   消息闪现一下后消失了。检查 WebSocket 处理。"

2.3 7 大问题速查表

| 问题 | 概率 | 难度 | 优先级 |
|------|------|------|-------|
| 自己没理解 | ⭐⭐⭐⭐⭐ | 中 | P0 |
| 上下文污染 | ⭐⭐⭐⭐⭐ | 低 | P0 |
| AI 能力不足 | ⭐⭐⭐⭐ | 高 | P1 |
| spec 歧义 | ⭐⭐⭐⭐ | 中 | P1 |
| AI 错误假设 | ⭐⭐⭐ | 低 | P1 |
| 测试不全 | ⭐⭐⭐ | 中 | P2 |
| 反馈不够 | ⭐⭐⭐ | 低 | P2 |

---

design.md 的关键作用

design.md 是 AI 开发的"关键"

【SDD 4 份文档】
- spec.md = 需求
- design.md = 设计 ← 关键
- tasks.md = 任务
- develop.md = 开发

【为什么 design.md 关键？】
1. 决策前置 = 避免代码级返工
2. 多 Agent 协作的统一语言
3. AI 理解的"上下文窗口"
4. 知识沉淀 = 下次复用
5. Review 的基准

3.2 设计做好 = 代码完成 90%

【为什么？】
- 设计 = 决策
- 决策 = 难的部分
- 实现 = 简单的部分

【具体占比】
- 设计决策：占项目 70% 难度
- 代码实现：占项目 30% 难度
- 调试：占项目 50% 时间

【如果设计错了】
- 代码写完才发现 = 100% 返工
- 测试写完才发现 = 50% 返工
- 上线后才发现 = 1000% 返工（业务损失）

【结论】
- 在 design 阶段多花 1 小时
- 在 develop 阶段省 10 小时
- 在 production 阶段省 100 小时

design.md 的 5 大具体维度

维度 1：接口设计（API contract）

【为什么关键】
- 接口 = 模块的"合同"
- 接口错 = 上下游都改

【必填内容】
- 接口签名（method + 入参 + 出参）
- 错误码定义
- 兼容性约定
- 版本管理

维度 2：数据流（state machine）

【为什么关键】
- 数据流错 = 状态不一致
- 最难调试的 bug 都是状态相关

【必填内容】
- 状态定义
- 转换条件
- 异常状态（dead end）
- 并发场景

维度 3：异常路径（error handling）

【为什么关键】
- 正常路径谁都能写
- 异常路径 = 健壮性的关键

【必填内容】
- 异常分类（可恢复 / 不可恢复）
- 重试策略
- 降级方案
- 上报机制

维度 4：时序（concurrency / async）

【为什么关键】
- 时序错 = 死锁 / 竞态
- 最难重现的 bug

【必填内容】
- 同步 / 异步边界
- 锁 / 临界区
- 顺序保证
- 超时机制

维度 5：模块边界（separation of concerns）

【为什么关键】
- 边界不清 = 改动牵一发动全身
- 复用困难

【必填内容】
- 模块职责
- 模块依赖（哪些不应该依赖）
- 数据所有权
- 测试边界

---

design.md 查缺补漏 10 项清单

【design.md 必查的 10 项】

1. 时序（sequence）
   - 调用顺序
   - 异步 / 同步
   - 超时机制

2. 状态转换（state machine）
   - 状态定义
   - 转换条件
   - 异常状态

3. 异常处理（error handling）
   - 异常分类
   - 重试 / 降级
   - 错误码

4. 并发（concurrency）
   - 锁 / 临界区
   - 顺序保证
   - 资源竞争

5. 数据一致性（consistency）
   - 强一致 / 最终一致
   - 事务边界
   - 数据回滚

6. 边界条件（boundary）
   - 空值 / null
   - 极值（最大 / 最小）
   - 异常输入

7. 性能（performance）
   - QPS / 延迟
   - 资源使用
   - 瓶颈分析

8. 安全（security）
   - 鉴权 / 授权
   - 数据加密
   - 攻击防护

9. 可观测性（observability）
   - 日志
   - 监控 / 告警
   - 链路追踪

10. 可测试性（testability）
    - 单元测试边界
    - Mock 友好
    - 集成测试

4.1 容易忘记的 5 项（重点提醒）

【第 1】时序（最容易忘）
- 因为代码写完看起来"对"
- 但时序错 = 偶发 bug
- 调试时才发现 = 太晚

【第 2】异常处理（最容易被忽略）
- 业务逻辑只考虑"正常情况"
- 异常 = 边界
- 不处理 = 雪崩

【第 3】边界条件（最难想到）
- "不会有人输入这个" → 用户就会输入
- "不可能为空" → 就是会空

【第 4】并发（最容易写错）
- 单线程逻辑 "对"
- 多线程 = 不一定对
- 必须显式处理

【第 5】可观测性（最不被重视）
- "代码能跑就行"
- 但出问题时 = 不知道哪里错了
- 日志 / 监控 = 救命稻草

4.2 查缺补漏的方法

【方法 1】串讲（最有效）
- 给同事讲一遍设计
- 不熟的地方 = 你的盲区
- 别人一个问题 = 一个漏洞

【方法 2】自问自答
- 每个模块问 5 个"如果"
  - 如果用户输入 X？
  - 如果服务挂掉？
  - 如果网络断？
  - 如果并发 1000？
  - 如果数据被改？

【方法 3】对照 checklist
- 打印上面的 10 项
- 一项一项对照
- 没写 = 必须补

【方法 4】让 AI 找漏洞
- "从安全 / 性能 / 并发角度，找设计的漏洞"
- "作为面试官，你会怎么问这个设计？"
- "有哪些边界条件没考虑到？"

【方法 5】跑通 prototype
- 写一个最小可行实现
- 跑起来看效果
- 比设计文档更真实

---

第五部分：AI 进死巷的 8 大破局方法

5.1 识别"死巷"

【死巷的 5 个信号】
1. AI 反复回到同样的错误
2. AI 给出 3+ 个方案都不对
3. AI 的回复越来越长（绕圈子）
4. AI 开始质疑你的需求
5. 你自己也说不清问题在哪

【一旦识别】
- 不要继续"试错"
- 立即停下来
- 用下面的方法

5.2 8 大破局方法

破局 1：停下来，自己先理解代码

【做法】
- 停止和 AI 对话
- 自己读代码
- 自己画流程图
- 写自己的测试

【为什么】
- AI 进死巷 = 你也可能不理解
- 两个人都不懂 = 永远解不开
- 必须有人懂

【关键】
- 调试的前提是理解
- 不理解 = 调不动

破局 2：重读 spec 和 design

【做法】
- 拿出最初的 spec
- 拿出 design.md
- 对照代码看是否一致

【为什么】
- 可能是 spec 本身有歧义
- 可能是 design 漏了某场景
- 可能是实现偏离了设计

【关键】
- spec / design 是"锚点"
- 偏离锚点 = 错

破局 3：给 AI 一个"全新"session

【做法】
- 新开对话
- 重新给 AI：
   - 完整 spec
   - 完整 design
   - 当前的 bug 描述
   - 已尝试的所有方案

【为什么】
- 上下文可能被污染
- 新 session = 干净起点
- 但要确保给的背景完整

【关键】
- 不是"换个 AI"
- 是"换个干净的 session"

破局 4：让 AI 用其他思路

【问法】
- "如果不用 X，会怎么实现？"
- "能不能换个思路？"
- "完全抛弃当前方案，重新设计"

【为什么】
- AI 可能在"局部最优"
- 换思路 = 跳出死巷

【关键】
- 不要让 AI 在错误方向上继续
- 明确要求"换思路"

破局 5：切小问题

【做法】
- 把大问题拆成 N 个小问题
- 每个小问题给 AI
- 一个个解决

【例子】
❌ "为什么这个功能不对？"
✅ "为什么 X 输入时 Y 行为？"
✅ "为什么 Z 条件下 W 输出？"

【为什么】
- 大问题 = 信息量太大
- 小问题 = AI 更聚焦
- 小问题解决了 = 大问题解决

破局 6：手动验证

【做法】
- 不要纯靠 AI
- 自己用 curl / postman / debug 工具
- 手动复现问题

【为什么】
- AI 看不到你的环境
- AI 不能跑代码
- 只有你能验证

【关键】
- 调试不只是"问 AI"
- 是"动手验证"

破局 7：接受 AI 能力上限

【做法】
- 判断任务是否超出当前 AI 能力
- 必要时人接手
- 必要时升级到更强 AI

【例子】
- 复杂算法设计 → 高级 AI
- 系统架构 → 顶级 AI
- 简单实现 → 普通 AI

【关键】
- AI 有上限
- 不是所有事 AI 都能做
- 该人做就人做

破局 8：休息一下

【做法】
- 暂停 30 分钟
- 喝杯水 / 走一走
- 回来再看

【为什么】
- 调试疲劳 = 看不出问题
- 大脑需要"重启"
- 休息后经常秒解

【金句】
"调试不下去 = 休息一下 = 秒解"

【关键】
- 不要"死磕"
- 死磕 = 低效
- 休息 = 高效

5.3 破局方法速查

| 方法 | 适用场景 | 时间 | 优先级 |
|------|---------|------|-------|
| 1. 停下来理解 | 任何时候 | 30min | P0 |
| 2. 重读 spec | 设计怀疑错 | 30min | P0 |
| 3. 新 session | 上下文污染 | 20min | P0 |
| 4. 换思路 | AI 死循环 | 20min | P1 |
| 5. 切小问题 | 大问题 | 30min | P1 |
| 6. 手动验证 | 不确定环境 | 1h | P1 |
| 7. 接受上限 | 超出 AI 能力 | - | P2 |
| 8. 休息一下 | 调试疲劳 | 30min | P0 |

---

第六部分：实战案例（数字员工 AI 项目调试实录）

6.1 案例 1：上下文污染

【问题】
- 我让 AI 优化一个前端 Bug
- AI 反复给我类似方案
- 都不对

【诊断】
- 上下文被前面 50+ 轮对话污染
- AI 忘了最初的需求

【破局】
- 新开 session
- 给 AI：完整 spec + 当前 bug + 已尝试的方案
- AI 5 分钟定位

【教训】
- 长对话 = 上下文污染
- 定期开新 session

6.2 案例 2：spec 歧义

【问题】
- AI 实现的功能和我预期不同
- 反复改都不对

【诊断】
- spec 写"消息发送有问题"
- 太模糊
- AI 不懂我的具体需求

【破局】
- 重写 spec：精确描述输入 / 输出 / 边界
- AI 一次写对

【教训】
- spec 不够精确 = 调试反复
- 前期花 1 小时 = 后期省 10 小时

6.3 案例 3：AI 能力不足

【问题】
- 让 AI 设计一个复杂的分布式算法
- AI 方案太幼稚
- 多次迭代都不行

【诊断】
- 任务超出当前 AI 能力
- 我自己也半懂

【破局】
- 切小问题（拆成 3 个）
- 第 1 个我自己设计
- 第 2、3 个 AI 实现

【教训】
- 不是所有事都让 AI 做
- 复杂核心 = 人做
- 周边 = AI 做

---

第七部分：核心金句

"AI 是陪练，不是替代。
 你的能力成长 = 你的真正价值。"

"调试不下去 = 休息一下 = 秒解。
 死磕 = 低效；休息 = 高效。"

"design 阶段多花 1 小时，
 develop 阶段省 10 小时，
 production 阶段省 100 小时。"

"AI 进死巷的 5 个信号：
  反复错 + 方案多 + 回复长 + 质疑你 + 你不懂。"

"个人能力 + AI 加速 = 杠杆；
 个人能力 - AI 替代 = 灾难。"

---

第八部分：与第 1 篇的对比

【第 1 篇：流程视角】
- 整体流程
- 4 份文档
- 一个人全栈
- 给后来者的 5 条建议

【本篇：开发视角】
- 调试 7 大问题
- design 5 大维度
- 查缺补漏 10 项
- 破局 8 大方法

【第 3 篇：未来视角】（待写）
- SDD 与 AI Coding 的未来
- Agent 化 SDD
- 自动化文档
- 自我进化设计

---

写在最后：与 SDD 系列呼应

【SDD 系列博客】
- 第 1 篇：SDD 模式 AI Coding 实战感悟（流程）
- 第 2 篇：SDD 模式实战指南（决策清单 + 模板）
- 第 3 篇：SDD + 敏捷混合工作流（长期项目）
- 第 4 篇：SDD 与 AI Coding 的未来（展望）
- 第 5 篇：（本文）SDD 开发感悟 2（开发过程）

【形成闭环】
- 决策 → 流程 → 实践 → 调试 → 未来
- 完整的 SDD 实战体系

---

思维模型附录

1. 杠杆思维：AI 是杠杆，不是替代
2. 决策前置：在 design 阶段做决策
3. 边界思维：5 个"如果"找盲区
4. 反馈完整性：5 个要素说清楚
5. 上下文管理：定期清理 / 开新 session
6. 调试纪律：先理解，再动手
7. 能力边界：AI 有上限，接受它

---

给读者的 3 个问题

1. 你最近一次调试 AI 代码，问题出在哪一类？
   我：上下文污染（最近 1 周）
2. 你的 design.md 漏过哪些关键项？
   我：时序 + 异常处理（最近发现）
3. 你会什么时候让 AI 接手 vs 人接手？
   我：核心算法 = 人；周边实现 = AI

---

AI 是陪练，不是替代。

design 是关键，调试是基本功。

AI 进死巷 = 8 大方法破局。