Appearance
writing-plans 技能的核心思想是：一份好的实现计划，要让一个「熟悉编程但对你项目一无所知」的工程师也能无卡顿地执行下去。这意味着每个任务步骤都不能有"TBD"，不能说"添加适当的错误处理"，不能说"参考 Task 3"——所有代码都必须写全，所有命令都必须能粘贴运行，所有文件路径都必须精确到行号。
writing-plans skill：给 AI 写一份「傻瓜也能执行」的实现计划
它解决的是什么问题
你有没有遇到过这种情况：和 AI 讲清楚了需求，它开始写代码，一开始方向正确，但写到一半突然偏了——改了不该改的文件，跳过了测试，或者用了和项目风格完全不搭的方案？
问题的根源通常不是 AI 能力不够，而是没有一份足够细的计划。
当 AI 靠模糊印象推进任务，每一步都在做小决策，这些小决策的累积误差最终会让结果偏离预期。writing-plans 技能的作用是在写代码之前，强迫 AI 先把所有这些决策显式地写出来，让人来审查、确认，再交给智能体执行。
这份计划要细到什么程度
SKILL.md 里有一句话可以当作标准：
写给一个热情高涨、品味不佳、没有判断力、对项目毫无了解、还不喜欢写测试的初级工程师来看。
换一种中文表达：写给一个对你代码库零上下文的人，也能照着做不卡壳的程度。
具体来说，每一个「步骤」的粒度是 2 到 5 分钟：
- 写这个失败的测试 → 一个步骤
- 运行测试，确认它失败 → 一个步骤
- 写让测试通过的最简实现 → 一个步骤
- 再次运行测试，确认通过 → 一个步骤
- 提交 → 一个步骤
这不是在浪费空间，这种粒度让 AI 智能体执行时有明确的检查点，也让人工审查时能发现哪一步逻辑不通。
好计划 vs 坏计划：对比示例
坏计划：模糊、不可执行
markdown
### Task 2: 实现用户认证
- [ ] 创建认证模块
- [ ] 添加适当的错误处理
- [ ] 编写测试（参考 Task 1 的风格）
- [ ] 确保安全性这份计划有四个致命问题：
- 没有文件路径：「创建认证模块」要在哪个文件里创建？叫什么名字？
- 空洞的指令：「添加适当的错误处理」——什么叫适当？哪些错误？怎么处理？
- 引用了上下文：「参考 Task 1 的风格」——执行 Task 2 的智能体可能根本没读 Task 1。
- 无法验证：「确保安全性」是结果描述，不是可执行动作。
好计划：精确、可执行
markdown
### Task 2: 实现 JWT 登录接口
**Files:**
- Create: `src/auth/login.ts`
- Modify: `src/routes/index.ts:45-60`
- Test: `tests/auth/login.test.ts`
- [ ] **Step 1: 写失败的测试**
\`\`\`typescript
// tests/auth/login.test.ts
import { login } from '../../src/auth/login';
test('valid credentials return JWT token', async () => {
const result = await login('user@example.com', 'correct-password');
expect(result.token).toBeDefined();
expect(result.token).toMatch(/^eyJ/); // JWT 格式校验
});
test('invalid password throws AuthError', async () => {
await expect(login('user@example.com', 'wrong')).rejects.toThrow('Invalid credentials');
});
\`\`\`
- [ ] **Step 2: 运行测试，确认失败**
\`\`\`bash
npx jest tests/auth/login.test.ts -t "valid credentials"
\`\`\`
Expected: FAIL，报错 "Cannot find module '../../src/auth/login'"
- [ ] **Step 3: 写最简实现**
\`\`\`typescript
// src/auth/login.ts
import jwt from 'jsonwebtoken';
import { db } from '../db';
export async function login(email: string, password: string) {
const user = await db.users.findByEmail(email);
if (!user || !await user.verifyPassword(password)) {
throw new Error('Invalid credentials');
}
const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET!, { expiresIn: '7d' });
return { token };
}
\`\`\`
- [ ] **Step 4: 运行测试，确认通过**
\`\`\`bash
npx jest tests/auth/login.test.ts
\`\`\`
Expected: PASS（2 tests）
- [ ] **Step 5: 提交**
\`\`\`bash
git add src/auth/login.ts tests/auth/login.test.ts
git commit -m "feat: add JWT login endpoint"
\`\`\`两份计划描述的是同一件事，但好计划的执行者（无论是 AI 还是人）完全不需要做任何额外决策。
计划文档的固定格式
每份计划文档必须以固定的文件头开始，这个文件头告诉执行它的智能体：这份计划需要用 subagent-driven-development 或 executing-plans 技能来执行，不要直接开写。
markdown
# [功能名称] 实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task.
> Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** [一句话描述目标]
**Architecture:** [2-3 句描述方案]
**Tech Stack:** [关键技术/库]
---计划保存到：docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
写计划前先做文件结构规划
在列出具体任务之前，先把哪些文件会被创建或修改列出来，以及每个文件的职责是什么。
这一步的价值在于：文件边界的划分决定了任务的划分。如果文件结构没想清楚就开始列任务，任务之间会出现模糊地带，导致两个任务都在处理同一段逻辑。
原则：
- 每个文件有且只有一个清晰的职责
- 一起变化的文件放在一起（按功能聚合，不按技术层级分层）
- 在现有项目中，跟随已有模式；除非文件已经过于臃肿，否则不要重组结构
严禁出现的内容
以下内容出现在计划中，意味着这份计划是不完整的：
| 反模式 | 为什么不行 |
|---|---|
| "TBD"、"TODO"、"稍后实现" | 执行时没有足够信息，会被跳过或猜测 |
| "添加适当的错误处理" | "适当"是一个判断，不是一个动作 |
| "处理边界情况" | 哪些边界情况？不说清楚等于没说 |
| "为上述代码编写测试" | 没有具体测试代码的测试步骤无法执行 |
| "与 Task N 类似" | 执行者可能不按顺序读，重复写完整代码是必须的 |
| 步骤中提到了但没有定义的函数名 | Task 7 调用的方法必须在更早的 Task 中被定义 |
计划写完后的自查清单
写完整份计划后，回头用新鲜眼光做一次自检，不用派子智能体，自己过一遍即可：
- 需求覆盖：对照原始设计文档，每一条需求都能找到对应的实现任务吗？列出漏掉的。
- 占位符扫描：搜索反模式关键词（TBD、TODO、similar to、appropriate），找到即修复。
- 类型一致性：Task 3 定义的函数叫
clearLayers()，Task 7 调用时有没有拼成clearFullLayers()？接口名、参数类型、返回值格式要前后一致。
发现问题直接在原地修复，不需要重新走一遍整个流程。
执行移交：写完计划之后
计划保存完毕后，提供两种执行选项：
选项一：子智能体驱动（推荐） 每个任务由一个独立的新子智能体执行，任务之间进行两阶段审查（先检查规格符合度，再检查代码质量），迭代速度快。
选项二：内联执行 在当前会话中使用 executing-plans 技能，分批执行并在关键节点暂停等待人工确认。
两种方式都能用，选项一更适合任务较多、希望并行推进的场景；选项二更适合你想保持更紧密控制的情况。
FAQ
Q: 这个技能要在什么时候触发？ A: 当你有了一份通过 brainstorming 技能确认的设计文档之后。它在「设计确认」和「开始写代码」之间，填充了一份可执行的实现计划。顺序是：brainstorming → writing-plans → subagent-driven-development（或 executing-plans）。
Q: 计划要有多长？一个任务能不能合并几个步骤？ A: 长度取决于功能的复杂度，没有硬性页数限制。步骤不建议合并——"写测试 + 运行测试 + 写实现"合成一步，就失去了 TDD 的 RED-GREEN 节奏，智能体会倾向于直接写实现而跳过先确认测试失败的步骤。
Q: 如果功能非常大，一份计划写不下怎么办？ A: writing-plans 本身有一个范围检查（Scope Check）步骤：如果一份设计文档涵盖了多个独立子系统，应该在 brainstorming 阶段就拆分成多份子项目设计文档，再分别生成各自的计划。每份计划应该能独立生产出可测试的软件。
Q: 计划里的代码必须是完全正确的、可运行的代码吗？ A: 是的，这是最关键的要求。「伪代码」或「示意性代码」等于没有。如果某一步需要修改代码，就必须写出修改后的完整版本，而不是「在这里加上验证逻辑」这样的描述。