writing-plans 是一项面向多步任务的计划编写技能,适用于在编写代码之前、已经拿到规格或需求的阶段。其核心是:计划应描述意图、行为与契约,说明要构建什么以及为何选择该方案,而把具体如何写代码留给掌握完整仓库上下文的实现者。
主要能力与要求:宣布正在使用该技能;在专用工作树中运行;计划保存至 docs/quirk/plans/YYYY-MM-DD-<feature-name>.md(用户自定义位置优先)。计划遵循无代码规则,禁止包含可运行实现代码或完整测试主体;每个涉及代码的步骤给出确切文件路径、行为目标、契约(前置/后置条件、不变量、错误行为)以及可观测的验收检查。仅当字面文本本身就是契约时才允许代码,且需打标签:CONTRACT:、SCHEMA:、COMMAND:、REGEX:、CONFIG:、PSEUDOCODE (justified):。
使用方式:先做范围检查,若规格覆盖多个独立子系统,建议拆分为多个计划。确定文件结构,按职责划分单元并给出接口契约;任务分解为红-绿-提交节奏的小步骤。计划头部须包含状态、目标、Goals/Non-Goals、架构、备选方案、技术栈、约束与横切关注点。可选声明 independent、dependencies、scope.files、cooperative,以便并行执行。完成后按子代理驱动或行内执行方式交接。
限制:不得出现含糊表述(如 TBD、处理边界情况);不得粘贴完整实现体或测试体;接口与类型需在各任务间保持一致;若规格需求缺少对应任务需补上。计划规模应与任务规模匹配。