mcpField
W
writing-plans

writing-plans

github.com/osmonteroAgent 工作流15120 次安装4 天前更新
代码仓库

关于 writing-plans

用于为项目背景有限的软件工程师编写逐步实施计划的技能，强调准确的文件路径、具体代码与测试步骤，并在交接前自查。

主要功能

  1. 01梳理文件及其职责
  2. 02将工作拆分为小步骤
  3. 03提供具体代码与测试命令
  4. 04规划增量式文件编辑
  5. 05检查需求覆盖与一致性

适用场景

  1. 01根据已批准的规格制定功能计划
  2. 02为刚接触代码库的工程师准备任务
  3. 03编排测试驱动的实施步骤

安装

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

$npx skills add https://github.com/osmontero/opencode-skills --skill writing-plans

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

附带文件LICENSE.txt

详细介绍

编写计划

概述

编写全面的实现计划，假设工程师对我们的代码库一无所知，而且品味可能不太好。记录他们需要了解的一切：每项任务要修改哪些文件、代码、测试、可能需要查阅的文档，以及如何测试。将完整计划拆分成小任务。保持 DRY。遵循 YAGNI。采用 TDD。频繁提交。

假设他们是熟练的开发者，但对我们的工具集或问题领域几乎一无所知。假设他们不太了解如何设计好的测试。

开始时宣布：“我将使用编写计划技能来创建实现计划。”

**上下文：**规划是只读的——plan Agent 只能写入 docs/plans/* 和 docs/specs/*。在当前检出目录中将计划写入这些路径；工作树会在执行时创建（参见 using-git-worktrees，它会在开始实施前由 executing-plans / subagent-driven-development 调用）。

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

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

范围检查

如果规格涵盖多个互不依赖的子系统，那么在头脑风暴阶段就应该将其拆分成多个子项目规格。如果尚未拆分，建议将其拆分成多个计划，每个子系统一个。每个计划都应独立产出可运行、可测试的软件。

文件结构

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

  • 设计边界清晰、接口定义明确的单元。每个文件都应有一项明确职责。
  • 你最擅长处理能同时纳入上下文的代码，而且文件越精简，修改就越可靠。优先选择较小且专注的文件，而不是包揽过多职责的大文件。
  • 一起变更的文件应放在一起。按职责拆分，而不是按技术层拆分。
  • 在现有代码库中，遵循既有模式。如果代码库使用大文件，不要擅自重构；但如果你要修改的文件已经变得臃肿，在计划中安排拆分是合理的。

此结构将指导任务拆分。每项任务都应产出独立完整、单独看也合理的变更。

小任务粒度

每一步只做一件事（2-5 分钟）：

  • “编写失败的测试”——一步
  • “运行测试，确认其失败”——一步
  • “实现最少量的代码，让测试通过”——一步
  • “运行测试，确认测试通过”——一步
  • “提交”——一步

计划文档标题

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

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or 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"
```

增量式文件写入（重要）

模型无法在单次调用中输出大型文件。 每次编辑或写入操作的输出上限约为 1000 个 token。超过此限制会导致 API 返回 500 错误。这是底层模型的硬性限制，并非最佳实践建议。

每次创建文件或进行大型编辑，都必须拆分为多个连续的增量步骤，每一步新增内容不得超过约 1000 个 token：

  1. 步骤 1：编写骨架——创建文件，包含导入语句、类／函数签名、类型定义和章节注释。暂不编写实现主体。
  2. 步骤 2 及后续步骤：逐个填充章节——每次编辑只实现一个函数、类方法或逻辑章节，每次编辑替换约 1000 个 token 或更少的聚焦区域。
  3. 最后一步：最终审查——阅读完整文件，修复不一致之处，然后提交。

**对于计划文档本身：**计划通常是大型文件。分多个阶段编写：

  • **阶段 1：**编写标题、文件结构图和任务概要（不含代码主体）
  • **阶段 2 及后续阶段：**逐个编辑计划，填充每个任务的代码块（每次编辑约 1000 个 token）
  • **阶段 3：**自我审查、修复问题并保存最终版本

在任务结构中，大型文件的写法如下：

- [ ] **Step 1: Write file skeleton**

Create `src/path/to/largefile.py` with imports, class definitions, method signatures, and TODO comments for each section.

- [ ] **Step 2: Implement Section A**

Edit `src/path/to/largefile.py` — replace the TODO for Section A with the actual implementation (~1000 tokens).

- [ ] **Step 3: Implement Section B**

Edit `src/path/to/largefile.py` — replace the TODO for Section B with the actual implementation (~1000 tokens).

- [ ] **Step 4: Final review and commit**

Read the complete file. Fix any inconsistencies. Commit.

**切勿规划单个步骤产出超过约 1000 个 token。**如果文件较大，计划中必须将其拆分为多个步骤。

不得使用占位内容

每个步骤都必须包含工程师所需的实际内容。以下内容都属于计划失败——绝不可写入：

  • “TBD”“TODO”“稍后实现”“补充细节”
  • “添加适当的错误处理”／“添加验证”／“处理边缘情况”
  • “为上述内容编写测试”（但没有实际测试代码）
  • “与任务 N 类似”（重复代码——工程师可能会按非顺序阅读任务）
  • 只描述要做什么，却没有展示如何实现的步骤（代码步骤必须包含代码块）
  • 引用任何任务中都没有定义的类型、函数或方法

请记住

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

自我审查

编写完计划后，以全新的视角对照规格检查计划。这是一份由你自行执行的检查清单——不是让子 Agent 执行的任务。

**1. 规格覆盖情况：**浏览规格中的每个章节／要求。你能否指出实现每项要求的任务？列出所有缺漏。

**2. 占位内容扫描：**搜索计划中的危险信号——检查上文“不使用占位内容”一节中的各种模式。发现后修复。

**3. 类型一致性：**后续任务中使用的类型、方法签名和属性名称，是否与前文定义的一致？任务 3 中名为 clearLayers() 的函数在任务 7 中变成 clearFullLayers()，就是一个错误。

如果发现问题，直接在原处修复。无需重新审查——修复后继续。如果发现有规格要求没有对应任务，就添加该任务。

执行交接

保存计划后，提供执行方式选择：

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

1. 子 Agent 驱动（推荐） - 我会使用 subagent 工具为每项任务分派一个全新的子 Agent，并在任务之间进行审查，以加快迭代

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

你想采用哪种方式？”

如果选择子 Agent 驱动：

  • **必需技能：**使用 subagent-driven-development
  • 每项任务都由全新的子 Agent 执行，并进行规格审查，然后进行质量审查；涉及安全的任务还需进行安全审查

如果选择内联执行：

  • **必需技能：**使用 executing-plans
  • 分批执行，并设置审查检查点

评论

支持 Markdown