SuperAPI AI 工具集

design-docs

写作与研究

查看项目

更新于 10-15 21:08

技能介绍

用途:为单个系统维护一份持久的意图声明——它为何存在、术语含义、必须始终成立的条件,以及它刻意不做什么。文档位于 thoughts/<username|shared>/design-docs/<system-slug>.md,无日期前缀,在原位修订,不用新的带日期文件取代。它具规范性:desplega:code-reviewing 的 Spec 轴会依据 Invariants 章节检查 diff,researching/planning/one-shot 必须 read-and-abide。

结构与顺序(模板在 cc-plugin/base/skills/design-docs/template.md):Purpose,一段话说明系统用途与面向对象,超过两段说明边界可能有问题;Glossary,核心术语一行定义,并列出应避免的别称,零实现细节;Invariants,编号(I1、I2…)且每条可测试,评审者能对 diff 回答是/否,属规范而非风格;Boundaries & Non-goals,明确不做的事及被拒范围与拒绝原因;Interfaces / Seams,其他系统如何接入,仅高层名称与职责;Decision log,每段一段的 ADR,最新在前,写 context → decision → consequence,只记难以逆转、出人意料或真正权衡的决策;Amendment log,每行一次改动的日期、改动内容、驱动它的计划或会话。

创建:按需创建,采用 grilling 式问答(规则同 desplega:brainstorming)。事实与决策分开——能查到的不要问,当前行为、既有术语、实际边界可由后台子代理(按 desplega:delegate-work 路由)调研后起草;只有真正的决策(命名、不变量强度、范围拒绝)才通过 AskUserQuestion 交给用户,且每题附推荐答案。按模板逐节起草,最后用 /file-review:file-review <path> 让用户批注草稿。

修订:设计通过工作变动,而非漂移。当计划或 one-shot 有意改变设计时,更新文档是工作的一部分——同一会话内追加 Decision log 条目(若确为真实决策)与 Amendment log 行。设计上没有周期性漂移审计,执行依靠 read-and-abide 加代码评审的 Spec 轴。

Read-and-abide(执行):任何触及某系统的技能,若该系统有设计文档,须先读;Glossary 是书写该系统内容的规范词汇;不得违反,Invariants 与 Boundaries 同时约束计划与代码;冲突须标记而非静默绕过——若任务需要破坏不变量或越过边界,作为显式决策提交用户(若采纳则修订文档);若现有代码与文档矛盾,报告“文档说 X、代码做 Y”,由用户决定哪个错。已接入 desplega:researching、desplega:planning(read-and-abide 规则)、desplega:one-shot(Step 2)、desplega:code-reviewing(Invariants 作为 Spec 轴来源)。

限制:资料未提供具体安装命令、收费方式、支持平台与版本要求。