企业官网建设流程全解析

这两年只要你在折腾 AI 编程，八成听过这几个关键词：OpenSpec、Superpowers、规格驱动。尤其当你用 Claude Code、Codex 这类 agent 工具写过几个像样的项目之后，大概率会遇到同一个坎：小需求 AI 一把梭很爽，一旦项目变复杂、功能变多，AI 就开始"精神分裂"，改 A 坏 B，前面定好的设计后面全忘，甚至自信满满地写出和需求完全相反的逻辑。问题不在模型不够聪明，而是你缺少一套能"管住" AI 的流程。

OpenSpec 解决的是"规格"问题——强制 AI 在动手前把需求、现状、目标状态写成可验证的文档；Superpowers 解决的是"动作"问题——把头脑风暴、写计划、执行计划这套工程流程变成 AI 能直接调用的技能。两个工具配合起来，就是给 AI 编程装上"规格驱动"的完整打法。这篇我把自己实际跑通全栈项目的组合用法、目录结构、提示词模板、踩坑记录全整理出来，适合正在用 agent 编程、又对交付稳定性不满意的人。

1. 为什么 AI 编程总在"半路翻车"——失控根源先搞清楚

1.1 AI 不是不聪明，而是"记性差"还"缺框架"

先说个扎心的结论：现在的 coding agent 模型能力已经够强，真正拖后腿的是"工作方式"。你让 Claude 单独实现一个函数，它写得又快又好；你让它从头到尾做一个包含数据库设计、API 层、前端页面、权限控制的全栈项目，前半小时还挺正常，一小时后就开始前后矛盾。

根源有两条。第一条是上下文窗口的物理限制。Agent 每轮对话都要把历史记录塞进上下文，项目一大，几百个文件的概要、几十轮修改记录很快就会把窗口塞满。窗口一满，早期的设计决策、约束条件就被"挤"出去了，AI 只能靠猜。第二条是缺少一个外部的"持久化记忆"结构。人类开发有需求文档、有架构图、有代码评审记录，AI 编程如果只靠对话流，那一切都像写在沙子上，潮水一冲就没了。

我做过的项目里有个特别典型的案例：让 AI 做一个包含用户注册、商品列表、购物车、订单结算的小商城。第一轮聊需求，AI 信誓旦旦地说会用 JWT 做认证；写到第三个模块时它突然改用 session，理由是"这样更简单"。你问它为什么改，它说"根据我们之前讨论的"。这就是典型的失忆——前面的决定根本没被记录，或者说记录被上下文冲掉了。

1.2 规格驱动的本质：把"需求-设计-实现"重新拆开

传统软件工程早就吃过这个亏。上世纪瀑布模型时代，大家觉得"先写完整需求文档再开发"太慢、太僵化；后来敏捷流行，大家又觉得"能跑的代码胜过完备的文档"。但请注意，敏捷从来不是说"不要文档"，而是说"要刚好够用的文档"。

AI 编程时代，这个道理被放大了十倍。AI 的优势是执行速度极快、代码生成能力强，弱项恰恰是全局规划、长程记忆、优先级判断。你让 AI 边想边写，它就容易陷入"局部最优"——每个文件单独看都没问题，合在一起就是一团乱麻。规格驱动（spec-driven）的核心，就是强行把"想清楚"和"写出来"分成两个阶段：先用人类可读、AI 可执行的规格文档把所有决策固定下来，再让 AI 按规格实现。

这里有个关键点：规格不只是给人看的，更是给 AI 看的。传统需求文档写"系统要支持用户登录"，AI 看完还是不知道怎么做；但如果你写成"当前系统没有任何认证机制，期望状态是用户可以通过邮箱 + 密码注册并登录，登录后服务端签发 JWT，前端将其存储在 HttpOnly Cookie 中，所有 /api/private 下的请求必须携带有效 token"，那 AI 就不用"设计"了，只需要"翻译"成代码。设计的风险由人脑承担，实现的工作交给 AI，这分工才是合理的。

2. OpenSpec 和 Superpowers 分别是什么——两个工具的分工逻辑

2.1 OpenSpec：给 AI 编程加一层"可变档案"

OpenSpec 是一个开源工具，官方定位是"spec-driven development for AI agents"。它做的事情可以理解成：在项目里建立一个 specs/ 目录，把所有关于系统的规格描述、变更提案、验收标准都放进去，并且用一套命令让 AI 能创建、更新、验证这些规格。

它的核心概念叫 Change Proposal（变更提案）。每次你要加功能、改逻辑、重构模块，不是直接让 AI 改代码，而是先创建一份 proposal，里面必须写清楚三件事：Current State（当前状态）、Desired State（期望状态）、Implementation Plan（实现计划）。Current State 描述现状，Desired State 描述改完之后的系统应该是什么样，Implementation Plan 列出改造步骤。写完这三段，AI 才被允许动代码。

我特别喜欢它的地方在于，OpenSpec 会把规格变成"可回归"的东西。每份 proposal 都对应一个 spec.md 文件，里面有明确的功能要求和验收清单。项目后续迭代时，AI 可以随时打开这份文件，对照检查自己有没有把旧功能改坏。这相当于给 AI 编程加了个"版本管理"——不是管代码，是管"意图"。

而且 OpenSpec 有配套的 prompts，放在 agents/ 目录下，专门给 AI 用的。你用 Claude Code 时可以让它读取这些 prompt，AI 就知道"哦，这个项目是规格驱动的，我改代码之前要先写变更提案"。这个细节很重要——工具再强，AI 不知道规则等于白搭。

2.2 Superpowers：把工程方法论变成 AI 的"职业技能"

Superpowers 是 Jesse Vincent（很多人叫它 obra）做的一套 Claude Code skills。它的思路和 OpenSpec 不一样，OpenSpec 管的是"规格"，Superpowers 管的是"流程"——具体说，是把软件工程里成熟的步骤拆解成 AI 可以一步步执行的小技能。

Superpowers 最核心的三个技能是：brainstorming（头脑风暴）、writing-plans（写计划）、executing-plans（执行计划）。听着像项目管理词汇，其实每个都是一套严格的提示词剧本。

以 brainstorming 为例，它会让 AI 先问你一系列问题，澄清需求边界、用户场景、非目标、风险点，全部聊完才会进入下一步。这解决了一个大痛点：很多人让 AI 写代码，直接说"帮我做一个博客系统"，AI 就闷头开写。Superpowers 会强迫 AI 先"访谈"你，把模糊的需求理清，再往下走。这也符合"先规格、后实现"的逻辑。

writing-plans 更狠，它会让 AI 把整个任务拆成一个一个互相关联的 plan 文件，每个文件有目标、有步骤、有验证方法，并且会主动把任务规模控制在"一次只做一件事"。执行的时候，executing-plans 会让 AI 严格按顺序执行，每完成一步就检查一次状态，不会跳步也不会自己发挥加功能。

2.3 组合的核心逻辑：一个管"存量"，一个管"增量"

我摸索下来，这两个工具是互补关系，不是竞争关系。OpenSpec 更偏"项目档案"——它维护的是整个系统当前长什么样、要变成什么样、为什么这么变；Superpowers 更偏"工作流引擎"——它维护的是 AI 在开发时按什么步骤走、用什么节奏推进。

实际组合中有一个技巧：你可以把 OpenSpec 作为 Superpowers 的"外部命令"集成进去。比如在 writing-plans 阶段，让 AI 先调用 openspec 创建变更提案，再把提案里的实现计划拆成 Superpowers 的 plan 文件。这样，OpenSpec 的"档案"和 Superpowers 的"动作"就闭环了：需求变更先被记录到规格库，再被拆解成可执行的计划，最后由 AI 按计划实现并回到规格库验证。

简单说：OpenSpec 管"这个项目应该是什么样"，Superpowers 管"怎么一步步把它做成这样"。两个都装上，才是完整打法。

3. 组合落地：我跑通全栈项目的完整实操流程

3.1 环境准备：Claude Code + Superpowers + OpenSpec 三件套

先说环境。我主力用的是 Claude Code，所以下面的命令以它为准。你如果用的是 Codex、OpenCode 这类支持 skills 的 agent 工具，思路完全一样，只是安装命令有差异。

第一步，安装 Claude Code。这个官方文档很清晰，装完在项目目录下运行 claude 就能进入交互界面。

第二步，安装 Superpowers。在项目里建一个 .claude/skills 目录，把 Superpowers 的仓库 clone 进来：

mkdir -p .claude/skills git clone https://github.com/obra/superpowers.git .claude/skills/superpowers

装完检查一下目录结构，应该能看到 .claude/skills/superpowers/skills/ 下面有一堆子技能，比如 brainstorming、writing-plans、executing-plans。

第三步，安装 OpenSpec。它是以命令行工具的形式工作的：

npm install -g @openspec/cli

然后在项目根目录初始化：

openspec init

初始化之后，项目里会出现 specs/ 和 proposals/ 两个目录，以及 agents/prompts/ 下面的一些 markdown 提示词文件。这两个目录就是后面所有规格工作的根据地。

3.2 第一步：用 brainstorming 把模糊需求聊清楚

很多人装完工具就直接让 AI 写代码，这是最大的浪费。我现在的习惯是，任何新需求进来，第一件事是让 AI 进入 brainstorming 模式。

实际操作时，我在 Claude Code 里输入类似这样的提示词：

请使用 Superpowers 的 brainstorming 技能，和我一起澄清下面这个需求的细节： "做一个团队任务管理工具，支持成员管理、任务分配、进度跟踪。" 在理清所有关键问题之前，不要写任何代码。

然后 AI 就会进入提问模式。它可能会问：用户角色有哪些？任务的状态流转是什么？成员权限怎么划分？需不需要通知功能？移动端适配吗？这个阶段看起来"浪费时间"，其实是整个流程里性价比最高的环节。需求每清晰一分，后面返工的概率就降十分。

有个细节我提醒一下：brainstorming 过程中，AI 会根据你的回答生成一份"需求简报"文档，存到项目的 plans 目录或者其他指定位置。这份简报别删，它是后面写 OpenSpec 提案的素材。

3.3 第二步：用 OpenSpec 写 Change Proposal

需求聊清楚之后，进入规格阶段。这一步的工作是创建一个 Change Proposal，把需求翻译成"当前状态 + 期望状态 + 实现计划"的格式。

在命令行里执行：

openspec create proposal

命令会交互式问你提案的标题、描述，然后生成一个类似 proposals/2025-05-01-team-task-management/ 的目录，里面有一个 proposal.md 文件。打开这个文件，把 brainstorming 的结果填进去。

以任务管理工具为例，一份合格的 proposal 大概长这样：

• 当前状态：系统没有任何任务管理能力，只有基础的用户注册与登录功能。
• 期望状态：系统支持创建项目，项目下有任务列表；任务有关联负责人、截止日期、状态字段（待处理/进行中/已完成）；项目管理员可以增删成员并分配任务。
• 实现计划：
  1. 设计任务与项目的数据模型，新增 projects、tasks、project_members 三张表；
  2. 实现项目 CRUD API，加权限校验，只有项目成员可访问；
  3. 实现任务 CRUD API，支持按状态筛选与负责人筛选；
  4. 前端新增项目看板页面，任务卡片支持拖拽更新状态；
  5. 补充自动化测试，覆盖权限校验和任务状态流转。

写完 proposal，运行 openspec validate 校验格式，再把提案"提案通过"状态更新一下。这时候 AI 的"设计工作"就完成了，后续它只需要照单执行。我遇到过很多次，写完这份提案之后，AI 写代码的准确率明显上了一个台阶，因为"设计"和"实现"混在一起时它容易偷懒，一旦设计被明文固定，它的角色就从"决策者"降级成了"执行者"，反而更可靠。

3.4 第三步：用 Superpowers 的 writing-plans 拆解执行计划

提案通过后，不要急着让 AI 写代码。下一步是把提案里的实现计划进一步拆成 Superpowers 的 plan 文件。

在 Claude Code 里输入：

请读取 proposals/2025-05-01-team-task-management/proposal.md，然后使用 writing-plans 技能，基于提案中的实现计划创建详细的执行计划。每个计划文件要包含：目标、前置条件、具体步骤、验收方法。

Superpowers 会生成一个 plans/ 目录，下面按顺序排列几个 markdown 文件。拆分的粒度很关键。按照 Superpowers 的默认策略，一个 plan 文件应该只做"一件事"。比如上面的实现计划拆成了五个 plan：

• 01-database-schema.md：设计数据模型并生成迁移文件；
• 02-project-api.md：实现项目 CRUD 与权限校验；
• 03-task-api.md：实现任务 CRUD 与筛选逻辑；
• 04-frontend-board.md：前端页面与交互；
• 05-tests-and-validation.md：补测试并做全链路验证。

每个 plan 文件里，Superpowers 会写清楚"当前状态""目标状态""执行步骤""验证方式"，还会要求 AI 在执行时"一次只做这个文件的事，不要提前碰后面的文件"。这正好和 OpenSpec 的提案形成呼应，规格库负责回答"做什么"，计划文件负责回答"按什么顺序做"。

3.5 第四步：executing-plans 执行与 OpenSpec 验收闭环

计划写完了，最后一步是执行。在 Claude Code 里输入：

请使用 executing-plans 技能，按顺序执行 plans/ 目录下的所有计划文件。每个计划完成后，对照计划文件中的验收标准做自检，然后更新执行状态。全部完成后，再对照 OpenSpec 提案的 Desired State 逐条验证。

执行过程中有个细节值得注意：Superpowers 要求 AI 每完成一个 plan，就在文件里记录实际执行结果和偏差情况。这相当于"过程文档"——以后出了问题，你可以追溯是哪个环节偏离了计划。

全部执行完之后，我还会手动做一轮 OpenSpec 验收。做法很简单，让 AI 打开对应的 spec.md 或 proposal.md，把 Desired State 里的每一条期望状态当成验收清单，逐条检查实现。这一招治"AI 自我感觉良好"特别有效。比如提案里写"任务列表支持按负责人筛选"，AI 可能只实现了按状态筛选，它自己没意识到；但你把 Desired State 贴在它面前，它就能对照查漏。

4. 关键细节：这样写规格才不会被 AI 带偏

4.1 规格写"行为"和"约束"，不要写"实现方案"

这是我最想强调的一点。刚用 OpenSpec 时，我犯过一个低级错误：在 Desired State 里写"使用 Redis 缓存用户数据"。结果 AI 真的去引入 Redis，哪怕这只是个日活几百的小工具，徒增运维成本。

规格的正确写法是描述"行为"和"约束"，而不是替 AI 决定技术选型。比如需要缓存，你应该写"热门任务列表的读取响应时间应低于 200ms，且在高并发下不崩溃"，至于用 Redis 还是内存缓存还是数据库索引，那是 AI 在实现阶段该权衡的事。

有个简单的判断标准：如果你在规格里写的内容是"怎么办"，删掉；如果写的是"是什么、要什么样的行为、必须满足什么约束"，留着。规格越贴近"验收标准"，AI 发挥和跑偏的空间就越小。

4.2 一个 Change Proposal 只做一件事

OpenSpec 的提案机制天然鼓励小步提交，但很多人不习惯，总想在一个提案里塞三四个功能。这在 AI 编程场景下是致命的——提案一大，AI 的上下文里要维持的信息就多，实现到后面，前面的约束早忘了。

我的经验是：如果一个功能的变更涉及多个数据模型、多个模块的大改，要么把它拆成多个 proposal，要么在 proposal 里分成多个阶段。判断标准很简单，想象你要给这个提案写"验收清单"，如果你发现清单超过十条，而且条目之间没有强关联，就应该拆分。

拆分之后还有个好处：出 bug 时排查范围小。曾经有一次我同时改了用户认证和支付逻辑，结果订单接口报错，AI 花了十几轮才定位到是认证中间件改动引起的。如果当时拆成两个提案，这个问题一眼就能看到。

4.3 上下文管理的三个实用技巧

规格驱动流程本身能缓解上下文压力，但还不够。我在实践中还沉淀了三个小技巧：

技巧一：历史文档勤归档。每一轮开发完成，把已经完成的提案移动到 specs/ 目录并标记为"已实现"。AI 下次读取的时候，只需要看 specs/ 目录下的索引，不用把整个 proposals/ 历史都塞进上下文。

技巧二：关键约定放 README。把项目里最重要的规格约束、技术决策写进 README.md 的最前面。Claude Code 启动时默认会读 README，这样 AI 第一眼就能看到"本项目是规格驱动开发，改代码前先看 specs/ 目录"，比任何提示词都管用。

技巧三：用文件状态代替长对话。执行计划时，不要依赖对话里的"记得我们之前说过"，而是让 AI 把每一步的状态写回 plan 文件。这样就算中间断了对话、甚至换了一个新会话，AI 也能根据文件状态接续执行。我跑全栈项目时经常一个会话跨好几天，全靠这个技巧保证连续性。

5. 常见问题与实战排查

5.1 AI 不按规格执行，自己"自由发挥"怎么办

这是我最常被问到的问题。症状是：你明明在提案里写清了期望状态，AI 实现时还是加了多余的功能，或者改动了不该改的模块。

我的排查思路分两步。第一步，检查 AI 有没有真正"读到"规格文件。很多时候不是它故意不遵守，而是它启动时没有加载相关文件，根本不知道有规格存在。解决方法是把 OpenSpec 和 Superpowers 的提示词放进 Claude Code 的 CLAUDE.md 里，让 AI 每次启动都先读规则。

第二步，检查规格本身是否可验证。如果 Desired State 写得太抽象，比如"系统性能更好"，AI 无从判断自己是否满足，自然就按自己的想法来了。改法是把描述改成可测试的行为，比如"在 1000 个任务的数据量下，看板页面的首次加载时间不超过 1 秒"。有明确验收标准的规格，AI 才不敢乱来。

5.2 规格和代码不同步，文档成了摆设

这个问题在新人用规格驱动时特别常见。提案写归写，后面 AI 改代码时直接改了实现，但没人回来更新规格。几轮迭代之后，specs/ 目录里的内容和真实系统完全对不上，规格文件反而成了误导。

我的习惯是把"更新规格"也纳入执行计划。在 writing-plans 阶段，明确要求 AI 在完成代码实现后，diff 一遍提案里的 Desired State，把已实现、未实现、实现有偏差的部分都标出来。这个动作不花多少时间，但能保证规格库始终反映真实系统。另外，每次用 OpenSpec 创建新提案时，先让 AI 读一遍 specs/ 目录下相关的旧规格，避免新提案和旧规格冲突。

5.3 流程太繁琐，agent 干到一半"卡住"或超时

规格驱动流程确实比直接让 AI 写代码多好几个步骤，刚上手时会觉得慢。实际跑下来你会发现，前期的慢换来的是后期少返工。如果 agent 在执行到一半时上下文耗尽或者卡住，我有两个处理办法。

第一个办法是从 plan 文件恢复。因为 Superpowers 要求每步都回写状态，所以你只要让新会话继续执行对应编号的 plan 文件即可，它知道哪些步骤做完了、哪些没做。

第二个办法是手动缩小执行范围。卡住通常是因为一个 plan 文件里塞了太多事，或者 AI 在某个环节过度探索。我会在提示词里加限制条件，比如"只实现 01-database-schema.md，不要提前改动 API 层代码"。把范围缩到最小，AI 反而更容易顺畅完成。

5.4 几个常见问题的速查表

最近一些朋友试用后问我各种问题，我把高频的几个整理成了速查表：

写在最后的一些实在话

这套组合打法我用了差不多三个月，最大的感受不是"AI 写出的代码变强了"，而是"我终于能搞清楚 AI 在做什么了"。规格文件就像开发过程的仪表盘，它让你在任何一个节点都能回答三个问题：系统现在是什么状态？要变成什么状态？距离目标还差几步？光这三点，就比"黑箱式"地信任 AI 要踏实得多。

如果你正准备上手，我的建议是别贪多。第一次用，只装 OpenSpec，把一个需求跑通；第二次加 Superpowers 的 brainstorming 和 writing-plans；熟悉之后再把 executing-plans 接进闭环。一步到位的结果大概率是你被流程搞烦，然后弃用。工具只是帮你建立纪律的，真正管用的，是你愿意在 AI 动手前多花十分钟把事情想清楚——这个习惯放在任何时代都不亏。