SuperAPI AI 工具集

design-doc

写作与研究

查看项目

更新于 10-15 21:37

技能介绍

用途:把产品与技术上下文转化为一份最小、可执行的设计文档,供实现型智能体安全落地。

主要能力:从对话中提取问题、目标、约束、非目标、决策与理由、被否决方向及未决事项;阅读仓库说明、愿景、架构、代码、测试、schema 与配置,先搜索再推断,核实路径、签名、归属与集成点;仅在会实质影响范围、架构、兼容性、安全或故事边界且无法自行发现时,批量提出简洁问题,否则写明假设;综合出所选行为与契约,优先沿用仓库既有模式;编写带稳定 ID 的规范用户故事,使每个故事可独立实施,并尽量减少故事数量。

使用方式:先完整阅读共享设计契约,再按工作流撰写。验证时从已安装或仓库技能集中解析 design-to-issues/scripts/story_contract.py 并运行: python3 <story-contract-script> <design-doc>
--repo-root <repository-root> --mode author 修复所有验证失败后再报告完成。默认保存为 docs/design/<short-kebab-case-name>.md,除非用户或仓库指定其他路径。新内容与修订内容均保持 Draft,本技能不会将其提升为 Revised。

文档结构:按需选用 Problem and Goals、Scope and Non-Goals、Decisions and Rationale、Architecture and Contracts、Integration and Behavior、Risks and Verification、Open Questions、User Stories、Changelog 等章节,可合并或省略无关部分;在重要时纳入安全、隐私、数据归属、迁移、兼容性、性能、可观测性、发布与回滚;仅在能消除实现歧义时使用精确示例、数据形状、序列或图,并把拟议接口标注为 proposed。

故事要求:遵循共享契约中的故事形状与依赖语法;行为结果放入 Acceptance Criteria,实现指引放入 Implementation Context;标准须二元且可观察,不得用文件位置、lint 通过或“工作正常”等模糊表述;在 Verification 中按故事需要指明测试、命令、浏览器/设备检查、迁移或运维证据;仅在故事改变文档或运维面时纳入相应工作;修订共享架构或契约文字时同步更新所有受影响故事;跨修订保留既有 ID。

修订行为:处理评审产物时,逐条评估阻塞性发现,以最小一致改动满足必要不变量;非阻塞建议仅在要求或明显有益时采纳;详细处置留在评审产物或协调交接中,设计文档只加一行简洁 changelog,例如:

  • 2026-07-28: Addressed review pass 2; clarified token ownership and updated AUTH-002. 文档保持 Draft 以便独立后续评审。

报告:返回设计路径、决策与故事顺序摘要、验证结果及仍需用户决定的事项;不要启动 issue 同步或实现。

限制:资料未提供具体收费、价格、平台支持范围或效果数据。