核心命题： 代码之前是计划，计划之前是设计，设计之前是理解。跳过任何一步都会付出更高代价。
课前回顾
第 3-4 课聚焦"纪律"（怎么写代码、怎么调试）。本课回到工作流的起点：在动手写代码之前，怎么确保你在做对的事（brainstorming），以及怎么把它拆成可执行的步骤（writing-plans）。
这两个技能是 7 步核心工作流的前半段，也是第 6 课"子代理架构"的直接输入。
5.1 Brainstorming 技能精读
文件： skills/brainstorming/SKILL.md
HARD-GATE：最强的行为约束
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and
the user has approved it. This applies to EVERY project regardless of
perceived simplicity.
</HARD-GATE>
<HARD-GATE> 不是标准的 Markdown — 它是一个语义标签，告诉 AI "这是一个不可越过的门"。和 TDD 的 Iron Law 不同，HARD-GATE 不只是说"不要跳过"，而是列出了具体禁止的动作：调用实现技能、写代码、创建项目脚手架。
为什么需要这么强？因为在 v4.3.0 之前，AI 会：
- 收到"帮我做一个 todo 应用" → 直接开始写代码
- 或者花 30 秒"设计" → 跳到 frontend-design 技能开始实现
HARD-GATE 阻止了这两种跳过。
"太简单不需要设计"— 反模式
## Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A todo list, a single-function utility,
a config change — all of them. "Simple" projects are where unexamined assumptions
cause the most wasted work.
这是一个认知陷阱：越"简单"的项目，越容易跳过设计。但"简单"项目正是未检验的假设造成最多浪费的地方 — 你以为很简单，做到一半发现不是。
设计可以很短（真正简单的项目只需要几句话），但必须展示给用户并获得确认。
9 步 Checklist
1. 探索项目上下文 — 检查文件、文档、最近提交
2. 提供可视化伴侣 — 如果话题涉及视觉问题（单独一条消息）
3. 逐个提问澄清 — 一次一个问题
4. 提出 2-3 个方案 — 带取舍分析和推荐
5. 分块展示设计 — 按复杂度调整每块的详细程度
6. 写设计文档 — 保存到 docs/superpowers/specs/
7. 规格自审 — 检查占位符、矛盾、歧义、范围
8. 用户审阅 — 等用户确认后才继续
9. 转入实现 — 只能调用 writing-plans
每一步都是刻意设计的。注意几个要点：
"一次一个问题"（步骤 3）
不是一口气问 10 个问题，而是每条消息只问一个。原因：多个问题会让用户选择性回答，遗漏关键信息。一个一个来，确保每个问题都得到充分回答。
"提出 2-3 个方案"（步骤 4）
不是直接给出"最佳方案"，而是给选项。原因：用户可能有你不知道的约束（性能要求、技术栈限制、团队偏好）。提供选项让用户做出知情决策。
"分块展示"（步骤 5）
Scale each section to its complexity: a few sentences if straightforward,
up to 200-300 words if nuanced
简单的部分用几句话，复杂的部分用 200-300 字。不是所有部分都需要同等篇幅 — 把注意力花在真正需要深入的地方。
步骤 9 只能调用 writing-plans
**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design,
mcp-builder, or any other implementation skill.
brainstorming 的唯一出口是 writing-plans。这确保了必须先有计划才能实现，不会跳步。
大项目分解
If the request describes multiple independent subsystems (e.g., "build a
platform with chat, file storage, billing, and analytics"), flag this
immediately. Don't spend questions refining details of a project that
needs to be decomposed first.
当需求涉及多个独立子系统时，不要在单个 spec 中处理所有东西。先分解成子项目，每个子项目走自己的 spec → plan → implementation 循环。
Visual Companion（可视化伴侣）
brainstorming 支持一个浏览器端的可视化伴侣 — 一个零依赖的 WebSocket 服务器，可以在浏览器中展示 mockup、架构图、布局对比等。
关键决策规则：每个问题单独决定是否用浏览器。 不是开启了就所有问题都用浏览器。判断标准：
"Would the user understand this better by seeing it than reading it?"
用户看到它比读到它更容易理解吗？
用浏览器：UI mockup、架构图、布局对比
用终端：需求问题、概念选择、权衡列表、技术决策
5.2 Writing-Plans 技能精读
文件： skills/writing-plans/SKILL.md
目标受众假设
Write comprehensive implementation plans assuming the engineer has zero
context for our codebase and questionable taste.
计划的目标读者是"一个对代码库零上下文、品味可疑的工程师"。这个假设迫使计划足够详细和明确 — 如果连"最差情况"的执行者都能照着做，计划就够好了。
2-5 分钟粒度
每个步骤应该是 2-5 分钟就能完成的单个动作：
**Each step is one action (2-5 minutes):**
- "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
注意："写测试"和"运行测试"是两个不同的步骤。这个粒度确保了：
- 每一步都可以独立验证
- 失败时能精确定位哪一步出了问题
- 子代理执行时能清楚地报告进度
任务结构模板
### 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"
```
注意每个任务的结构：
- Files — 精确的文件路径（创建/修改/测试）
- Steps — 用 checkbox 语法
- [ ]便于跟踪进度 - Code — 完整的代码，不是描述
- Commands — 精确的运行命令和预期输出
No Placeholders — 计划失败模式清单
These are **plan failures** — never write them:
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (repeat the code)
- Steps that describe what to do without showing how
- References to types, functions, or methods not defined in any task
六种不允许出现的内容。最后一条尤其重要："引用了其他任务中没有定义的类型或函数"。如果任务 7 用了一个 clearLayers() 函数，但任务 3 中定义的是 clearFullLayers()，这就是一个计划级别的 bug。
"Similar to Task N" 也是被禁止的 — 即使两个任务很相似，也必须重复代码。因为子代理可能不按顺序读任务，或者只读到被分配的那个任务。
自审 Checklist
写完计划后的三项自检：
1. **Spec coverage:** Skim each section/requirement in the spec.
Can you point to a task that implements it? List any gaps.
2. **Placeholder scan:** Search your plan for red flags —
any of the patterns from the "No Placeholders" section.
3. **Type consistency:** Do the types, method signatures, and property
names you used in later tasks match what you defined in earlier tasks?
这三项检查来自 v5.0.6 的决策：用简单的 inline 自审替代耗时 25 分钟的子代理评审，捕获 3-5 个真实 bug 只需 30 秒。
5.3 两个技能的衔接
输入 → 输出链
用户需求（模糊的自然语言）
│
brainstorming
│
▼
设计文档：docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
│
writing-plans
│
▼
计划文档：docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
│
subagent-driven-development（第 6 课）
│
▼
代码 + 测试 + 提交记录
衔接的关键点
brainstorming → writing-plans 的衔接
brainstorming 完成后：
"Spec written and committed to `<path>`. Please review it and let me know
if you want to make any changes before we start writing the implementation plan."
等用户确认后，才调用 writing-plans。这个"用户审阅门"是 v5.0.1 加入的 — 之前 AI 会自动从设计跳到计划，用户没机会审阅设计文档。
writing-plans → 执行的衔接
"Plan complete and saved. Two execution options:
1. Subagent-Driven (recommended) - fresh subagent per task, two-stage review
2. Inline Execution - execute tasks in this session with checkpoints
Which approach?"
Scope Check 回溯机制
writing-plans 有一个"安全网"：
## Scope Check
If the spec covers multiple independent subsystems, it should have been
broken into sub-project specs during brainstorming. If it wasn't,
suggest breaking this into separate plans.
如果 brainstorming 阶段漏掉了大项目分解，writing-plans 会在这里兜底。这是防御式设计 — 每个环节都对上游错误有容错。
5.4 设计原则：隔离性与清晰边界
两个技能都强调了一个共同的设计原则：
Break the system into smaller units that each have one clear purpose,
communicate through well-defined interfaces, and can be understood
and tested independently.
这个原则的实际应用：
在 brainstorming 中（设计层面）：
- 每个组件有清晰的职责
- 组件之间通过明确的接口通信
- 每个组件可以独立理解和测试
在 writing-plans 中（文件层面）：
## File Structure
Before defining tasks, map out which files will be created or modified
and what each one is responsible for.
先确定文件结构，再定义任务。每个文件有一个职责。
在执行中（代码层面）：
给 implementer 子代理的指令中也强调了这个原则：
## Code Organization
Each file should have one clear responsibility with a well-defined interface.
If a file you're creating is growing beyond the plan's intent, stop and report.
从设计到计划到执行，"单一职责 + 清晰接口" 贯穿始终。
实践作业
作业 1：模拟 brainstorming 流程
选一个你想做的小功能（比如"一个命令行的番茄钟"），模拟 brainstorming 的 9 步流程：
- 你当"用户"，AI 当"设计师"（或你扮演两个角色）
- 逐步走完 checklist
- 输出一份设计文档
作业 2：写一个 3 任务的计划
基于作业 1 的设计文档，写一个 3 任务的实施计划：
- 每个任务有 Files、Steps、Code、Commands
- 确保无占位符
- 做一次自审（spec 覆盖 + 占位符扫描 + 类型一致性）
作业 3：寻找衔接点
重新阅读两个技能的完整文档，标注所有"调用其他技能"的地方。画出完整的技能调用图。
本课自检清单
- 能说出 brainstorming 的 9 步 checklist
- 理解 HARD-GATE 和 Anti-Pattern 的设计意图
- 能编写符合"No Placeholders"原则的实施计划
- 理解 2-5 分钟粒度的设计理由
- 能说出两个技能之间的输入输出衔接
下节预告
第 6 课：多代理协作 — 子代理架构全解析
brainstorming 产出了设计，writing-plans 产出了计划。下一课，我们看计划是怎么被执行的 — 一个主控 Agent 如何派发子代理、构造它们的上下文、处理它们的返回状态，以及双阶段评审是如何工作的。
