第 4 章：实施计划 — 把设计拆成可执行的任务

你将学到什么

• 从设计稿和需求文档出发，写一份实施计划
• 用 superpowers 的 /writing-plans 命令自动生成详细任务列表
• 理解好的计划长什么样：每步有代码、有测试、有 commit

4.1 为什么需要实施计划

第 2 章我们理清了需求，第 3 章我们做好了设计。现在该写代码了？

还差一步——把设计拆成任务。

原因很简单：

4.2 /writing-plans — 自动生成实施计划

命令语法

/writing-plans [需求描述或设计文档路径]

实战：为 NoteFlow 生成实施计划

在 Claude Code 中输入：

/writing-plans

基于以下文档生成实施计划：
- 需求文档：docs/notes/requirement-review.md（第 2 章产出）
- 设计系统：src/styles/design-system.css（第 3 章产出）
- HTML 设计稿：src/pages/index.html（第 3 章产出）

目标：实现 NoteFlow 的 P0 功能（笔记 CRUD + localStorage）
技术栈：React 18 + Vite + vitest

Claude 会做什么：

1. 读取你的需求文档和设计稿
2. 分析需要创建/修改哪些文件
3. 拆成 5-8 个独立任务
4. 每个任务包含：文件路径、代码、测试、commit 命令

4.3 好的计划长什么样

/writing-plans 产出的计划文档大致是这样：

# NoteFlow P0 实施计划

## 文件结构

src/
├── components/
│   ├── NoteList.jsx       — 笔记列表组件
│   ├── NoteList.test.jsx  — 列表组件测试
│   ├── NoteEditor.jsx     — 编辑器组件
│   ├── NoteEditor.test.jsx— 编辑器测试
│   └── SearchBar.jsx      — 搜索栏组件
├── hooks/
│   ├── useNotes.js        — 笔记数据管理 Hook
│   └── useNotes.test.js   — Hook 测试
├── utils/
│   └── storage.js         — localStorage 封装
├── App.jsx                — 主应用
└── App.test.jsx           — 集成测试

---

### Task 1: localStorage 工具函数

**文件：**
- 创建: `src/utils/storage.js`
- 测试: `src/utils/storage.test.js`

- [ ] **Step 1: 写测试**

\```javascript
import { saveNotes, loadNotes, getStorageUsage } from './storage';

describe('storage', () => {
  beforeEach(() => localStorage.clear());

  test('saveNotes stores data to localStorage', () => {
    const notes = [{ id: '1', title: 'Test', content: 'Hello' }];
    saveNotes(notes);
    expect(JSON.parse(localStorage.getItem('noteflow-notes'))).toEqual(notes);
  });

  test('loadNotes returns empty array when no data', () => {
    expect(loadNotes()).toEqual([]);
  });

  test('getStorageUsage returns percentage', () => {
    saveNotes([{ id: '1', title: 'A'.repeat(1000), content: '' }]);
    const usage = getStorageUsage();
    expect(usage).toBeGreaterThan(0);
    expect(usage).toBeLessThan(100);
  });
});
\```

- [ ] **Step 2: 运行测试确认失败**

运行: `npm test -- src/utils/storage.test.js`
预期: FAIL（函数未定义）

- [ ] **Step 3: 实现最小代码**

\```javascript
const STORAGE_KEY = 'noteflow-notes';
const MAX_STORAGE_MB = 5;

export function saveNotes(notes) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(notes));
}

export function loadNotes() {
  const data = localStorage.getItem(STORAGE_KEY);
  return data ? JSON.parse(data) : [];
}

export function getStorageUsage() {
  const data = localStorage.getItem(STORAGE_KEY) || '';
  const usedBytes = new Blob([data]).size;
  const maxBytes = MAX_STORAGE_MB * 1024 * 1024;
  return (usedBytes / maxBytes) * 100;
}
\```

- [ ] **Step 4: 运行测试确认通过**

运行: `npm test -- src/utils/storage.test.js`
预期: 3 tests PASSED

- [ ] **Step 5: Commit**

\```bash
git add src/utils/storage.js src/utils/storage.test.js
git commit -m "feat: add localStorage utility functions"
\```

Task 2-5: 依次类推

每个任务都遵循同样的结构：写测试 → 确认失败 → 写代码 → 确认通过 → commit。

4.4 计划质量的检查标准

/writing-plans 生成计划后，Claude 会自动做一轮自检。你也可以手动检查：

4.5 审查和批准计划

计划生成后，你有两个选择：

flowchart TB
    P[计划文档生成] --> Q{怎么执行？}

    Q --> A["选项 A：Subagent 驱动
（推荐）
每个 task 派一个 subagent
自动编码+审查"]
    Q --> B["选项 B：手动执行
自己一步步跟着做
学习每个细节"]

    A --> AA["/subagent-driven-development
下一章讲解"]
    B --> BB["自己执行每个 Step
适合第一次学习"]

    style A fill:#dcfce7,stroke:#16a34a
    style B fill:#fef3c7,stroke:#d97706

建议： 第一次跟教程选手动执行（理解每个步骤）。后续项目选 subagent 驱动（效率最高）。

动手做

1. 准备好第 2 章的需求文档和第 3 章的设计稿
2. 运行 /writing-plans，生成 NoteFlow 的实施计划
3. 审查计划：每个任务都有代码吗？有测试吗？没有 placeholder 吗？
4. 保存计划到 docs/superpowers/plans/noteflow-p0.md

本章小结

核心原则： 计划越详细，执行越顺利。每步都有代码和测试，不需要临时做决定。