本文由 AI 分析生成
建立時間： 2026-07-30 來源： https://refactoringenglish.com/excerpts/write-an-effective-design-doc/
Summary
Michael Lynch (ex-Google/Microsoft) argues that design docs are valuable only for hard-to-reverse decisions and must be written before any code to elicit substantive reviewer feedback. The article enumerates a comprehensive section list (including SLOs, open issues, and alternatives considered) and provides the heuristic: write a design doc when the penalty for being wrong is high.
Michael Lynch（前 Google/Microsoft 工程師）主張設計文件只對難以撤銷的決策有價值，且必須在開始寫程式碼前完成，才能獲得真正有用的審查意見。文章列出完整章節清單（含 SLO、開放問題、替代方案），並提供核心啟發式：當決策出錯的代價很高時才寫設計文件。
Key Points
- Core decision rule: “What’s the penalty for being wrong?” — write docs only for hard-to-reverse decisions
- Write before any code: post-implementation docs get rubber-stamped; pre-code docs receive substantive architectural feedback
- Full section list: title, metadata, objective, background, related docs, goals, non-goals, scenarios, diagrams, glossary, constraints, SLOs, monitoring/alerting, timeline, interfaces, dependencies/infrastructure, security, privacy, legal, logging, open issues, resolved issues, alternatives considered
- SLOs make vague requirements like “performant” concrete and force specificity about success criteria
- Open issues explicitly surfaces known tradeoffs, signaling intellectual honesty and inviting engagement
- Diagrams clarify architecture in ways prose cannot, especially for reviewers who skim
Insights
The “penalty for being wrong” heuristic makes the write/skip decision tractable where other approaches (complexity-based, “big feature” rules) are too vague. The open issues section is underused in practice: explicitly documenting known unknowns transforms a design doc from a ratification exercise into a genuine decision-making artifact. The observation that post-implementation docs get rubber-stamped is important—the expected value of a design doc is almost entirely front-loaded, before code is written.
Connections
- software-engineering-practices
- Loop Engineering A Technical Roadmap for an Autonomous Loop — STATUS.md in autonomous loops serves an analogous function to the open-issues section: human-readable state that captures known problems explicitly
Raw Excerpt
“A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner.”