SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场solution-design

solution-design

编程与开发

查看项目

更新于 10-26 16:18

技能介绍

用途

Solution Design 是一份指导性“指令契约”，用于引导新建或既有软件项目的工程与设计工作。它的目标是帮助使用者从问题与需求出发，逐步形成可验证的设计与交付计划，同时让文档的详尽程度与项目的规模、复杂度、风险和工作方式相匹配。

该技能强调：文档类型描述的是职责，并不意味每种类型都必须拆成独立文件。

主要能力

  • 激活契约：在用户启动新项目/新功能并需要决定设计，要求记录架构、数据、API、需求（PRD）、决策（ADR）或交付计划，或要求“软件设计”“PRD”“SDD”“设计文档”“记录系统”等类似内容时加载；也希望把设计与现有仓库对齐时使用。不适用于无需记录设计决策的编码或 PR 审查。
  • 硬性规则：从意图出发；先检视再写作（有仓库时查看结构、文档、配置、模型、迁移、测试与相关代码，不盲目替换既有文档）；绝不虚构（业务规则、表、字段、端点、容量、性能目标、角色、权限、控制等，需区分已验证事实、已接受决策、提案、假设与开放问题，重要但未知的内容标记为“待定义”）；不预设架构；最小充分文档；单一事实来源；迭代式设计；记录决策而非每个代码细节；不混淆“记录”与“验证”；使用用户语言并以 Markdown 为默认格式。
  • 文档级别决策门：根据观察到的信号选择级别。
    • 轻量级：边界清晰的领域、少量集成、少量人员、可管理的失败影响 → project-design.md（需求+数据+API+架构作为章节）+ README.md；仅当第三方消费 API 时才提供 OpenAPI。
    • 标准级：多个模块/流程、多名协作者、相关集成 → prd.md + system-design.md；database-design.md 与 openapi.yaml 仅在能增加独立细节时提供；复杂变更写 TDD，相关决策写 ADR。
    • 严谨级：多团队、复杂领域、严格的合规/安全/隐私要求、高可用要求、精细迁移 → PRD、SDD、DBDD、API 契约、TDD、ADR、测试策略、部署、可观测性、可追溯性。
    • 混合级：规模小但某一领域高风险 → 仅在关键领域保持严谨，其余轻量。
    • 上下文不足：先轻量，记录假设，待具体需求出现时再扩展。
    • 评估因素（定性判断，规模本身不决定级别）：领域复杂度与不确定性、失败影响与可恢复性、数据敏感性/完整性/容量、外部集成、安全/隐私/合规/可用性/性能、协作人数、变更概率与成本。
  • 合并或拆分文档的判断因素：读者/消费者是否相同、变更与归属是否一致、是否需要版本管理与工具校验或发布、复杂度/规模是否适合单章节、是否需要可追溯/审计/访问控制。规则为先合并，仅在出现“拆分”列因素时才拆分；不为套模板而创建空文件或独立文件。
  • 与领域技能交接：跨流程（级别、文档组织、发现）归本技能；具体 API 设计规则交给 api-design 技能；数据库规范化、索引、迁移、引擎交给 database-design 技能；前端组件、状态、UX、可访问性、UI 测试交给 frontend-engineering 技能（如可用）。
  • 专业化规则：涉及数据（DBDD、ERD、迁移、引擎）、用户/角色/权限（功能访问需求 vs RBAC/JWT 技术策略）、详细技术设计（图表、TDD、OpenAPI、ADR、可度量 NFR）时，加载 references/specialized-rules.md 并按需应用。底线规则：绝不虚构角色/权限或访问规则；功能访问需求归 PRD，技术策略归 SDD；已记录的约束既不等于已实现也不等于已验证。

使用方式

  1. 确定起点：新项目走 greenfield 工作流（加载 references/greenfield-workflow.md），从问题、用户、预期结果与约束开始，在理解需求前不生成架构、表或端点；既有项目则检视仓库，把代码、配置、测试与迁移视为当前状态的证据，区分当前状态、拟议设计与未来工作；新功能则审视上下文、惯例与既有设计。缺失非阻塞信息时记录假设与开放问题，仅在歧义实质阻碍决策时才询问用户。
  2. 分类需求与级别：加载 references/document-types.md 识别职责（类型 ≠ 文件），应用文档级别决策门。
  3. 收集可用上下文：检视相关文件，把重要未知项标记为“待定义”，不因次要细节阻塞工作；对影响架构、安全、持久化、互操作或变更成本的决策，按级别成比例地说明备选方案与权衡。
  4. 选择文档组织方式：采用能服务项目使用者的最小结构，各级别示例布局见 references/templates.md；若仓库已有惯例则尊重之，除非有明确理由改变。
  5. 写作或更新：以 references/templates.md 为参考而非强制形式，省略无关章节；合并时用清晰标题保留不同目的且不重复内容。
  6. 验证一致性：需求/规则/标准无矛盾；领域—数据—接口—流程连贯；端点/DTO/错误/HTTP 码与规范来源一致；链接、图表与引用有效（不虚构目标）；事实/决策/提案/假设/问题相互区分。
  7. 准备增量交付：适用时把设计拆成小里程碑或垂直切片，附验收标准与可验证测试；不虚构日期或精确估算；标记阻塞项与待定的高影响决策。
  8. 按输出契约交付。

适用场景

  • 启动新项目或新功能并需要决定设计。
  • 需要记录架构、数据、API、需求（PRD）、决策（ADR）或交付计划。
  • 用户要求“软件设计”“PRD”“SDD”“设计文档”“记录系统”等。
  • 希望把设计与现有仓库对齐。

限制与不适用

  • 不适用于无需记录设计决策的编码，或 PR 审查。
  • 不虚构业务规则、表、字段、端点、容量、性能目标、角色、权限或控制。
  • 不预设架构，不无缘由推荐微服务、模式、框架、技术或基础设施。
  • 不默认生成所有工件，不创建空文件。
  • 不声称已审查代码、运行测试或验证需求，除非确实做过。
  • 不虚构日期或精确估算。
  • 具体的 API、数据库、前端工艺规则由对应技能负责（如可用）。

输出契约

结束时报告：创建或修改的文件；选择该文档级别的理由（以及合并工件时各职责落在何处）；最重要的假设；待定决策与阻塞项；建议的下一个增量。

质量准则

当文档能帮助理解要构建什么或现有系统如何工作、识别重要决策与约束、定位契约并验证需求时，文档即就绪。文件数量与长度不是质量指标，应优先采用最简单、能保持设计可理解、可验证且易于更新的结构。

参考资料

  • references/greenfield-workflow.md：新项目的迭代流程（发现 → 需求 → 领域 → 设计 → 交付）。
  • references/document-types.md：各工件类型（PRD、SDD、TDD、DBDD、OpenAPI、ADR）的职责及何时拆分。
  • references/templates.md：各级别的参考模板（集成的轻量文档、PRD、SDD、DBDD 等）与拆分标准。
  • references/specialized-rules.md：数据、用户/角色/权限以及技术设计的具体规则。
  • references/philosophy.md：底层推理、动机与 v1.2.1 映射（各规则背后的原因）。