mcpField
W
writing-plans

writing-plans

github.com/camacho开发350 次安装
代码仓库

关于 writing-plans

用于编写逐项拆分的软件实现计划的技能，面向需要明确文件路径、代码、测试和命令的开发者。计划保存到项目规划目录，并包含自检和执行交接。

主要功能

  1. 01梳理文件及其职责
  2. 02将工作拆分为小步骤
  3. 03提供代码与测试指导
  4. 04注明命令和预期结果
  5. 05检查计划覆盖范围与遗漏
  6. 06支持交接执行

适用场景

  1. 01根据规格规划功能实现
  2. 02准备 TDD 实施任务
  3. 03创建便于审查的工程交接

安装

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

$npx skills add https://github.com/camacho/ai-skills --skill writing-plans

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

详细介绍

编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库毫无了解，品味也不太可靠。记录他们需要了解的一切：每项任务要修改哪些文件、代码、测试、需要查阅的文档，以及如何测试。将完整计划拆解为易于执行的小任务。遵循 DRY、YAGNI、TDD。频繁提交。

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

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

上下文： 应在专用工作树中执行（由头脑风暴技能创建）。

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

  • （尊重用户对计划位置的偏好——此默认位置可以覆盖）

范围检查

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

文件结构

定义任务之前，先列出将要创建或修改的文件，并说明每个文件的职责。这一步会确定拆分方案。

  • 设计边界清晰、接口明确的单元。每个文件都应有一个明确的职责。
  • 你对能同时纳入上下文的代码推理效果最好，文件聚焦时修改也更可靠。优先选择更小、更专注的文件，而不是承担过多职责的大文件。
  • 一起变更的文件应放在一起。按职责拆分，而非按技术层拆分。
  • 在现有代码库中，应遵循既有模式。如果代码库使用大文件，不要擅自重构；但如果要修改的文件已经过于庞大，在计划中加入拆分步骤是合理的。

此结构将指导任务拆分。每项任务都应产出独立、自洽的变更。

小任务的粒度

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

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

计划文档头部

每个计划都必须以此头部开头：

# [Feature Name] Implementation Plan

> **For agentic workers:** Use /build or your project's plan execution skill 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()，这就是一个错误。

如果发现问题，请直接修正。无需重新审查，修正后继续。如果发现某项规范要求没有对应任务，请添加该任务。

执行交接

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

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

1. 子 Agent 驱动（推荐）——每项任务都派发一个全新的子 Agent，并在任务之间审查，快速迭代

2. 内联执行——在本次会话中使用 /build 执行任务，并通过检查点分批执行

你想采用哪种方式？”

如果选择子 Agent 驱动：

  • 根据计划上下文，为每项任务派发一个全新的子 Agent
  • 在继续之前审查每项任务的输出

如果选择内联执行：

  • 使用 /build（或项目的计划执行技能）
  • 通过检查点分批执行，以便审查

评论

支持 Markdown