mcpField
W
writing-plans

writing-plans

github.com/lucianghindaAgent 工作流43042 次安装今天更新
代码仓库

关于 writing-plans

writing-plans 是将规格说明转化为逐项实施计划的技能。它列出文件、测试步骤、命令和提交，使对代码库了解有限的开发者也能按计划推进。

主要功能

  1. 01梳理文件及其职责
  2. 02拆分为小型任务
  3. 03提供具体代码与命令
  4. 04纳入测试和提交步骤
  5. 05检查需求覆盖与占位内容

适用场景

  1. 01规划功能实现
  2. 02将规格说明拆成可测试任务
  3. 03为不熟悉代码库的开发者准备计划

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lucianghinda/superpowers-ruby --skill writing-plans

安装后在 Claude Code 中输入/writing-plans确认已加载。

附带文件plan-document-reviewer-prompt.md

详细介绍

编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库毫无了解，而且判断力存疑。记录他们需要知道的一切：每项任务要修改哪些文件、代码、测试、需要查阅的文档，以及如何测试。将完整计划拆解为易于执行的小任务。DRY。YAGNI。TDD。频繁提交。

假设他们是经验丰富的开发者，但对我们的工具集或问题领域几乎一无所知。也不要假设他们很擅长设计测试。

开始时宣布：“我正在使用 writing-plans 技能来创建实施计划。”

上下文： 应在专用工作树中运行（由 brainstorming 技能创建）。

计划保存到： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

  • 用户对计划保存位置的偏好优先于此默认设置。

范围检查

如果规范涵盖多个彼此独立的子系统，那么在 brainstorming 阶段就应该将其拆分为多个子项目规范。如果没有拆分，则建议将其拆成多个计划，每个子系统对应一个。每个计划都应独立产出可运行、可测试的软件。

文件结构

定义任务之前，先梳理将要创建或修改的文件，以及每个文件的职责。此时要确定分解方案。

  • 设计边界清晰、接口明确的单元。每个文件都应只有一个明确职责。
  • 你最擅长处理能同时放在上下文中的代码，文件聚焦时，修改也更可靠。优先选择更小、更聚焦的文件，避免大文件承担过多职责。
  • 一起变更的文件应放在一起。按职责拆分，而非按技术层拆分。
  • 在现有代码库中，遵循已有模式。如果代码库使用大文件，不要擅自重构；但如果要修改的文件已经变得难以管理，可以在计划中安排拆分。

文件结构将指导任务分解。每项任务都应产出自成一体、独立合理的改动。

细化任务粒度

每个步骤只做一件事（2–5 分钟）：

  • “编写失败测试”——一个步骤
  • “运行测试，确认其失败”——一个步骤
  • “实现最精简的代码，使测试通过”——一个步骤
  • “运行测试，确认其通过”——一个步骤
  • “提交”——一个步骤

计划文档标题

每份计划都必须以此标题开头：

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-ruby:subagent-driven-development (recommended) or superpowers-ruby:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

任务结构

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

不得使用占位内容

每个步骤都必须包含工程师需要的实际内容。以下内容都属于计划缺陷，绝不要写：

  • “TBD”“TODO”“以后再实现”“补充细节”
  • “添加适当的错误处理”／“添加校验”／“处理边界情况”
  • “为上述内容编写测试”（但没有提供实际测试代码）
  • “与任务 N 类似”（应重复提供代码——工程师可能会跳着阅读任务）
  • 只描述要做什么，却不说明怎么做的步骤（涉及代码的步骤必须提供代码块）
  • 引用未在任何任务中定义的类型、函数或方法

请记住

  • 始终使用准确的文件路径
  • 每个步骤都提供完整代码——如果某个步骤要修改代码，就展示代码
  • 提供准确命令及预期输出
  • DRY、YAGNI、TDD、频繁提交

自我审查

写完完整计划后，重新审视规范，并对照检查计划。这是你自行执行的检查清单，不是分派给子 Agent 的任务。

1. 规范覆盖： 浏览规范的每个章节和要求。能否指出对应的实施任务？列出所有遗漏。

2. 占位内容扫描： 搜索计划中的危险信号——检查上方“不得使用占位内容”部分列出的所有模式。发现后予以修正。

3. 类型一致性： 后续任务中使用的类型、方法签名和属性名称，是否与前面定义的一致？例如，任务 3 中的函数名是 clearLayers()，但任务 7 中却写成 clearFullLayers()，这就是错误。

如果发现问题，直接在计划中修正。无需再次审查，修正后继续。如果发现某项规范要求没有对应任务，就添加相应任务。

执行交接

保存计划后，提供执行选项：

“计划已完成并保存到 docs/superpowers/plans/<filename>.md。有两种执行方式：

1. 子代理驱动（推荐） - 为每项任务派遣一个全新的子代理，在任务之间进行审查，快速迭代

2. 内联执行 - 在本会话中使用 executing-plans 执行任务，分批执行并设置检查点

你选择哪种方式？”

如果选择子代理驱动：

  • 必需子技能： 使用 superpowers-ruby:subagent-driven-development
  • 每项任务使用全新的子代理 + 两阶段审查

如果选择内联执行：

  • 必需子技能： 使用 superpowers-ruby:executing-plans
  • 分批执行，并设置检查点以供审查

评论

支持 Markdown