企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能
• 开发工具

本文围绕 superpowers-zh 仓库中 tests/subagent-driven-dev/svelte-todo/design.md 这一设计规格文档展开，剖析它以 localStorage 持久化 Todo 清单应用为载体的完整需求定义方式，并揭示它如何在subagent-driven-development（子智能体驱动开发）技能中充当可自动验收的测试夹具。读完本文，你将掌握如何用一份「功能 + 界面 + 组件结构 + 数据模型 + 验收标准」五段式的设计文档驱动多智能体流水线，把规格转化为可测试、可交付的实现。

设计文档的定位：SDD 技能的自动化测试夹具

在 superpowers-zh 的subagent-driven-development技能体系中，设计文档（design.md）不只是给人看的蓝图，它更是测试夹具的权威规格。仓库里存放着两套完整的测试场景：Go 语言实现的 go-fractals 分形命令行工具 和 Svelte 前端应用 svelte-todo，后者即本文主体。

这两份文档的共同使命，正如 tests/subagent-driven-dev/run-test.sh 所演示的那样：先由脚手架脚本把设计文档与实现计划复制进一个全新 git 仓库，再以一句claude -p "Execute this plan using superpowers:subagent-driven-development. The plan is at: ..."启动整个子智能体流水线，最后用真实测试命令（如npm test && npx playwright test）验证产出是否达标。因此，这份 design.md 的质量直接决定了自动化演练能跑多深——它必须是「可裁决」的规格，而不只是愿望清单。

功能清单：一条 Todo 应用的完整需求基线

设计文档的 Features 一节定义了应用的全部功能边界，共七项：

• 新增 Todo（Add new todos）
• 标记完成 / 未完成（Mark todos as complete/incomplete）
• 删除 Todo（Delete todos）
• 按 全部 / 进行中 / 已完成 过滤（Filter by: All / Active / Completed）
• 一键清除所有已完成项（Clear all completed todos）
• 持久化到 localStorage（Persist to localStorage）
• 展示剩余未完成项计数（Show count of remaining items）

这份清单是计划（plan.md）与验收标准（Acceptance Criteria）的共同出处。值得注意的是，它刻意维持了「经典 TodoMVC 最小集」的规模：没有拖拽排序、没有编辑行内文本、没有服务端同步——这种刻意收敛正是设计文档作为 SDD 夹具的可贵之处，它让每个任务都能被一个隔离上下文的实现子智能体独立消化（参见 SKILL.md 中「每个任务一个全新子智能体」的核心原则）。

用户界面设计：用 ASCII 原型锁定交互布局

设计文档用一段等宽 ASCII 线框图锁定了界面结构，这是纯文本规格中最有约束力的部分——实现者必须照此还原布局：

┌─────────────────────────────────────────┐ │ Svelte Todos │ ├─────────────────────────────────────────┤ │ [________________________] [Add] │ ├─────────────────────────────────────────┤ │ [ ] Buy groceries [x] │ │ [✓] Walk the dog [x] │ │ [ ] Write code [x] │ ├─────────────────────────────────────────┤ │ 2 items left │ │ [All] [Active] [Completed] [Clear ✓] │ └─────────────────────────────────────────┘

从这幅原型可以读出四个必须实现的交互区域：

1. 顶部输入区：文本输入框 + Add 按钮，对应TodoInput组件；
2. 中部列表区：每条 Todo 由复选框、文本、右侧删除按钮（X）组成，完成项显示对勾（✓）与删除线，对应TodoItem；
3. 状态栏：左侧显示未完成计数「X items left」，右侧依次为 All / Active / Completed 三个过滤按钮与 Clear Completed（✓）按钮，对应FilterBar；
4. 整体容器：由App.svelte负责装配。

结合 plan.md 中任务 10（Styling and Polish）的要求，这份原型还隐含了视觉细则：完成项需要删除线与弱化色（muted color）、当前激活的过滤按钮需要高亮、输入框需要有 focus 样式、删除按钮在桌面端悬停时出现（移动端常显）、整体需要响应式布局。

组件架构与目录结构：单一职责的文件划分

设计文档给出了明确的组件树，这是实现子智能体唯一的文件组织依据：

src/ App.svelte # Main app, state management lib/ TodoInput.svelte # Text input + Add button TodoList.svelte # List container TodoItem.svelte # Single todo with checkbox, text, delete FilterBar.svelte # Filter buttons + clear completed store.ts # Svelte store for todos storage.ts # localStorage persistence

这是一份「关注点分离」的教科书式划分：

• store.ts负责全局状态（Svelte store），对应计划任务 2，需要导出addTodo(text)、toggleTodo(id)、deleteTodo(id)、clearCompleted()四个操作函数；
• storage.ts负责 localStorage 持久化，对应计划任务 3，需要实现loadTodos(): Todo[]与saveTodos(todos: Todo[])，并对 JSON 解析错误做优雅降级（返回空数组）；
• TodoInput / TodoItem / TodoList / FilterBar四个组件各司其职，分别对应计划任务 4–7；
• App.svelte承担集成职责，持有过滤状态（默认'all'），计算过滤后的列表并逐组件下发 props，对应计划任务 8。

从实现子智能体视角看，这种「一文件一职责」的结构让 implementer-prompt.md 中「每个文件应有单一明确的职责和定义清晰的接口」的约束变得可执行——实现者不需要任何额外判断就能落盘。

数据模型：类型即契约

设计文档用 TypeScript 类型定义了唯一的数据契约：

interface Todo { id: string; // UUID text: string; // Todo text completed: boolean; } type Filter = 'all' | 'active' | 'completed';

两个要点值得展开：

1. id 使用 UUID：这保证了 localStorage 中的每条记录全局唯一，删除与切换状态操作可以稳定定位目标条目；计划任务 2 要求createTodo类函数生成新条目时填充该字段；
2. Filter 为联合类型：'all' | 'active' | 'completed'三个字符串字面量把过滤逻辑限制在三个可穷举的取值内，直接服务于计划任务 9 的过滤语义——'all'显示全部、'active'仅显示未完成、'completed'仅显示已完成，并透传给 FilterBar 的onFilterChange回调。

这份契约在计划中也被严格继承：FilterBar 的 props 签名（todos: Todo[]、filter: Filter、onFilterChange: (f: Filter) => void）与数据模型一一对应，没有出现类型漂移。

验收标准：9 条可机器验证的完成定义

设计文档末尾的 Acceptance Criteria 是整套流水线的「有约束力的权威」（binding authority）——SDD 技能中的任务审查者会拿着它逐条比对 diff：

1. 可输入文本并按回车或点击 Add 新增 Todo；
2. 点击复选框可切换完成状态；
3. 点击 X 按钮可删除 Todo；
4. 过滤按钮显示正确的 Todo 子集；
5. 「X items left」显示未完成项计数；
6. 「Clear completed」移除全部已完成项；
7. 刷新页面后 Todo 仍然存在（localStorage 持久化）；
8. 空状态下显示有帮助的提示文案；
9. 所有测试通过。

注意第 8 条：空状态提示并非 UI 原型中的显式元素，而是写在验收标准里——这正是设计文档「补全原型盲区」的地方。对应到计划任务 6，TodoList组件需要在列表为空时渲染「No todos yet」这类文案。第 9 条则把「测试全绿」直接写进了规格，为审查者的规格合规性检查提供了硬性依据。

从设计到计划：12 个任务的实现分解

design.md 并不直接描述实现步骤，真正的执行剧本在姊妹文档 plan.md 中，两者以「设计为权威、计划为论证」的关系配套使用。计划将整个应用拆解为 12 个可独立分派的原子任务：

每个任务都遵循统一的「Do / Verify」模板：Do 列出具体动作与产出文件，Verify 给出可执行的验证手段。这种结构化任务文本正是 SDD 技能中scripts/task-brief能够自动化抽取的前提——该脚本按标题把单个任务完整抽到独立简报文件（scripts/task-brief 同时兼容英文Task N与中文任务 N标题），让实现子智能体「一次 Read 调用就读完需求」，而无需翻阅整个计划。

跑通整套演练：scaffold.sh 与 run-test.sh 的配合

设计文档的价值最终通过自动化演练被验证。两条脚本构成完整的测试链：

scaffold.sh（用法：./scaffold.sh /path/to/target）负责在目标目录搭建隔离演练场：

1. mkdir -p目标目录并git init；
2. 把design.md与plan.md复制进去；
3. 写入.claude/settings.local.json，授予 Read/Edit/Write 及npm:*、npx:*、mkdir:*、git:*的 Bash 权限，供实现子智能体读写；
4. 建立初始提交；
5. 打印启动提示：用--plugin-dir指向 superpowers 插件目录执行计划。

run-test.sh（用法：./run-test.sh svelte-todo --plugin-dir <path>）则完成编排：先调用 scaffold 脚本，再以claude -p携带--dangerously-skip-permissions --output-format stream-json --verbose启动无头执行，把流式 JSON 输出（含 token 用量）落盘到时间戳目录，最后给出两条验证命令：npm test（单元/组件测试）与npx playwright test（E2E）。对 svelte-todo 场景而言，「测试全绿」正是验收标准第 9 条的直接落地。

规格如何驱动审查：设计文档在 SDD 流水线中的作用

这份 design.md 之所以称得上「有约束力的权威」，在于它贯穿了 SKILL.md 定义的完整审查闭环：

• 准备阶段：控制者通读计划并扫描冲突时，若计划与设计冲突，以设计为准作出裁决并记入账本；
• 任务审查：审查者拿到任务简报、实现者报告与审查包（scripts/review-package PLAN_FILE BASE HEAD生成含提交列表、stat 摘要与 -U10 上下文 diff 的文件），对照设计文档逐条核验规格合规性——缺失、多余、理解偏差三类问题都会作为发现抛出，并按 Critical / Important / Minor 定级；
• 修复循环：发现未解决时唤回原实现者（第 1–3 轮）或换更强模型（第 4–5 轮），修复后由 re-review-prompt.md 定向复审，对每条发现给出 ADDRESSED / NOT ADDRESSED 结论，每任务最多五轮；
• 最终审查：所有任务完成后，用最强模型对整个分支做宽范围审查，账本中「延后的 Minor」与「已搁置的发现」一并送审。

设计文档中「验收标准」这一节，正是任务审查者核对「规格 ✅/❌」时逐条打勾的清单；而 task-reviewer-prompt.md 要求审查者「不要信任报告、对照 diff 核实、给每条检查附 file:line」，则保证了这份规格被真正执行而非被口头满足。

总结：一份可执行规格的构成要素

纵观 design.md，它用五个小节回答了「做什么、长什么样、怎么组织、数据是什么、怎样算完成」五个问题，且每个答案都能被下游机械地消费：功能清单喂给计划分解，ASCII 原型喂给 UI 实现，组件树喂给文件结构，数据模型喂给类型与 store，验收标准喂给审查者与测试脚本。这份文档本身就是 SDD 方法论「规格是有约束力的权威」的最佳注脚——当设计文档可裁决时，子智能体流水线才能做到「高质量、快速迭代」。

• AI 技能
• AI 插件
• 人工智能
• 开发工具