writing-plans

name	writing-plans
description	在已有规格或需求、且任务需要多步骤实施时使用；必须在动代码前使用。

编写计划

概览

编写完整的实现计划时，假设执行工程师完全不了解我们的代码库，并且工程判断不稳定。把他们需要知道的内容都写清楚：每个任务要改哪些文件、测试/验证策略、可能需要查阅的文档，以及如何验证结果。DRY。YAGNI。采用实用、风险驱动的验证方式。

假设他们是熟练开发者，但几乎不了解我们的工具链或问题领域。也假设他们对良好测试设计并不熟悉。

开始时声明： “我正在使用 writing-plans skill 来创建实现计划。”

语言规则：

• 创建计划期间，与用户交流时使用简体中文。
• 最终开发计划文档主要使用简体中文编写。

上下文：

• 推荐：中大型或高风险改动在专用 worktree 中执行。
• 允许：小型、低风险改动可以在当前工作区执行。
• 根据改动范围、迁移风险和跨模块影响做判断。

计划保存到： docs/plans/YYYY-MM-DD-<feature-name>.md，但如果项目代码仓有其他规定，则需要严格遵守代码仓的规定

技术栈规则

• 始终优先遵循项目的实际技术栈。
• 如果技术栈约定不清晰，在适用时使用用户偏好的默认值（Python：click、rich、loguru、uv）。
• 不要覆盖明确的项目约束或既有约定。
• 编写新特性计划时，先以当前需求、已批准设计和用户确认的成功标准为边界；历史文档中的约束不得直接作为新特性开发过程的约束边界，至少不能作为第一优先级。
• 如果当前新特性与历史需求、设计文档或旧计划中的约束存在冲突，必须先请求用户确认取舍；禁止未经确认就基于历史约束写入计划。
• 禁止将历史文档中的“非范围”“暂不实现”“不引入依赖”等负向边界带入当前计划，作为当前新特性的限制条件或评估证据。

任务粒度

• 任务应能独立验证，并且范围合理。
• 典型任务规模为 15-90 分钟，具体取决于复杂度和风险。
• 不要强制每个任务都完整执行 RED-GREEN-REFACTOR。
• 每个任务都需要最低限度的验证策略，并按风险调整强度。

计划文档头部

每份计划都必须以这个头部开始：

# [功能名称] 实现计划

> **给 Claude：** 必需工作流：使用 superpowers:executing-plans 逐任务实现此计划。

**目标：** [用一句话描述要构建的内容]

**相关设计文档：** [已批准设计文档的精确路径]

**架构：** [用 2-3 句话说明实现方式]

**技术栈：** [关键技术/库]

**范围 / 非范围：** [明确边界]

---

任务结构

## Phase #N: [阶段名称]

### Task #N: [组件名称]

**状态：** Desinged | Coding | Finished

**文件：**
- 创建：`exact/path/to/new.file`（如需要）
- 修改：`exact/path/to/existing.file`
- 验证：`exact/path/to/tests/or/manual-checklist`（如适用）

- 功能：[此任务交付什么]
- 实现说明：[关键技术决策和约束]
- 预期验证结果：[必须通过或观察到什么]
- 完成时间：[完成时可选填写时间戳]

计划管理要求

• 计划必须组织为一个或多个阶段（Stage #1、Stage #2、...）。
• 每个阶段必须包含一个或多个任务（Task #1、Task #2、...）。
• 每个任务必须包含：
  • 任务内容
  • 实现说明
  • 预期结果
  • 状态：Desinged | Coding | Finished
• 验证必须由风险驱动：
  • 高风险改动（schema 迁移、跨模块重构、数据同步）：需要更强验证（自动化测试和/或迁移检查）。
  • 中低风险改动：允许使用定向构建检查加关键手动路径验证。
• 随工作推进及时更新任务状态。

记住

• 始终使用精确文件路径
• 包含具体实现说明，不写模糊表述
• 在适用时包含精确验证命令/检查清单和预期结果
• 所有保存的计划文档都以简体中文为主要语言
• 使用 $ 语法引用相关 skills
• DRY、YAGNI、实用验证、清晰范围边界
• 范围边界必须来自当前需求或用户确认；历史约束只能作为背景，发现冲突先问用户再写计划

执行交接

保存计划后，提供单一执行交接（不提供执行模式选项）：

“计划已完成并保存到 docs/plans/<filename>.md。下一步：使用 superpowers:executing-plans 执行此计划。”

“现在需要我准备执行交接提示词吗？”

执行交接规则：

• 不提供 subagent 驱动或其他替代执行路径。
• 引导他们在 worktree 中打开新会话。
• 必需工作流： 新会话使用 superpowers:executing-plans。