# Software Designer

> 创建、补全和从现有代码逆向生成可追踪的 Markdown 软件设计文档，覆盖系统上下文、架构、模块、数据、接口、核心流程、质量属性、部署、风险与验证，并用 Mermaid 表达必要视图。Use when 用户要求编写软件设计说明书、概要或详细设计文档、技术设计文档，依据需求形成设计，依据仓库代码、配置、数据库迁移和测试还原现状设计，或维护已有设计文档；不用于只画单张图、只做代码审查、只写需求文档或直接实现功能。

- **Type:** Skill
- **Install:** `agentstack add skill-betterlmy-agent-skills-software-designer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [betterlmy](https://agentstack.voostack.com/s/betterlmy)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [betterlmy](https://github.com/betterlmy)
- **Source:** https://github.com/betterlmy/agent-skills/tree/main/skills/software-designer

## Install

```sh
agentstack add skill-betterlmy-agent-skills-software-designer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Software Designer

## 工作模式

开始前判断任务类型：

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

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

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

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

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

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

## 开始前

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

## 通用工作流

### 1. 建立输入与证据清单

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

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

### 2. 选择文档深度

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

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

### 3. 形成设计

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

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

### 4. 绘制必要图表

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

### 5. 标注事实状态

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

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

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

### 6. 验证与交付

交付前检查：

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

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [betterlmy](https://github.com/betterlmy)
- **Source:** [betterlmy/agent-skills](https://github.com/betterlmy/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-betterlmy-agent-skills-software-designer
- Seller: https://agentstack.voostack.com/s/betterlmy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.