用途
该技能用于多步骤开发任务的计划编写阶段,须在写计划正文之前、动手写代码之前调用。它本身不负责规格到计划的完整流程:实际流程由 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 提交步骤:移除,提交仅在用户明确要求时进行,不作为计划步骤。