SuperAPI AI 工具集

writing-plans-conventions

编程与开发

查看项目

更新于 10-22 16:17

技能介绍

用途

该技能用于多步骤开发任务的计划编写阶段,须在写计划正文之前、动手写代码之前调用。它本身不负责规格到计划的完整流程:实际流程由 superpowers:writing-plans 承担(包括文件结构、任务粒度、验证步骤)。本技能是叠加在其之上的必要前置步骤,与 roadmap-conventions 之于 superpowers:writing-roadmaps 的关系相同:在起草任何一个实现任务之前,先确定计划涉及哪些技术栈,加载各技术栈的约定技能,使计划中的代码片段从一开始就按真实约定编写,而不是先写通用模式、事后“纠正”。

技术栈检测与所需技能

根据规格实际要求的内容(文件类型、框架装饰器或 API)判断技术栈,而非依据仓库整体技术清单——全栈单体仓库中的计划可能只涉及一侧。

计划涉及 按顺序调用
NestJS 代码(服务、控制器、DTO、模块、守卫) nestjs-best-practices,然后 nestjs-personal-conventions(如已安装)
Angular 代码(组件、服务、表单、模板) angular-best-practices,然后 angular-personal-conventions(如已安装)
两者都有 调用两对技能
都不涉及(纯基础设施、文档、配置、SQL 迁移) 无适用技术栈技能,仅使用 writing-plans 继续

若某技术栈的个人约定技能未安装,可仅调用最佳实践技能继续,不视为阻塞。

使用方式与顺序

在呈现实现任务之前调用本技能及其所需技术栈技能;计划要求的“修改前/修改后”代码块在首次书写时就应反映已加载的约定。若草稿完成后再加载技术栈技能,则每个任务的代码都需二次调整,应一次按正确顺序完成。

使用原生 Plan Mode。写计划前阅读与其范围相关的所有规则/技能:通用约定,以及计划特定领域涉及的约定;由单个智能体编写整个计划,须预先了解所有适用约定,而不仅是自己实现的部分。计划准备好后等待标准审查(ExitPlanMode)并按结果处理再保存。

必需的计划结构

计划必须包含:目标、架构、文件地图、实现任务、测试场景、约束、一次最终验证。缺少任一项即为不完整计划。

最终验证在所有任务实现后仅执行一次,作为最后一步,运行构建、类型检查、lint 和测试;不逐任务执行,也不在写完单个文件后做范围/目标运行(例如不用 -- <pattern> 只跑单个测试)。添加测试的任务在测试代码写完即结束,运行留到最终验证。

每个实现任务须包含具体代码,而非仅文字描述。对每个涉及文件展示“修改前”(现有代码及位置)与“修改后”(确切新代码)对照,新文件则给出完整代码块。仅用文字叙述改动的任务不充分——计划是实施者机械执行的产物,代码须在写计划时确定。文字可解释原因,但不能替代代码。

每个新增或改变行为的任务配一个专门测试编写任务,交由独立的测试编写角色/通道处理,默认不遗漏测试覆盖(见 testing-philosophy)。

计划中不添加提交步骤:不在任何任务中加入 git add、git commit 或创建 PR。

文件放置与清理遵循 repo-workflow-conventions:计划文件放在项目根目录,命名为 YYYY-MM-DD-<feature-name>.md,计划完全实现后删除,除非用户明确要求保留。

常见错误与修正

  • 直接调用 superpowers:writing-plans、把技术栈技能当作可选:只要计划涉及某技术栈,最佳实践与个人约定(如有)均为必需,不是判断项。
  • 只在任务“看起来足够复杂”时才加载技术栈技能:技术栈检测是二元的(涉及/不涉及),不是复杂度阈值。
  • 先起草任务代码,再加载技术栈技能“检查”:应在起草前加载,因为计划中的代码块本身就需要合规。
  • 任务描述只用文字叙述改动而无实际代码:应给出修改前/后代码。
  • 把测试覆盖留到“后续”:在同一计划中加入独立测试编写任务。
  • 在任务中加入 git 提交步骤:移除,提交仅在用户明确要求时进行,不作为计划步骤。