Back to Details

design-doc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Doc

设计文档

Write a lightweight architecture design doc for a decision that deserves thinking before code. Use this when the problem has real ambiguity, tradeoffs, cross-cutting concerns, or future maintenance risk. If the solution is obvious and the doc would only become an implementation manual, say so and recommend 
spec
or 
implement
instead.
为值得在编码前深思熟虑的决策撰写轻量化架构设计文档。当问题存在明显模糊性、需要权衡取舍、涉及跨领域关注点或存在未来维护风险时，使用此方法。如果解决方案显而易见，且文档仅会沦为实现手册，请说明这一点并推荐使用
spec
或
implement
替代。

Workflow

工作流程

1. Ground

1. 基础准备

  • Treat the full argument as the design brief unless the user names a feature or path.
  • Derive a kebab-case slug if no name is given.
  • Read referenced docs, code, specs, plans, and architecture notes so the design fits the system as it exists.
  • Identify stakeholders, goals, non-goals, constraints, cross-cutting concerns, and decisions that need human review.
  • Ask only when a missing fact would materially change the design. Ask one question at a time with your recommended answer.
  • 除非用户指定了功能或路径，否则将完整需求作为设计概要。
  • 若未提供名称，则生成一个kebab-case格式的slug。
  • 阅读参考文档、代码、规范、计划和架构说明，确保设计适配现有系统。
  • 识别利益相关者、目标、非目标、约束条件、跨领域关注点以及需要人工评审的决策。
  • 仅当缺失的事实会实质性改变设计时才提出问题。每次只提一个问题，并附上你的推荐答案。

2. Write

2. 撰写文档

Write 
docs/<design-slug>/design.md
using the sections below. Keep solo-developer docs short: prefer 1-3 pages unless the architecture genuinely needs more.
  • Status: Draft, In Review, Approved, or Superseded.
  • Summary: the problem and recommended direction in a few sentences.
  • Context and Scope: objective background, current system, and what this doc covers.
  • Goals: outcomes this design must achieve.
  • Non-Goals: reasonable adjacent outcomes this design deliberately excludes.
  • Constraints: technical, product, migration, compatibility, operational, cost, or time constraints.
  • Proposed Design: the chosen architecture, starting high-level before details.
  • Architecture Views (when useful): system context, data flow, runtime, deployment, or component diagrams.
  • Interfaces and Data (when relevant): API, event, schema, storage, or contract changes that affect the design.
  • Alternatives Considered: plausible options and why they lose under the stated goals and constraints.
  • Tradeoffs: what the chosen design gains, gives up, risks, or postpones.
  • Cross-Cutting Concerns: security, privacy, observability, reliability, performance, cost, and operations where relevant.
  • Rollout and Migration (when relevant): how to ship, migrate, verify, and back out safely.
  • Open Questions: decisions or facts still unresolved.
  • Decision: the recommendation, assumptions, and who needs to review or approve it.
使用以下章节撰写
docs/<design-slug>/design.md
。单人开发的文档应简洁：除非架构确实需要更多内容，否则建议控制在1-3页。
  • 状态：Draft、In Review、Approved 或 Superseded.
  • 摘要：用几句话描述问题及推荐方向。
  • 背景与范围：客观背景、当前系统以及本文档涵盖的内容。
  • 目标：本设计必须达成的成果。
  • 非目标：本设计刻意排除的合理相关成果。
  • 约束条件：技术、产品、迁移、兼容性、运维、成本或时间方面的约束。
  • 拟议设计：选定的架构，先从高层概述再到细节说明。
  • 架构视图（适用时）：系统上下文、数据流、运行时、部署或组件图。
  • 接口与数据（相关时）：影响设计的API、事件、schema、存储或契约变更。
  • 备选方案考量：可行的备选方案，以及为何在既定目标和约束下它们不被选用。
  • 权衡取舍：选定设计所获得的收益、放弃的内容、存在的风险或推迟的事项。
  • 跨领域关注点：相关的安全、隐私、可观测性、可靠性、性能、成本和运维事项。
  • 发布与迁移（相关时）：如何安全地发布、迁移、验证和回退。
  • 未解决问题：尚未确定的决策或事实。
  • 决策结论：推荐方案、假设前提以及需要评审或批准的人员。

3. Pause

3. 暂停阶段

Stop after writing. Do not continue into 
spec
, 
plan
, or implementation until the human confirms the design.
撰写完成后停止推进。在人工确认设计之前，不要进入
spec
、
plan
或实施阶段。

Rules

规则

  • The document exists to make reasoning reviewable, not to document every implementation step.
  • Focus on tradeoffs, alternatives, and constraints code will not explain later.
  • Use diagrams only when they clarify relationships, flows, or deployment.
  • Do not copy full schemas, APIs, or code unless the exact shape is central to the decision.
  • Write for a future maintainer who needs to understand why this design was chosen.
  • 文档的作用是让决策逻辑可被评审，而非记录每一个实现步骤。
  • 重点关注代码日后无法解释的权衡取舍、备选方案和约束条件。
  • 仅在图表能明确说明关系、流程或部署情况时才使用图表。
  • 除非确切的结构是决策的核心，否则不要复制完整的schema、API或代码。
  • 为未来需要理解为何选择此设计的维护人员撰写文档。