Design Documentation

---
name: design-documentation
description: Use when 编写或修改特性 RFC、架构、系统、功能或详细设计说明书；普通实验报告用 cinderx-optimization-report。
---

# 设计文档编写

按用户要交付的设计层级选择一个模板，只读取相关材料。局部修改沿用现有文档结构；详细设计不要求先补齐整套上游文档。

| 设计范围 | 模板 |
|----------|------|
| 特性动机、目标、方案与风险评审 | [特性 RFC](references/feature-rfc-template.md) |
| 整体模块、交互和部署边界 | [架构设计](references/architecture-design-template.md) |
| 需要独立成文的系统约束、可靠性、安全或生命周期 | [系统设计](references/system-design-template.md) |
| 功能域、功能项、模块接口和影响 | [功能设计](references/function-design-template.md) |
| 组件内部行为、数据与实现接口 | [详细设计](references/detailed-design-template.md) |

## 交付范围

沿用用户指定路径或项目约定；新文档没有约定时可放入 `docs/design/YYYY-MM-DD-<topic>-<type>.md`。模板是章节参考；只有用户要求完整标准说明书或项目已有固定格式时，才保留所有章节、元信息、编号与修订记录，不适用项写“不涉及”。普通设计可省略无关章节，不编造产品版本、密级或审批信息。

关键决策关联代码、上游约束或可信来源，解释方案的适用边界、风险和验收方式。可靠性、安全性、性能等分析按实际影响展开；有实质影响时不能省略。

完整 RFC、架构或功能设计还需按 [视图与层级规范](references/design-views.md) 保持包含/依赖关系、聚合接口、时序调用和模型链一致；局部修订只核对受影响部分。

## 各层重点

- RFC 对齐动机、目标与非目标、总体方案、风险和开放问题；保留状态与已有 Issue/PR 来源，不因没有上游文档而阻塞起草。
- 架构设计关注系统/组件结构、外部边界、交互和部署。4+1 视图按需要采用。
- 功能设计关注模块能力、逻辑接口、输入输出和验收口径。可采用总-分结构：前部从外部视角用通俗易懂的语言概括面向谁、解决什么问题，再在后部展开实现方案、接口、DFX 和影响点。需要比较流程、关系或边界时用 mermaid 或表格。
- 功能跨多个模块时说明职责和交互；不因跨模块就认定拆分错误。实现细节留到详细设计，必要时用伪代码帮助说明。
- 详细设计描述内部接口、行为和数据模型，可具体到目标语言、运行环境和代码路径，应能指导开发与测试。

交付前检查决策、接口、图表和验收口径是否一致，修正文档自身的问题后给出路径与待定事项。