企业官网建设流程全解析

这段时间我把 OpenSpec、Superpowers 和 SDD + TDD 这套工作流真正跑起来之后，才算把“让 AI 写代码”这件事从偶尔惊艳、经常翻车，变成了过程可预期、结果可检查。这篇文章不是某个工具 README 的复述，而是我从零开始搭建这套工作流的完整记录，包括安装、目录设计、六步实操、测试先行怎么做，以及我在真实项目里踩过的坑。适合已经用上 AI 编程工具，但总觉得交付质量不够稳定的开发者参考。

先说一个基本判断：OpenSpec 解决的是“需求怎么被严格描述”的问题，Superpowers 解决的是“AI 怎么按套路干活”的问题，SDD 是把它们串起来的流程，TDD 是这个流程里最硬的验收环节。单独用任何一个，效果都有限，组合起来才像一套完整的工程方法。

1. 为什么这套工作流能治“AI 写代码不稳定”的毛病

1.1 从“提示词工程”到“规格驱动”：协作方式的根本变化

以前我们让 AI 写一个功能，通常是在对话框里甩一句话：“帮我加一个用户注册功能。”然后就等着。AI 会自己脑补出一大堆细节：要不要邮箱验证、密码规则是什么、注册成功跳哪里、重名怎么办。运气好它能猜对一半，运气不好整个结构都跑偏。更麻烦的是，这种对话是一次性的，没有任何产物沉淀下来。下次想改需求，只能再把整个历史对话甩给 AI，让它从一堆文字里找上下文。

SDD 的全称是 Specification-Driven Development，规格驱动开发。它的核心思想是：把“需求长什么样”这件事，从对话里抽出来，写成一份结构化的、放在代码仓库里的 markdown 文档。这份文档就是 AI 的施工图。AI 看图纸施工，而不是靠猜。

这个转变非常关键。对话是流式的，看过了就没了，而且越长越容易混乱。规格是持久化的，它在仓库里，可以被 review、被 diff、被回滚。你可以说“这次只做规格里的这些内容”，AI 就不会自己加戏。这就像你给装修师傅一张平面图，而不是发一段语音描述，强调的是“少解释、看得见、改得动”。

1.2 OpenSpec、Superpowers、SDD、TDD 到底各管什么

很多人会把 OpenSpec 和 SDD 混为一谈，其实它们是两层的概念。SDD 是一种开发方法论，OpenSpec 是把方法论落地的工具。没有 OpenSpec，你也可以在项目里手动建一个specs目录然后往里写 markdown，但那样规格的创建、变更、状态管理、归档都得自己维护，团队之间没有统一约定，很快就乱了。

Superpowers 又是另一个维度。如果说 OpenSpec 管“需求文件”，那 Superpowers 管“AI 的能力”。它是给 AI 编程工具安装的一套技能包，里面是一组结构化的操作技能，比如“如何做计划”“如何写测试”“如何做代码审查”。每次干活的时候，AI 会先从这套技能库里选取合适的流程来执行，而不是靠自己的自由发挥。

它们的关系我用一个表来说明：

这套组合里，SDD 是为 AI 定边界，TDD 是为代码定底线。OpenSpec 是容器，Superpowers 是执行者。缺了哪一个，另外几个都会变得难落到实处。

2. 环境准备：先把 OpenSpec 和 Superpowers 装好再谈流程

2.1 OpenSpec 的安装、初始化与目录结构

我先说安装。OpenSpec 通常以命令行工具的形式使用，你需要一个能运行脚本的本地环境，Node 和 Python 按需准备。不管你用哪种方式安装，目标都是拿到一个openspec命令，可以在项目根目录执行。

如果你拿到的是仓库源码，典型的做法是把项目拉下来，把可执行文件所在目录添加进 PATH。我自己比较喜欢这种源码方式，因为出问题的时候我可以直接读源码排查，而不是对着一个黑盒猜原因。装好之后在项目根目录跑一下：

openspec --version

能正常输出版本号，说明环境没问题。然后执行初始化：

openspec init

这会在项目里生成一个specs目录，里面通常有需求、变更、归档、当前状态这几块结构。我用过的典型目录结构是这样的：

project/ ├── specs/ │ ├── requirements/ # 需求背景类文档 │ ├── changes/ # 待实施的变更规格 │ ├── current/ # 当前系统规格快照 │ └── archive/ # 已完成的规格归档 ├── .claude/ │ └── skills/ # Superpowers 技能放这里 └── src/

这套目录的直觉是：没有归档前，改动都放在changes里，每一份改动就是一个独立文件夹；完成并验证后，再合并进current或归档到archive。这样整个项目的规格演进像 git 一样有迹可循，而不是所有需求堆在一份巨型文档里。

2.2 Superpowers 的安装方式与技能目录

Superpowers 的安装相对简单，它本质上是把一组技能文件放进 AI 工具能识别的目录。以支持目录型技能的 AI 编程工具为例，你可以把技能包克隆到项目的.claude/skills目录下，或者在全局的配置目录里安装，看你自己想让哪些项目使用。

我建议先全局安装、验证有效后，再下沉到具体项目。原因很简单：全局安装只需要配一次，项目里直接就能用；如果你一开始就绑定单项目，后来想换个项目用还得重新配，比较麻烦。

装完之后，每个技能应该是一个独立的文件夹或 markdown 文件，里面描述了这个技能的目标、适用场景和操作步骤。你可以直接打开看一眼，看它是不是真的在引导 AI 按“规划、执行、检查”的顺序做事，而不是简单的一两句话提示词。

2.3 装完先别急着写代码，做一次链路验证

我见过太多人装完工具就直奔需求，结果跑了两步发现 AI 根本没加载技能，规格读不到，测试包缺失，整个流程像多米诺骨牌一样倒。所以安装完必须先做链路验证。

第一步，确认 AI 工具能访问specs目录。你可以在对话里问它：“请列出 specs 目录下所有文件。”如果它能准确列出来，说明文件访问正常。

第二步，确认 Superpowers 技能已加载。你直接问：“你有哪些可用技能？”看它能不能说出你安装的那几个技能名称。如果答不上来，大概率是安装目录不对，或者需要重启会话。

第三步，跑一个最小的端到端验证：随便写一个一行规格，让 AI 按规格生成一个函数，同时写一个测试。全流程走通之后，再开始真正的工作。这个验证只需要十几分钟，但能避免后面连续踩坑，很值得。

3. SDD 六步实践：把需求变成可以交付的规格

3.1 前两步：需求澄清与上下文收集，拒绝“第一版就直接写”

SDD 六步是我自己平时用的版本，比官方流程更偏实践一些。第一步是需求澄清。你要让 AI 先别写代码，而是把需求里的问题列出来。比如“给 Todo 应用加标签筛选”这个需求，听起来很清楚，但里面其实藏着不少问题：

• 是单选标签还是多选？
• 筛选条件要不要和现有“完成状态”筛选叠加？
• 没有匹配结果时显示什么？
• 标签数据从哪里来，硬编码还是用户可维护？

这些如果不先问清楚，AI 随便猜一个，做出来的东西基本不是你要的。

第二步是上下文收集。让 AI 读取项目里相关代码，理解现有结构。我会明确要求它读取特定文件，比如路由、数据模型、列表组件，然后输出一个简短的“现状摘要”，让我确认它没有理解偏。这两步的目的，是让 AI 在写任何正式文档前，先对齐一个共同的“现实基础”。

这个阶段我通常用这样的提示词：

现在先不要写实现代码，也不要写任何规格文档。 请按顺序完成： 1. 列出你对这个需求的所有疑问； 2. 读取 src/todos 下的相关文件，输出当前数据模型和列表逻辑摘要； 3. 等我确认之后，再进入下一步。

实测下来，这个约束非常关键。一旦让 AI 直接跳进“写规格”或者“写代码”，它很容易跳过问问题的步骤，自作主张做决定。主动把它的动作卡住，它才会真正执行。

3.2 中间两步：编写规格与评审，验收标准必须可测试

第三步是写规格。OpenSpec 里一份变更规格通常长这样：背景、目标、范围、用户故事、验收标准。我强调一点：验收标准必须写成“可以验证真假的句子”，不要出现“更好的体验”“提升效率”这类形容词。

什么是可验证的句子？“用户选择标签后，列表只显示包含该标签的 Todo。”这是可验证的。相反，“用户能够方便地筛选标签”就是不可验证的，因为“方便”没有标准。

第四步是评审规格。评审者可以是人，也可以让 AI 扮演评审者。我一般会让两个独立会话互相评审，或者在一个会话里让 AI 先写完规格，再换一个角色去挑毛病。比较实用的评审维度有三个：

• 每条验收标准是否真的可以被一个测试覆盖。
• 有没有边界情况被遗漏，比如空列表、超长文本、重复标签。
• 范围是不是过大，有没有把不该做的功能写进来。

评审阶段发现问题，改起来非常便宜，就是改几个字。等代码写完再发现需求错了，那就是重写，成本完全不同。

3.3 后两步：拆解任务、实现与验证，让 AI 照着规格干活

第五步是拆任务。规格评审通过之后，我不直接让 AI 写整个功能，而是让它先根据验收标准列出实现任务，每个任务对应一个或几个测试。这一步会把不可见的复杂度摊开，比如“写数据库查询逻辑”“改列表渲染”“加空状态组件”。任务拆完，AI 的工作路径就清晰了。

第六步是实现与验证。实现必须严格按 TDD 顺序来：先写测试，看到测试失败，再写实现，最后让测试通过。一个任务一个任务地推进，不要一次性把所有测试全部写出来然后再实现，那样一旦整体跑不过来，很难定位问题。

全部实现完后，还要做一层整体验证：跑全量测试，跑代码检查，然后人工抽查关键路径。人工抽查很重要，因为 AI 写的测试有可能和 AI 写的实现错得一致，两边都错但相互匹配，测试全绿，功能却是坏的。我的习惯是，在验收场景里手动操作一遍，再决定是否关闭这个变更。

4. 把 TDD 融进 SDD：测试先行这件事到底怎么做

4.1 行为级测试在前：每条验收标准对应一条用例

TDD 在 SDD 里的落点，不是在功能写完后再补测试，而是在规格评审通过后，马上根据验收标准写行为级测试。这一步很多人会偷懒，但我建议你宁可不写实现，也要先把测试写好。

所谓行为级测试，就是站在用户视角写测试，不管内部实现细节。比如“标签筛选”这个功能，行为测试就是：先创建几个带标签和不带标签的 Todo，再点选一个标签，断言列表里显示的条目标记。

这里有一个技巧：把规格里的每条验收标准，翻译成测试用例的时候，用表格来做映射。这样做的好处是，任何一个验收标准丢了，都能从测试用例里找出来，不会出现“需求写着，但测试根本没覆盖”的情况。

4.2 单元测试的 red-green-refactor 节奏

行为级测试覆盖的是“功能是否正确”，单元测试覆盖的是“内部逻辑是否健壮”。在 AI 协作场景下，单元测试尤其重要，因为 AI 在改内部实现的时候，很容易破坏一些隐藏逻辑，比如排序规则、时间格式、权限判断。没有单元测试兜底，这些破坏往往要等很久才能被发现。

单元测试要遵守 red-green-refactor 节奏：

1. 先写一个当前必然失败的测试，运行它，确认失败，且失败原因符合预期。
2. 写实现代码，让这个测试变绿。
3. 重构代码，保持测试全绿。

这个节奏放在 AI 场景里有一个容易出错的地方：AI 有时候会自动“跳过”失败步骤，先把实现和测试一起写出来，然后告诉你“测试通过了”。这时候你无法判断测试到底有没有测到逻辑，因为测试目标一开始就通过了。所以我在提示词里会明确要求：每完成一个任务，必须先贴出“测试失败的输出”，再贴出“测试通过的输出”。两次输出都在，才算走完流程。

4.3 规格变更时，先改测试再改实现

开发和需求有个永恒的矛盾：需求一定会变。规格驱动的好处是需求变更时，第一修改点很明确。但真正的纪律在于顺序：先改规格，再改测试，最后改实现。这个顺序保证了每一步都有据可依。

我举一个真实例子。原来规格写的是“支持单个标签筛选”，后来产品说要支持多选。正确的流程是：

1. 改规格文件里的范围描述和验收标准，把“单个”改成“多个”。
2. 改测试用例，新增“多个标签同时筛选”的场景。
3. 运行测试，确认新用例失败。
4. 修改实现代码，让所有测试通过。

如果反过来写，先改代码，再改测试，你很容易忘了更新某个验收标准，最后测试虽然全绿，但规格和实现已经不一致了。规格和实现的“漂移”，就是从这个细小的顺序问题开始的。

5. 实操记录：从一条规格到全栈功能交付的全过程

5.1 需求场景：Todo 应用增加标签筛选

这次实操我选了一个比较小的需求，方便你完整看到流程如何走通：给一个全栈 Todo 应用增加“标签筛选”功能。技术栈是前端 React + 后端 FastAPI，数据存在 SQLite 里。这个需求涉及前端组件、后端接口、数据查询三层，足够演示 SDD 和 TDD 如何配合。

需求描述只有一句话：“用户可以根据标签筛选 Todo 列表。”如果直接让 AI 写，它可能给你做单个标签筛选，也可能做多个下拉框，甚至可能顺便加一个标签管理页面。范围不清，交付质量完全看运气。所以我决定走完整套流程。

5.2 规格文件长什么样：一个可直接抄的示例

在specs/changes/add-tag-filter目录下，我建了一份README.md。这是整个工作流的核心产物，它定义了 AI 要做什么，也定义了我如何验收。内容如下：

# 变更：Todo 标签筛选 ## 背景 Todo 列表目前只能按完成状态筛选。用户希望按标签过滤， 以便聚焦某类工作。 ## 目标 在列表页提供标签筛选功能。 ## 范围 - 支持单个标签筛选。 - 筛选结果与完成状态筛选可叠加。 - 不涉及标签管理功能。 ## 用户故事 作为 Todo 使用者， 我希望选择标签后只看到相关联的任务， 以便快速聚焦某类工作。 ## 验收标准 - 用户选择标签后，列表只显示包含该标签的 Todo。 - 用户同时设置完成状态与标签时，结果同时满足两个条件。 - 没有匹配的 Todo 时，显示空状态文案"暂无相关任务"。 - 用户清除标签后，列表恢复为完整任务列表。

这份规格写得非常“窄”，每条都能直接翻译成测试。没有“优雅”“快速”“用户友好”这类不可验证的词。评审时我重点看了范围这一节，确认“不涉及标签管理”明确排除掉了 AI 给自己加需求的路。

5.3 让 AI 按规格实现：提示词与落地步骤

规格文件写完并经过我自己审查后，我开始把实现任务交给 AI。我的提示词是这样的：

请读取 specs/changes/add-tag-filter/README.md。 在动手之前，先按 Superpowers 的 plan 技能给出实现计划， 计划中要为每条验收标准列出对应的测试用例。 确认计划后，按 TDD 顺序实施： 先写失败测试，再写实现，再重构。 每完成一步，请贴出对应测试的运行结果。

这段话里有两个关键点。第一是“读取规格文件”，不是把内容复制到提示词里，而是让它去读文件。这样当规格更新时，AI 下一次交互能看到最新内容。第二是“贴出测试运行结果”，这是防止 AI 假装做了 TDD 的强约束。

AI 给出的计划分了四步：后端接口支持标签参数、前端请求参数联动、列表渲染按标签过滤、空状态组件。前两步是后端集成测试，后两步是前端组件测试。计划没问题，我就让它开始执行。

5.4 验证、提交与规格关闭

执行过程中有一个小插曲：后端第一次实现时，AI 只按标签过滤，但没有跟“完成状态”叠加。原因是它在读规格时，误把“筛选结果与完成状态筛选可叠加”理解为两个独立的接口。我让它重新读规格文件中的验收标准，然后补了一个同时传两个参数的集成测试，驱动它修正了实现。这个过程正好体现了 SDD 的价值：分歧发生在规格层面，而不是实现层面，双方可以通过规格文件对账。

最终所有测试通过。我手动打开页面，创建了几条不同标签的任务，验证了单选、叠加筛选、空状态、清除四个场景，全部符合预期。提交的时候，我保留了一个清晰的 git 提交顺序：先规格，再测试，最后实现。

git log --oneline # 8b1a2c3 docs(spec): add tag filter specification # 4e5f6a7 test(api): add tag filter integration tests # 9b8c7d6 feat(api): implement tag filter query # 1a2b3c4 test(frontend): add tag filter UI tests # 7d6e5f4 feat(frontend): implement tag filter UI

最后一步是关闭规格：把changes/add-tag-filter的内容合并到当前规格快照中，并把这个目录移到archive。这样整个变更的生命周期完整闭环，后续任何人查看项目历史，都能知道这个功能是为什么做、按什么标准做的。

6. 常见问题与排查技巧实录

6.1 工作流起不来、包找不到：先在 Python 环境里补依赖

使用包含 Python 脚本的工作流时，我最常遇到的报错是类似“请安装缺失的包以使用此工作流”的提示。这个信息看起来像是工具在指导你操作，但很多时候你按提示装完包，还是起不来。原因通常有两种：装进了错误的 Python 环境，或者项目依赖没有完整声明。

我的排查顺序是这样的：

1. 先确认当前用的是哪个 Python 解释器：which python，确保和项目虚拟环境一致。
2. 确认工作流脚本需要的依赖，比如某个脚本开头 import 了openai、pydantic，那就先pip show pydantic看装没装。
3. 用虚拟环境而不是全局环境安装，避免污染系统环境。

一个具体的踩坑记录：有一回工作流要求装requests，我全局环境里明明有，但项目虚拟环境里没有，脚本一跑就报错。我到虚拟环境里补装之后立刻正常。所以遇到这类报错，第一反应不是怀疑包版本，而是先确认“当前解释器是谁”。

6.2 AI 不听规格指挥：多半是规格写得不够“窄”

如果你明确说了“读取规格文件”，AI 还是自由发挥，不要急着怪 AI。先回去看你的规格文件是不是写得太宽了。我见过太多人把规格写成需求描述：“实现一个用户管理模块，功能要完整。”这样的规格等于没说。范围不清晰，AI 就只能靠猜。

解决办法是把范围写“窄”。在规格里明确列出“不做”的内容，是一个很有效的手段。前面那个标签筛选例子里的“不涉及标签管理功能”，就是专门用来堵住 AI 加需求的。同理，在对话提示词里也建议指定“只处理 specs/changes/xxx 范围内的内容”，尽量不给自由发挥留空间。

如果规格已经很窄，AI 还是跑偏，那可能是技能上下文被截断了。长会话里 AI 很容易忘掉早期的指令。我的做法是把规格路径重复写在每次提需求的末尾，并定期开新会话，让 AI 重新从规格文件读取上下文。

6.3 团队协作中容易踩的坑：规格评审、分支与归档

单人使用时，SDD 和 TDD 主要是改善个人效率。进入团队协作后，还有几个坑值得提前注意。

第一个坑是规格评审和代码评审的顺序反了。规格评审应该在实现之前做，而不是等代码写完再反过来补一份规格。评审规格时发现问题，成本只是改文字；等实现完了再评审，那基本等于返工。我会在团队约法三章：没有通过规格评审的变更，不允许进入编码阶段。

第二个坑是规格文件放在功能分支上，导致并发分支之间看不到彼此的规格变更。我的习惯是让specs目录跟着主干分支走，每次都先从主干拉最新的规格，再开始新变更。规格本身就应该像代码一样先 rebase 到最新，避免多个 AI 会话基于不同的需求基准写代码。

第三个坑是归档不及时。规格目录里如果堆满“已实现但没归档”的变更，时间一长就分不清哪些是新需求、哪些是旧需求。建议每个变更完成后，立即把对应目录从changes移到current或archive。这个动作虽然小，但对维持项目长期可维护性非常重要。

我个人在实际使用中最大的体会是：这套组合拳最值钱的部分，不是某个具体命令，而是它逼着我把“需求”这个最容易马虎的环节，变得可见、可审查、可回滚。AI 的能力只会越来越强，但如果没有一个稳定的容器去承接需求，能力越强越容易发挥到错误的方向上。最后分享一个小技巧：把验收标准写在每份规格的最顶部，实现过程中随时回看。当你发现 AI 开始偏离时，把那份文件再甩给它，通常比你说十句话都管用。