第 11 章 | 编写 design.md

更新于 2026/5/10
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 11 章：编写 design.md

学习目标

把 explore 时聊出的所有决策，落成一份能让 reviewer 三个月后仍能检查的文档。

design.md 在 4 件套里的位置

flowchart LR
    P["proposal.md
做什么 + 为什么"] --> D["design.md
怎么做
(取舍 + 理由)"]
    P --> S["specs/
做完是什么样"]
    D --> T["tasks.md
一步步做"]
    S --> T

    style D fill:#fff9c4

→ design 是承上启下的中枢。proposal 太抽象，spec 只描述行为，tasks 只列动作——只有 design 解释"为什么"。

4 段式结构

## Context
（背景、当前状态、约束、相关方）

## Goals / Non-Goals
**Goals:**
- ...

**Non-Goals:**
- ...

## Decisions
### D1. <主题>
**选**：...
**为何**：...
**取舍**：...

### D2. <主题>
...

## Risks / Trade-offs
- [Risk] → Mitigation

每个 D 的三段式

flowchart TB
    D["D 编号 + 主题"] --> Pick["选什么
(具体方案，1~2 句)"]
    Pick --> Why["为何
(3~5 个理由 + 替代方案为什么不行)"]
    Why --> Trade["取舍
(明确放弃了什么)"]

    style D fill:#fff9c4
    style Pick fill:#c8e6c9
    style Why fill:#bbdefb
    style Trade fill:#ffcdd2

完整例子（来自 doc2video 的 D5）：

### D5. 同步策略：先念后敲（线性脚本）

**选**：每个 step 严格顺序：高亮文档 → 播放 TTS → TTS 结束 → 终端打字 → 等命令完成 → 停留 N 秒 → 下一步。

**为何**：
- 把"反应式实时调度"问题降级为"线性回放"。
- 与初学者认知一致："先听讲，再看做"。
- 与 D1/D2/D3 解耦，时间轴拼接由后处理完成。

**取舍**：不能做"边讲边敲"的高级演示；这是 MVP 明确放弃的体验。

Goals / Non-Goals 怎么写

Goals (做什么)             Non-Goals (明确不做什么)
─────────                 ─────────────────────
能编译为 mp4               不做 GUI 自动化
有配音 + 字幕              不做跨平台
DryRun 预检               不做 VM 隔离
分屏布局                   不做多语言切换

可视化：

flowchart LR
    All["所有可能想到的
(无穷无尽)"] --> Goals["✓ Goals
(本 change 做的)"]
    All --> NG["✗ Non-Goals
(明确不做)"]
    All --> Silent["? 没提到的
(留白 = 拒绝默认)"]

    Goals --> NextChange["下次 change 可能扩"]
    NG --> WontDo["除非新 change
明确翻案"]
    Silent --> Reject["按 Non-Goal 处理"]

    style Goals fill:#c8e6c9
    style NG fill:#ffcdd2
    style Silent fill:#fff9c4

→ Non-Goals 比 Goals 更重要——它划定边界，防止 scope creep。3 个月后任何 agent 想做 Non-Goal 列出的事，reviewer 直接拒。没明确写的也按拒绝处理——这是"留白默认 = 不做"原则。

Risks 的写法

[Risk] 作者真机洁净度问题
  → Mitigation: 工具录制前打印 checklist，提示已安装包

[Risk] edge-tts 走非公开 API
  → Mitigation: TTSBackend 抽象，OpenAI 可作 fallback

格式：问题 → 怎么缓解。一行说清。

反模式

❌ design 写成 README           没有"为什么"
❌ design 写未来路线图          那是 roadmap，不是 design
❌ 没有 Non-Goals               边界不明，将来必扯皮
❌ 决策没编号                   后续 review 没法引用
❌ 决策只有"选什么"             不解释 = 三个月后没人敢改

你现在能做什么

  • 写一份带 Goals/Non-Goals 的 design.md
  • 用 D 编号让决策可被 reviewer 精确引用
  • 每个 D 都有"为何"和"取舍"

下一章把规约的"骨头"写出来——Requirement 与 Scenario。