Software Designer

工作模式

开始前判断任务类型：

1. 正向设计：根据需求、约束和目标提出可实施设计。
2. 代码逆向：根据现有代码、配置、数据结构、部署文件和测试恢复当前设计事实。
3. 增量维护：以现有设计文档为基线，补充或更新受变更影响的章节。

任务同时包含“现状”和“目标”时，分别输出“现状设计”和“目标设计”，不要混写为已经实现的事实。

文档语义不随形成方式改变

正向设计、代码逆向和增量维护只是设计事实的不同取得方式，不是三种文档语义。无论采用哪种方式：

• 背景描述系统或功能为什么存在以及解决什么问题；
• 目标描述需要达成的业务能力和质量结果；
• 范围描述系统责任、外部边界和明确不承担的职责；
• 架构、模块、流程、数据、接口和质量属性直接描述设计对象。

不得把“分析代码”“还原实现”或“生成文档”写成系统背景、建设目标或核心范围。代码逆向只影响证据规则，并在文档信息、事实状态或设计依据中记录；只有同时描述现状和目标方案时才使用 As-Is/To-Be 结构。

开始前

1. 读取当前目录适用的协作指令、目标文档和文档约定。
2. 确认读者、系统边界、设计深度和交付位置；能从上下文可靠判断时不要追问。
3. 用户要求落盘但未指定位置时，优先沿用仓库文档目录；没有约定时使用 docs/software-design.md。
4. 检查工作区状态，保留无关的现有修改。设计任务不授权修改业务代码。
5. 完整设计文档必须读取 references/document-standard.md。
6. 代码逆向任务还必须读取 references/reverse-engineering.md。

通用工作流

1. 建立输入与证据清单

• 正向设计：整理业务目标、范围、角色、关键用例、质量属性、约束和验收标准。
• 代码逆向：整理入口、模块、调用关系、数据结构、接口、集成、运行配置、部署和测试证据。
• 增量维护：对比变更与现有文档，建立“变更 -> 受影响章节 -> 验证证据”清单。

缺少的信息按影响处理：仅当该信息必须由用户选择，且不同答案会使当前交付互不兼容、引入显著安全或数据风险，或导致无法验收时先澄清。技术栈、容量、SLA 等非阻塞未知项先给出技术中立设计，标记为“建议”或“待确认”，继续完成可证实部分。

2. 选择文档深度

• 简版：单模块或小功能，保留边界、流程、数据/API、风险和验证。
• 标准版：默认选择，覆盖系统上下文、架构、模块、核心流程、数据、接口、质量属性、部署和追踪。
• 详细版：仅在用户明确要求或高风险系统需要时，补充状态机、异常矩阵、容量计算、迁移和灾备细节。

不要为了套模板制造空章节。完整不等于冗长；优先描述影响实现和验收的决策。

3. 形成设计

1. 先写系统或功能的真实背景、建设目标、责任范围、范围外事项和约束；不得用分析任务代替系统目的。
2. 给出系统上下文和总体架构，说明组件职责、依赖方向及关键决策理由。
3. 只对核心模块展开业务规则、状态、数据和接口；辅助模块保持摘要。
4. 对核心成功路径和关键失败路径建模，明确事务、一致性、权限和幂等边界。
5. 补充性能、安全、可用性、可观测性、部署、迁移、测试和验收中确有影响的内容。
6. 建立需求或用例到模块、数据、接口和测试的追踪关系。

使用 templates/software-design-document.md 作为可裁剪骨架。需要校准篇幅和图表密度时读取 examples/student-management-system.md，不要复制其中的领域结论或技术选型。

4. 绘制必要图表

• 三个及以上组件存在依赖时，使用 Mermaid 架构图或流程图。
• 存在关系型持久化模型时，使用 E-R 图展示核心实体、主外键和基数。
• 核心业务跨越多个参与者或组件时，使用时序图展示成功与关键失败分支。
• 存在重要生命周期时再增加状态图；不要为装饰而画图。
• 每张图只表达一个视角，图前说明目的，图后解释关键结论。名称必须与正文一致。

5. 标注事实状态

• 已确认：由需求、源码、配置、迁移、测试或运行证据直接支持。
• 推断：由多个证据推导但未被直接声明；必须写出依据。
• 建议：面向目标设计的方案；必须写明理由、代价和需要确认的责任角色，不得表述为现有事实。
• 待确认：缺少证据且会影响设计或验收；集中列入待确认项。

禁止把推荐方案写成现有实现，也禁止仅凭目录名、类名或接口名断言运行时行为。

事实状态用于保证准确性，不用于把正文组织成审计报告。有充分证据的普通设计事实直接陈述；推断、建议和待确认必须显式标记。测试文件存在只证明“有测试证据”，只有实际执行成功才能写“本次测试通过”。

6. 验证与交付

交付前检查：

• 范围、术语、模块名、图表名、接口和数据对象前后一致；
• 背景、目标和范围描述设计对象，没有被分析或逆向任务说明替代；
• Markdown 围栏、相对链接和 Mermaid 代码块闭合；可用本地渲染器时执行语法验证；
• 逆向结论包含可定位的文件与行号，推断、建议和待确认项没有伪装成事实；
• 核心需求至少能追踪到模块、接口或数据，以及对应验证方式；
• 没有无依据的版本号、容量指标、SLA、基础设施或外部系统；
• 文档规模与任务相称，删除重复说明和无内容章节。

完成报告说明文档位置、使用模式、图表和核心章节、实际执行的检查、仍待确认的内容。