# Writing Plans

> 当你已有多步骤任务的 spec 或 requirements，且尚未触碰代码时使用

- Skill: `vinvcn/writing-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vinvcn/writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinvcn/writing-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vinvcn (https://skillmd.com/u/vinvcn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinvcn/writing-plans

---


# 编写计划

## 概览

编写全面的 implementation plans，假设执行工程师对我们的 codebase 零上下文，且品味可疑。记录他们需要知道的一切：每个 task 要触碰哪些文件、代码、测试、他们可能需要检查的 docs、如何测试。把完整 plan 拆成小块 tasks 给他们。DRY。YAGNI。TDD。频繁 commits。

假设他们是熟练开发者，但几乎不了解我们的 toolset 或 problem domain。假设他们不太懂好的 test design。

**开始时宣布：** "I'm using the writing-plans skill to create the implementation plan."

**上下文：** 如果在隔离 worktree 中工作，它应该已在执行时通过 `superpowers:using-git-worktrees` skill 创建。

**将计划保存到：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- （用户对 plan 位置的偏好会覆盖此默认值）

## 范围检查

如果 spec 覆盖多个独立 subsystems，它应该已在 brainstorming 期间拆分成 sub-project specs。如果没有，建议将它拆成多个单独 plans —— 每个 subsystem 一个。每个 plan 都应能独立产出可工作、可测试的软件。

## 文件结构

定义 tasks 之前，先梳理哪些文件会被创建或修改，以及每个文件负责什么。这是锁定分解决策的位置。

- 设计边界清晰、interfaces 明确的 units。每个文件都应有一个清晰责任。
- 你对一次能放进上下文的代码推理最好；当文件聚焦时，你的 edits 也更可靠。优先选择更小、更聚焦的文件，而不是承担过多职责的大文件。
- 一起变化的文件应该放在一起。按责任拆分，而不是按技术层拆分。
- 在现有 codebases 中，遵循既有 patterns。如果 codebase 使用大文件，不要单方面重构 - 但如果你要修改的文件已经变得难以驾驭，在 plan 中包含拆分是合理的。

这个结构会指导 task 分解。每个 task 都应产出自包含的更改，且独立看也合理。

## 小块 Task 粒度

**每个 step 是一个 action（2-5 分钟）：**
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step

## Plan Document Header

**每个 plan 必须以此 header 开头：**

```markdown
# [Feature Name] 实施计划

> **给 agentic workers：** REQUIRED SUB-SKILL: 使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans，逐 task 实现此 plan。Steps 使用 checkbox（`- [ ]`）语法进行跟踪。

**目标：** [One sentence describing what this builds]

**架构：** [2-3 sentences about approach]

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

---
```

## Task 结构

````markdown
### 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: 编写失败测试**

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

- [ ] **Step 2: 运行测试以验证它失败**

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

- [ ] **Step 3: 编写最小 implementation**

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

- [ ] **Step 4: 运行测试以验证它通过**

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"
```
````

## 不要有占位符

每个 step 都必须包含工程师所需的实际内容。这些是 **plan failures** —— 绝不要写：
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above"（没有实际 test code）
- "Similar to Task N"（重复代码 —— 工程师可能会乱序阅读 tasks）
- 只描述要做什么却不展示怎么做的 steps（code steps 需要 code blocks）
- 引用任何 task 中都未定义的 types、functions 或 methods

## 记住
- 始终使用精确 file paths
- 每个 step 都要有完整 code —— 如果 step 更改 code，就展示 code
- 精确 commands 与 expected output
- DRY、YAGNI、TDD、频繁 commits

## 自我评审

写完整 plan 后，用新鲜视角查看 spec，并对照检查 plan。这是你自己运行的 checklist —— 不是 subagent dispatch。

**1. Spec coverage：** 浏览 spec 中的每个 section/requirement。你能指向实现它的 task 吗？列出任何 gaps。

**2. Placeholder scan：** 在你的 plan 中搜索 red flags —— 上方 "No Placeholders" section 中的任何 patterns。修复它们。

**3. Type consistency：** 你在 later tasks 中使用的 types、method signatures 和 property names 是否匹配 earlier tasks 中定义的内容？Task 3 中名为 `clearLayers()`、Task 7 中却名为 `clearFullLayers()` 的 function 是 bug。

如果发现问题，就 inline 修复。无需重新评审 —— 修复后继续。如果发现某个 spec requirement 没有对应 task，就添加该 task。

## 执行交接

保存 plan 后，提供执行选择：

**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration

**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints

**Which approach?"**

**如果选择 Subagent-Driven：**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- 每个 task 使用 fresh subagent + 两阶段 review

**如果选择 Inline Execution：**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
- 带 review checkpoints 的 batch execution