Convert a vague design problem or proposal into a clearly structured, sufficiently detailed Markdown design document.
The deliverable is an independent .md file; the output path is specified by the user or inferred from context,
and can be directly consumed by a Code Agent for coding development.
When to use / not use
Use
- Need to write a detailed design document for a new feature / module
- Need to turn a verbally discussed design proposal into a traceable Markdown document
- Need to compare multiple technical solutions and provide a recommendation
- Need to supplement details for an existing skeleton design document
Do not use
- Pure code implementation (write code directly, do not go through the design document process)
- Simple bug fix / typo fix
- Scenarios where a complete design document already exists and only execution is needed
Input / Output
Input
The design problem provided by the user may include the following information (not all is required):
- Problem description: what problem to solve
- Constraints: performance, compatibility, dependency limitations, etc.
- Alternative solutions: ideas the user already has in mind (may be incomplete)
- Related modules: which existing modules / documents are related
- Target path: the location of the output file (may be omitted; the skill infers it based on the project structure)
Output
A complete Markdown design document. The output path is determined by the following priority:
- A path explicitly specified by the user
- A design document directory agreed upon in the project (such as
doc/、docs/design/、design/） - Same directory as the related module
The file name is recommended to use the <topic>_design.md format, but the project's existing naming conventions should be respected.
Section skeleton
Design documentMustOrganize according to the following skeleton; sections may be added or removed but the order must not be disrupted:
# <主题名>
## 概述
## 场景分析
## 方案选择
## <核心设计章节>
（根据内容拆分为多个二级章节，每个章节聚焦一个子问题）
## 文件归属
（如涉及新增 / 修改文件）
## 与其他文档的关系
（如有关联文档）
Requirements for each section
| Section | Required or not | Content requirements |
|---|---|---|
# <主题名> |
✓ | Level-1 heading, concisely summarizing the design topic |
## 概述 |
✓ | 1-2 paragraphs clearly explaining "what it is" and "why" |
## 场景分析 |
✓ | Break down the scenarios in which the problem occurs, and analyze the difficulties and challenges scenario by scenario (see "How to write scenario analysis") |
## 方案选择 |
✓ | List alternative solutions, compare benefits and costs, and explain the reasons for the final choice (see "How to write solution selection") |
| Core design section | ✓ | At least one; split into level-2 sections by sub-problem, with each section focused |
## 文件归属 |
Recommended | List in a table the paths, purposes, and whether they are included in version control for related files |
## 与其他文档的关系 |
Optional | Cross-reference related documents |
How to write scenario analysis
Scenario analysis is the bridge in a design document from "overview" to "core design"—first break down the problem space clearly, then let the subsequent design sections address them one by one. Without this step, the design easily jumps directly to solutions and ignores edge cases.
Analysis process
用户描述的问题
│
├── 1. 识别场景维度
│ └── 问题在什么条件下发生？按触发方式、用户角色、数据规模、
│ 环境差异等维度拆出 2-5 个主要场景
│
├── 2. 描述每个场景
│ ├── 场景名称（简短、可识别）
│ ├── 触发条件（谁 / 什么时候 / 什么操作）
│ └── 期望行为（理想情况下应该发生什么）
│
├── 3. 分析困难与挑战
│ ├── 该场景下"难在哪里"（技术约束、状态复杂度、边界条件）
│ ├── 是否有已知的失败模式
│ └── 与其他场景是否存在冲突或耦合
│
└── 4. 汇总为场景矩阵
└── 用表格呈现全貌，为后续设计章节提供索引
Scenario identification principles
- Split by trigger method: User-initiated vs system-triggered vs external event-driven
- Split by user role: Different roles may have different expectations and constraints for the same feature
- Split by data scale / complexity: Simple cases vs complex cases often require different handling strategies
- Split by exception path: Normal flow vs exception / degradation / retry and other scenarios
- Split by environment differences: Behavioral differences under different runtime environments, platforms, and configurations
There is no need to exhaustively enumerate all dimensions—choose the 2-3 dimensions most relevant to the current problem for splitting, and ultimately produce 2-5 main scenarios. Too few scenarios means the analysis is insufficient; too many means the granularity needs to be merged.
Output format
The scenario analysis section uses a combination of third-level subsections + a summary matrix:
## 场景分析
### 场景一：<场景名称>
**触发条件**：<谁 / 什么时候 / 什么操作>
**期望行为**：<理想情况>
**困难与挑战**：
- <挑战 1>：<为什么难，技术约束是什么>
- <挑战 2>：<边界条件 / 失败模式>
### 场景二：<场景名称>
（同上结构）
### 场景汇总
| 场景 | 触发条件 | 核心挑战 | 涉及的设计章节 |
| --- | --- | --- | --- |
| 场景一 | ... | ... | §<章节名> |
| 场景二 | ... | ... | §<章节名> |
Quality requirements
- Scenarios must be identifiable: After reading the scenario name and trigger conditions, readers can immediately map them to a specific situation in actual use
- Challenges must be specific: Write "the difficulty is X because Y", not "this scenario is relatively complex"
- Scenarios must be distinguishable from one another: If the challenges of two scenarios are completely identical, it means they should be merged
- Challenges must map to design sections: The "related design sections" column in the summary matrix must not be left blank—every challenge should have a corresponding design section to solve it; if a challenge has no corresponding section, it means the document lacks design content
How to write the solution selection
Solution selection is the decision-making hub of a design document—after the scenario analysis clarifies "what the problem is", it answers "what solution to use to solve it" and "why choose it instead of others". Without this step, readers (including your future self and Code Agent) cannot understand the context of design decisions, and are prone to re-arguing or changing direction incorrectly in subsequent iterations.
Solution evaluation process
场景分析产出的挑战列表
│
├── 1. 提出备选方案
│ ├── 列出 2-4 个可行的技术方案（含"不处理"作为基线）
│ └── 每个方案用一句话概括核心思路
│
├── 2. 逐方案评估
│ ├── 收益：解决哪些场景的挑战，带来什么额外价值
│ ├── 代价：实现复杂度、性能开销、维护成本、兼容性风险
│ └── 约束适配：是否满足项目已有的技术 / 架构 / 资源约束
│
├── 3. 对比与推荐
│ ├── 用对比矩阵呈现关键维度上的差异
│ ├── 明确推荐方案
│ └── 说明推荐理由（收益 > 代价 的具体论据）
│
└── 4. 记录否决理由
└── 每个被否决方案，说明"为什么不选"（一句话）
Principles for proposing solutions
- At least 2 alternative solutions: If there is only 1 solution, the analysis is insufficient; force yourself to find alternatives
- Include a "do nothing" baseline: Clarify "what happens if nothing is done", to help judge whether the solution is really worth the investment
- Solutions must be feasible: Every solution should be technically implementable; do not include an obviously unreliable solution just to make up the numbers
- Consistent granularity: Alternatives should be choices at the same level (do not compare "use Redis" with "rewrite the entire system")
Solution selection output format
## 方案选择
### 备选方案
**方案 A：<一句话概括>**
<2-3 句话描述核心思路>
- 收益：<解决了什么，带来什么价值>
- 代价：<实现复杂度、风险、限制>
**方案 B：<一句话概括>**
（同上结构）
**方案 C：不处理（基线）**
维持现状，不做改动。适用于：<什么时候"不做"也是合理选择>
### 对比矩阵
| 维度 | 方案 A | 方案 B | 不处理 |
| --- | --- | --- | --- |
| 场景覆盖 | ... | ... | — |
| 实现复杂度 | ... | ... | — |
| 维护成本 | ... | ... | — |
| 扩展性 | ... | ... | — |
### 推荐方案
**推荐：方案 A**
理由：
1. <收益论据 1>
2. <收益论据 2>
3. <与场景分析中挑战的对应关系>
### 否决理由
- **方案 B**：<一句话说明为什么不选>
- **不处理**：<一句话说明为什么不能维持现状>
Solution selection quality requirements
- Benefits must correspond to scenarios: Each benefit point should be traceable to a specific challenge in the scenario analysis; do not write empty phrases like "improve user experience"
- Costs must be honest: Do not avoid the shortcomings of the solution—if implementation is complex, write that it is complex; if there is performance overhead, write about the overhead
- Reasons for rejection must be specific: Write "Solution B does not support requirement Y in scenario X", not "Solution B is not good enough"
- The recommended solution must have justification: Do not just say "recommend Solution A"; explain why A's benefits outweigh its costs
- Comparison dimensions must be distinguishable: If all options are evaluated the same on a certain dimension, that dimension is not worth listing
Visual Conventions
The following visual elements are the core means of expression in the design document; use them as needed.
ASCII Architecture Diagram
Used to express component relationships and module hierarchies. Use text code blocks:
调度层
├── engine/
│ ├── base.py # 抽象基类
│ └── adapter_a.py # 适配器 A
└── manager.py # 管理模块
State Machine / Flowchart
Use box-drawing characters (┌ ┐ └ ┘ │ ─ ►) to draw state transitions and flows:
(new) ──► active ──► paused ──► completed
▲ │
└──────────┘
(resume)
Directory Tree
Use text code blocks + indentation to represent file / directory structures:
module/
├── config.json # 配置文件
├── core.py # 核心逻辑
└── tests/ # 测试目录
Tables
Markdown tables are used for structured comparisons and attribute listings:
| 能力 | 方案 A | 方案 B |
| --- | --- | --- |
| 恢复会话 | 支持 | 不支持 |
| 导出记录 | ✗ | ✓ |
Code Blocks
- Target language: used for interface definitions, pseudocode, and key implementation snippets; includes docstrings and comments
- JSON / JSONC: used for data schemas, with inline
//comments explaining field meanings - Shell: used for command examples and user interaction flows
The language annotation of code blocks should match the language actually used by the project. The comment language follows the project's comment conventions.
Hard Content Rules
- Overview first: the first level-2 section must be
## 概述, explaining the background and motivation in 1-2 paragraphs - Do not invent modules: only reference modules that already exist in the project or that this document plans to create; do not fabricate them out of thin air
- File attribution table: if the document involves adding / modifying files, it must include a file attribution table indicating path, purpose, and whether it is under version control
- Cross-references: use relative path links when referencing other documents
- Line width constraint: body text must not exceed 120 characters per line (except code blocks and table rows)
- Respect project style: if the project has a CLAUDE.md or other conventions, the document style (comment language, spacing between Chinese and English, etc.) must be consistent with it
- Table column order: when comparing multiple options, organize as "capability / attribute | Option A | Option B"
Workflow
用户提出设计问题
│
├── 1. 理解上下文
│ ├── 阅读用户描述
│ ├── 如果描述模糊，向用户提问澄清（不超过 3 个问题）
│ ├── 阅读项目的 CLAUDE.md / README.md，了解项目规范
│ └── 阅读关联的已有设计文档，理解现有设计上下文
│
├── 2. 场景分析
│ ├── 按触发方式 / 用户角色 / 数据规模等维度拆解场景（2-5 个）
│ ├── 逐场景描述触发条件、期望行为、困难与挑战
│ ├── 与用户确认场景拆解是否完整、挑战是否准确
│ └── 输出场景汇总矩阵（草稿）
│
├── 3. 方案选择
│ ├── 提出 2-4 个备选方案（含"不处理"基线）
│ ├── 逐方案评估收益与代价
│ ├── 构建对比矩阵，明确推荐方案与否决理由
│ └── 与用户确认方案选择
│
├── 4. 确定文档结构
│ ├── 拟定一级标题
│ ├── 确定目标文件路径（用户指定 / 项目约定 / 推断）
│ ├── 根据场景分析 + 方案选择拆出核心设计章节
│ │ （每个挑战映射到至少一个章节，方案的关键决策也要有对应章节）
│ └── 判断是否需要 文件归属 / 与其他文档的关系 章节
│
├── 5. 填充内容
│ ├── 撰写概述（1-2 段话）
│ ├── 撰写场景分析章节（三级子章节 + 汇总矩阵）
│ ├── 撰写方案选择章节（备选方案 + 对比矩阵 + 推荐与理由）
│ ├── 逐个填充核心设计章节
│ │ ├── 选择合适的视觉元素（架构图 / 表格 / 代码块）
│ │ └── 确保代码示例符合项目注释规范
│ ├── 补充文件归属表（如有新增文件）
│ └── 补充交叉引用（如有关联文档）
│
├── 6. 自检
│ ├── 概述是否说清了"是什么"和"为什么"
│ ├── 场景分析是否充分（场景可辨识、挑战具体、映射到设计章节）
│ ├── 方案选择是否有说服力（备选方案可行、收益对应场景、否决理由具体）
│ ├── 章节顺序是否符合骨架
│ ├── 文件归属表是否完整（如适用）
│ └── 风格是否与项目已有文档一致
│
└── 7. 输出
├── 如果目标文件已存在：与用户确认后覆盖或追加
└── 如果目标文件不存在：新建文件并写入
Handling when a skeleton document already exists
If the target file already exists but has very little content (e.g., only a title), treat it as a "skeleton document":
- Keep the existing title and chapter structure
- Add detailed content under the existing chapters
- If it is necessary to add new chapters, append them after the existing chapters
- Confirm the supplementation plan with the user before writing