# Solution Design

> 基于已确认需求和仓库事实，为涉及跨模块、公共接口、数据流、持久化或迁移决策的软件变更生成复杂度受控、可验证且决策完整的工程方案。适用于“02 实现方案设计”“第二阶段”“把需求转成工程方案”和中大型项目设计；不用于可由局部修改完成的简单任务、正式 Ticket 拆分或代码评审。

- Skill: `entropy-r/solution-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add entropy-r/solution-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/entropy-r/solution-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Entropy-R (https://skillmd.com/u/entropy-r)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/entropy-r/solution-design

---


# 02 实现方案设计

把已澄清需求转换为可评审、可实施的工程方案。本阶段只设计，不修改代码、不发布任务、不创建外部资源。

## 调用边界

- 当变更涉及多个模块、公共契约、持久化模型、关键数据流或迁移顺序，需要实施前作工程决策时使用本 skill。
- 简单、局部、可逆且不涉及关键接口决策的修改只需简短计划，不为进入三段式流程而扩展任务。
- 需要正式拆票时使用 `$to-tickets`；审查已有方案时使用 `$solution-review`；评审已完成代码时使用 `code-review`。

## 输入门槛

优先读取 `$requirement-intake` 的输入包和用户补充回答。上下文中已有等价信息时直接使用；关键目标、范围或验收口径仍不清楚时，列出阻塞项并返回需求澄清阶段。

## 证据与复杂度约束

1. 设计依据按优先级来自已确认需求、现有代码与契约、ADR、测试或可复现现象，以及明确的安全约束；不把猜测当成需求。
2. 优先选择能满足当前验收标准、符合现有结构的最小方案，不顺手重构，不为未来可能性增加灵活性。
3. 每个新增模块、层次、抽象、配置项、扩展点、兼容路径、重试、回退或数据源都必须能追溯到上述依据；缺少依据时从方案中移除。
4. 发现范围外问题时仅在确实影响当前决策时记录为非阻塞项，不扩展本次设计。

### 失败与防护

- 权威数据、系统不变量、必需配置和安全边界失败时，设计为显式失败或失败关闭，不用默认成功、空结果或替代身份掩盖问题。
- 受控降级只用于产品需求或现有架构明确允许的非关键能力；触发条件必须明确、结果可观测，且不得伪造成功、吞掉不可恢复错误或引入第二事实源。
- 保留当前任务需要的输入校验、鉴权、事务与并发约束、外部超时、可恢复故障的有限重试、资源清理和响应结构校验；不要以“避免过度防御”为由删除有效护栏。

## 设计流程

1. 只读检查仓库结构、相关入口、调用关系、接口、数据模型、测试方式、项目规范和 ADR，不询问可从环境发现的事实。
2. 固定目标、验收标准、范围、非范围和仍需沿用的假设，并把每项验收条件映射到可观察行为。
3. 选择符合现有模式的最小方案；只有存在会实质改变成本、风险或公共契约的路线分歧时，才列出备选与推荐。
4. 仅设计本次会改变的模块职责、接口、数据结构和数据流；安全、并发、幂等、兼容、迁移与恢复只在任务实际涉及时展开。
5. 设计与风险相称的验证方式，优先聚焦受影响路径；需要全量测试、性能基准或人工验收时说明原因。
6. 仅在存在依赖、分阶段迁移或发布顺序时给出阶段级实施顺序，不在本阶段生成正式 Ticket。

## 自适应输出

使用足以安全实施的最短结构，省略空标题和与任务无关的内容。

始终包含：

- **方案摘要**：目标、使用者、验收标准和明确非范围。
- **关键设计**：按子系统或行为说明必要变更；只列本次会变化的模块、数据流、接口与失败语义。
- **验证方案**：关键正常路径、边界、失败场景和必要的人工验证。
- **假设与风险**：沿用假设、实施前阻塞项和已接受风险。

按需包含：

- 公共接口、持久化模型或外部契约发生变化时，明确输入、输出、错误和兼容策略。
- 任务确实涉及安全、并发、迁移、回滚、恢复或受控降级时，说明对应策略和证据。
- 存在三个以上相互依赖步骤、迁移窗口或发布约束时，给出实施顺序与阶段交付结果。

## 完成检查

- 每项验收条件都有对应设计行为和测试或人工验证方式。
- 每项新增复杂度都有当前需求、既有契约、事实证据或安全要求支撑。
- 删除某个设计项不影响验收时，已经删除该项。
- 公共接口与实际涉及的失败语义明确，必要护栏没有被削弱。
- 输出没有模板填充内容，实施者无需再作关键产品或架构决定。

满足以上条件后进入 `$solution-review`。

## 平台兼容性

- 支持平台：Windows + macOS + Linux。
- 方案中的命令、路径和部署方式必须明确目标系统。