writing-plans Skill 是什么？怎么用？

Android童话镇
2 阅读7分钟

想象一下：你是一个刚接手新房的业主，想改造厨房。你跟施工队长说：“我想要一个更好用的厨房，能做饭、洗菜、储物。” 队长说：“明白！我这就去干。” —— 然后第二天你发现，他把洗碗机装在了冰箱的位置，灶台离水槽两米远，储物柜在吊顶里。你问：“你怎么不先画个图纸？” 队长挠头：“你说得挺清楚的呀，我以为我都懂了。”

这就是 没有计划的后果。

在 AI 辅助编程的世界里，我们也有类似的问题。你给 AI 一个需求（Spec），AI 直接冲去写代码，结果可能是：

  • 漏掉重要功能
  • 步骤太模糊，AI 自己都不知道下一步该干嘛
  • 代码和需求对不上
  • 测试没写，或者写了错的测试

于是，Writing-Plans Skill 诞生了。它的角色，就是那个 先画施工图纸，再动手干活 的靠谱队长。

一、Writing-Plans Skill 是什么？（一句话 + 一个比喻）

Writing-Plans Skill 是一个让 AI 在写代码之前，先生成一份“施工蓝图”的能力。
这份蓝图会把一个需求拆成 2–5 分钟就能做完的、带具体代码和命令的“微步骤”，确保每一步都不会跑偏。

比喻：

  • Spec（需求）  = 你给厨师说：“我想吃一道酸辣开胃的菜。”
  • Writing-Plans = 厨师拿出一张纸，写下：1) 切泡菜，2) 调酸辣汁（醋2勺+生抽1勺+辣椒油1勺），3) 煮粉丝2分钟，4) 装盘撒葱花。每一步都有精确分量和时间。
  • 执行计划 = 厨师照着这张纸一步一步做，做完一道完美的酸辣泡菜粉丝。

没有计划，厨师可能把粉丝煮成坨，或者把醋倒半瓶。

二、为什么需要它？（痛点 vs 解决方案）

没有计划的问题有计划的解决方式
AI 漏掉 spec 中的某个要求计划里每个要求都对应至少一个任务
任务太笼统，比如“实现用户登录”拆成：写测试 → 建登录表单 → 验证密码 → 返回 token → 测试通过 → 提交
代码里出现 // TODO 或者 # FIXME later计划禁止任何占位符，所有代码必须完整写出
类型/函数名前后不一致计划最后会自检类型一致性
不知道测什么、怎么测每个任务第一步就是写测试（TDD）

简单说：计划就是 AI 的“防呆设计” ，让它不会犯低级错误。

三、Writing-Plans Skill 的最佳用法

1. 什么时候用它？

  • 任何时候你有一个需要多步完成的编程任务，且你希望结果靠谱。
  • 特别是：写新功能、重构、修复杂 bug、集成第三方服务。
  • 一句话规则：  如果任务需要超过 15 分钟才能想清楚，就先用 Writing-Plans 生成计划。

2. 怎么用？（三步走）

第 1 步：准备需求（Spec）
你需要一份比较清晰的需求描述。可以是你自己写的，也可以让 AI 帮你从聊天记录里整理出来。例如：

“在任务管理应用中，增加一个‘按截止日期过滤’的功能。用户可以选择今天、本周、本月，然后列表只显示对应任务。”

第 2 步：告诉 AI 使用 Writing-Plans Skill
你直接说：“请用 writing-plans skill 为以下 spec 生成实施计划。” 然后把 spec 贴过去。

AI 会回复：“我正在使用 writing-plans skill 创建实施计划。” 然后它会：

  • 创建一个干净的工作目录（worktree）
  • 按照固定模板生成计划文档
  • 保存到 docs/superpowers/plans/2026-04-17-task-filter.md

第 3 步：决定怎么执行这个计划
AI 生成计划后，会问你两种执行方式：

  • 方式A（推荐）：子代理驱动 – 每个任务派一个全新的 AI 小助手去执行，做完一个你检查一个，没问题再继续。就像流水线上每个工人只做一个动作，又快又稳。
  • 方式B：内联执行 – 当前 AI 自己按顺序做所有任务，中间会停下来让你检查几个“里程碑”。适合你不想频繁切换对话的情况。

你选一个，AI 就开始干活了。

四、实现原理

Writing-Plans Skill 其实是一个  “元技能”  —— 它不直接写代码，而是生成一份非常严格的指令集，然后再由另一个 AI（或同一个 AI 的不同模式）去执行。整个过程分为三部分：

1. 计划生成器（Writing-Plans 自身）

它读入你的 spec，然后：

  • 检查范围：如果 spec 涉及多个独立子系统，会建议拆成多个计划（避免混乱）。

  • 设计文件结构：先决定要创建/修改哪些文件，每个文件做什么。

  • 分解任务：每个任务拆成 5 个标准步骤：

    • 写失败测试
    • 运行测试（预期失败）
    • 写最少代码让它通过
    • 运行测试（预期通过）
    • 提交 git

  • 填充内容：每一步都必须有完整的代码、命令、预期输出。不允许写 “TODO” 或 “后续补充”。

  • 自检：生成完后，它会自我审查：spec 是否全覆盖？有没有占位符？类型/函数名是否前后一致？

2. 计划文档格式（强制模板）

每一份计划开头都有这个“护身符”：

# [功能名] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development ...

**Goal:** 一句话目标
**Architecture:** 两三句架构说明
**Tech Stack:** 技术栈
---

然后是任务列表，每个任务都有精确的文件路径、步骤列表、代码块。

3. 计划评审器（可选但推荐）

为了确保计划没有漏洞，还有一个 Plan Document Reviewer 子代理。它像一个质检员，检查：

  • 完整性（有没有缺失步骤、占位符）
  • 与 spec 的对齐（有没有跑偏）
  • 任务粒度（会不会太大导致卡住）
  • 可构建性（另一个 AI 照着做能不能完成）

只有评审通过，计划才算真正可用。

五、时序图：从需求到完工的全过程

下面用 mermaid 画一个完整的调用过程（你可以把它想象成一部电影的剧情流程）：

从需求到完工的全过程.png

解释几个关键点：

  • Worktree：一个干净的临时工作区，避免干扰现有代码。
  • 子代理驱动：每个任务是一个独立的“小 AI”，做完就销毁，不会累、不会乱。
  • Checkpoint：内联执行中的“里程碑”，比如完成一个组件后让你看一眼。

六、实战小例子

假设你的 spec 是：

“在命令行工具里增加一个 --verbose 参数，打印更详细的日志。”

Writing-Plans Skill 会生成类似这样的计划（简化版）：

# Verbose Flag Implementation Plan

**Goal:** 增加 --verbose 参数，输出 debug 级别日志。

**Architecture:** 使用 argparse 添加标志，设置日志级别为 DEBUG。

## Task 1: 修改参数解析

**Files:**
- Modify: `cli/main.py:15-25`
- Test: `tests/cli/test_main.py`

- [ ] **Step 1: 写测试 – 验证 --verbose 能开启 debug 日志**
```python
def test_verbose_sets_debug_level(capsys):
    with patch('cli.main.logging.basicConfig') as mock_config:
        main(['--verbose'])
        mock_config.assert_called_with(level=logging.DEBUG)
  • Step 2: 运行测试（预期失败）
    pytest tests/cli/test_main.py::test_verbose_sets_debug_level -v → FAIL
  • Step 3: 实现 --verbose
# cli/main.py
parser.add_argument('--verbose', action='store_true')
if args.verbose:
    logging.basicConfig(level=logging.DEBUG)
  • Step 4: 重新运行测试 → PASS
  • Step 5: 提交
    git add cli/main.py tests/cli/test_main.py
    git commit -m "feat: add --verbose flag for debug logging"

你看，每一步连代码和命令都写好了，你什么都不用想，照着复制粘贴（或者让 AI 自动执行）就行。

---

## 七、最佳用法总结（给小白的三句心法）

1. **先写 spec，再叫 Writing-Plans** – 别在脑子里想，写下来。哪怕只有三句话。
2. **永远用“子代理驱动”执行** – 每个任务独立做，你中间可以随时喊停、修改、重试。
3. **信任计划，但相信评审** – 计划生成后，花 1 分钟让评审员扫一遍，能避免 90% 的返工。

---

## 八、最后的一个小幽默

> 问：为什么 Writing-Plans Skill 是“超级技能”？  
> 答：因为它就像你玩游戏时的“攻略” – 你不需要自己试错 100 次，照着做就能一次通关。  
> 而那个不写计划的 AI，就像第一次玩《黑暗之魂》还选了无用之人开局，然后直接冲向 BOSS。

**现在，你可以放心地对 AI 说：“请用 writing-plans skill 给我一个计划。”**  
然后泡杯茶，等着看 AI 像乐高说明书一样把代码一块块拼出来。🍵
avatar
文章
阅读
粉丝