DeepChat SDD 是一个用于 DeepChat 项目的规格驱动开发技能,适用于在实施重大变更前建立共享上下文与可长期保留的决策记录。
用途
该技能应在对 DeepChat 源代码、配置、测试、文档、构建脚本、发布流程或项目结构进行重大变更前使用,尤其是需要共享上下文或持久决策记录的工作。对于琐碎或高度局部化的改动,除非开发者明确要求,否则应跳过 SDD,例如视觉/样式修复、文案修改、小型 UI 布局调整、归属模块清晰的简单局部逻辑改动、不改变项目方向的常规文档编辑,以及发布流程已覆盖的发布元数据。若范围不明确,应先检查再询问是否需要 SDD,而不是默认创建产物。
目标分类
每个目标创建一个 kebab-case 文件夹:新能力、用户可见行为、集成或需要共享计划的大型工具归入 docs/features/<goal>/;复杂缺陷、回归、失败测试、CI 失败、可靠性问题或提示/运行时问题归入 docs/issues/<goal>/;重构、迁移、依赖边界、共享契约、运行时架构或跨模块设计归入 docs/architecture/<goal>/。若一个请求包含多个独立目标,应拆分为不同文件夹。现有架构参考文档(如 docs/architecture/agent-system.md)保持原位,新架构目标使用子文件夹。只有当根因、影响范围或修复路径足够复杂、未来开发者能从书面记录中受益时,缺陷才值得走 SDD;简单样式缺陷或明显的局部逻辑修复应直接实现。若缺陷修复引入新的用户可见能力、数据迁移、公共契约或跨模块重设计,则应归类为功能或架构。
必需产物
功能与架构目标使用两个产物:spec.md 是规范性 RFC,涵盖上下文、目标、非目标、设计、归属、接口、数据流、不变量、兼容性、验收标准与开放问题;plan.md 是有序实施步骤与实时完成状态,随后是整体变更审查、验证选择、清理与质量门禁。不要创建 tasks.md,plan 是唯一的执行跟踪器。复杂缺陷目标通常使用一个文件:spec.md 包含问题描述、影响、根因或疑似位置、修复设计、简明实施清单、验证结果,以及关联的 GitHub issue(若存在)。仅当复杂缺陷有多个可独立跟踪的实施切片时才添加 plan.md。绝不要添加 tasks.md。所有 [NEEDS CLARIFICATION] 标记必须在实施前解决。若请求的变更很小,宁可跳过 SDD 也不要创建象征性产物。
产物边界
spec.md 应作为 RFC 编写,必须解释足够的实施方向以约束局部代码决策,但不能变成逐文件任务清单。验收标准描述可观察结果或可独立验证的契约,而不是测试清单。plan.md 同时作为计划与任务跟踪器,组织为有序的复选框章节,步骤应是连贯、可审查的实施切片,包含目标、归属边界、必要指导、依赖(若有)与完成条件。引用 spec 而不是重复其设计。
GitHub Issue 同步
默认不同步 GitHub issue。Issue 同步是后续记录,不是本地 SDD 或实施的关卡。仅当开发者明确要求,或在 SDD 产物写完或实施完成后询问并获得批准时,才创建或关联 GitHub issue。符合条件的工作:仅复杂缺陷;简单样式缺陷和明显的局部逻辑修复不应创建 issue。仅全新功能或重大功能重写;单一操作、小型行为调整和普通调整不应创建 issue。若资格不明确,在理解工作后询问开发者。绝不因为本地安装了 gh 并已认证就自行授权创建 issue。获得批准后:功能 issue 使用 [feature] 标签,缺陷 issue 使用 [bug] 标签;若标签缺失且 gh 有权限,先创建标签;在 SDD 产物中记录 issue URL 或编号。若 gh 不可用或未授权,继续仅本地进行,并且仅在请求或批准同步时注明未创建 GitHub issue。为关联工作创建 PR 时,在 PR 正文中包含 Closes #NNN,以便合并后 GitHub 自动关闭 issue。
工作流程
先检查当前代码与文档。判断工作是否足够重大以走 SDD;琐碎/局部改动跳过产物。需要 SDD 时,按分类规则选择目标文件夹。编写或更新 RFC,并解决所有可能改变实施的问题。对于功能、架构或多切片缺陷工作,编写一个有序实施计划,不要单独的任务列表或预先测试矩阵。保持实施与现有 DeepChat 模式一致:主进程 Presenter 边界、类型化的 shared/contracts/*、渲染层 api/*Client、UI 字符串使用 Vue 3 Composition API 与 i18n。对于改变或替换历史功能的架构工作,若该功能的 spec.md 仍是维护中的契约,则更新它。在决定是否编写新测试代码前完成计划实施。现有检查可随时运行。对照 spec 审查整体变更,关注隐藏副作用、兼容性、失败行为、性能、安全、命名与维护成本。选择最小有用验证,移除临时验证,仅为符合条件的行为或契约添加持久测试。随着连贯实施切片落地,更新 plan.md 或复杂缺陷 spec 清单。仅在文档或实施明确范围后,询问是否同步符合条件的 GitHub issue,除非开发者已要求同步。当应用代码、测试、i18n 或项目文档变更时,在交接前运行 pnpm run format、pnpm run i18n、pnpm run lint 和 pnpm run typecheck。
实施优先验证
实施优先意味着在决定是否编写新测试前完成计划实施,并不禁止在开发期间运行现有测试、类型检查、lint、构建或手动检查。实施前编写新测试代码属于例外,仅在开发者要求 TDD、需要最小可执行复现来理解复杂失败,或迁移、并发、恢复、协议兼容性需要刻画当前行为时使用。在 plan.md 或复杂缺陷 spec 中用一句话记录原因。实施后可在以下选项中选择:现有测试与静态或构建检查;必须在交接前移除的临时探针、脚本或测试;以及针对用户可见行为、已文档化的跨模块契约、持久化或迁移、生命周期或并发、恢复、安全边界或已证实回归的最小持久回归测试。不要保留镜像私有控制流、断言偶然调用顺序、通过 mock 重复实现或仅为提高覆盖率而存在的测试。宁可没有新测试,也不要低价值的实现耦合测试。
文档卫生
不要在普通功能、缺陷或架构工作中进行广泛的 SDD 清理。仅当开发者明确要求清理或整理 SDD 文档时,才使用单独的 deepchat-sdd-cleanup 技能。将现有 tasks.md 文件视为遗留,仅在该目标被积极更新时迁移。将剩余工作合并到现有 plan.md;若没有,则在 spec.md 中保留单切片复杂缺陷清单,并为功能、架构或多切片缺陷工作创建 plan.md。不要在无关工作中进行全仓库迁移。在当前目标期间,若直接受影响的历史 spec 仍是活跃契约,则更新它们。