Chapter 11: Writing design.md
Learning Objectives
Document all decisions made during the exploration phase into a format that a reviewer can still understand and check three months later.
Position of design.md in the 4-Piece Suite
flowchart LR
P["proposal.md
What + Why"] --> D["design.md
How
(Trade-offs + Rationale)"]
P --> S["specs/
What it looks like when done"]
D --> T["tasks.md
Step-by-step"]
S --> T
style D fill:#fff9c4→ The design document is the central hub connecting upstream and downstream. The proposal is too abstract, specs only describe behavior, and tasks only list actions—only the design explains "why."
4-Section Structure
## Chapter 11: Context
(Background, current state, constraints, stakeholders)
## Chapter 11: Goals / Non-Goals
**Goals:**
- ...
**Non-Goals:**
- ...
## Chapter 11: Decisions
### D1. <Topic>
**Choice**：...
**Rationale**：...
**Trade-offs**：...
### D2. <Topic>
...
## Chapter 11: Risks / Trade-offs
- [Risk] → Mitigation
Three-Part Structure for Each Decision
flowchart TB
D["D Number + Topic"] --> Pick["What was chosen
(Specific solution, 1-2 sentences)"]
Pick --> Why["Rationale
(3-5 reasons + why alternatives were rejected)"]
Why --> Trade["Trade-offs
(What was explicitly given up)"]
style D fill:#fff9c4
style Pick fill:#c8e6c9
style Why fill:#bbdefb
style Trade fill:#ffcdd2Complete Example (from doc2video's D5):
### D5. Synchronization Strategy: Narrate then Type (Linear Script)
**Choice**：Strict sequence for each step: Highlight document → Play TTS → TTS ends → Type in terminal → Wait for command completion → Pause for N seconds → Next step.
**Rationale**：
- Degrades the "reactive real-time scheduling" problem to "linear playback."
- Consistent with a beginner's understanding: "First listen, then watch."
- Decoupled from D1/D2/D3; timeline assembly is handled by post-processing.
**Trade-offs**：Cannot perform advanced "narrate-while-typing" demonstrations; this experience is explicitly abandoned for the MVP.
How to Write Goals / Non-Goals
Goals (What to do) Non-Goals (What explicitly NOT to do)
───────── ─────────────────────
Can compile to mp4 No GUI automation
With voiceover + subtitles No cross-platform support
DryRun pre-check No VM isolation
Split-screen layout No multi-language switching
Visualization:
flowchart LR
All["Everything potentially thought of
(Infinite)"] --> Goals["✓ Goals
(Done in this change)"]
All --> NG["✗ Non-Goals
(Explicitly not done)"]
All --> Silent["? Not mentioned
(Blank = Default rejection)"]
Goals --> NextChange["May expand in next change"]
NG --> WontDo["Unless new change
explicitly overturns"]
Silent --> Reject["Treated as Non-Goal"]
style Goals fill:#c8e6c9
style NG fill:#ffcdd2
style Silent fill:#fff9c4→ Non-Goals are more important than Goals—they define boundaries and prevent scope creep. If any agent wants to do something listed in Non-Goals three months later, the reviewer will directly reject it. Anything not explicitly written is also treated as rejected—this is the "blank by default = not doing" principle.
How to Write Risks
[Risk] Author's machine cleanliness issue
→ Mitigation: Print a checklist before tool recording, prompting for installed packages
[Risk] edge-tts uses non-public API
→ Mitigation: Abstract TTSBackend, OpenAI can be used as fallback
Format: Problem → How to mitigate. State clearly in one line.
Anti-Patterns
❌ Design written as a README No "why"
❌ Design written as a future roadmap That's a roadmap, not a design
❌ No Non-Goals Unclear boundaries, will lead to disputes later
❌ Decisions not numbered Cannot be referenced in subsequent reviews
❌ Decisions only state "what was chosen" No explanation = no one dares to change it three months later
What You Can Do Now
- Write a design.md with Goals/Non-Goals
- Use D numbers to allow decisions to be precisely referenced by reviewers
- Each decision (D) includes "Rationale" and "Trade-offs"
The next chapter will lay out the "bones" of the specification—Requirements and Scenarios.