一个丑网页的逆袭，OpenSpec 规范驱动开发全流程

lincats

348人浏览 · 2026-08-25 07:10:05

lincats · 2026-08-25 07:10:05 发布

一个丑网页的逆袭，OpenSpec 规范驱动开发全流程

一个网页界面，第一版做出来又丑又不顺手，改到想推倒重来。有人换了条路，用 OpenSpec 这套规范驱动开发框架，先把要建的东西写清楚，再让 AI 照着规格一步步施工。结果，丑小鸭真的变成了小天鹅。这篇文章，就是那次网页开发的完整实战复盘。

我很早就想介绍一篇实战用 OpenSpec 做规范驱动开发的文章，一直没找到合适的切入点，直到看到作者 Sean Kochel 的这条视频，让我眼前一亮。

Sean 是一名持续拆解 AI 编程工具的作者。这条视频没停在功能介绍，实打实地拿一个食谱应用界面，从一处丑到不想用的第一版出发，一路改造成接近设计稿的成品。

整个过程用到的，就是 OpenSpec 这一套规范驱动框架，六条命令走完全程，init、explore、propose、validate、apply、archive。下面顺着 Sean 的演示，把每一步拆开看。

一、先看清 OpenSpec 站在哪

动手之前，Sean 先把市面上的 AI 编程工具分成了三类。这个分类很实用，新手能一眼看清 OpenSpec 的位置。

第一类，规格驱动。 OpenSpec 就属于这一类，同类的另有 GitHub Spec Kit。这类工具的核心，是把 spec 当作驱动一切的产出物。使用者要花大量时间把「到底要建什么」对齐清楚，之后的事情就顺理成章地往下走。

这套逻辑的心智模型可以概括成八个字，人负责编排，agent 负责协助。Sean 的判断是，刚接触 AI 编程的人走这条路更稳，因为它逼着人把要建什么、它要做什么想清楚。

第二类，流程执行。 比如 Agent Skills、Obra Superpowers、Compound Engineering。它们也有流程引导人走，但真正的价值，是把最佳实践和纪律植入编码过程。像 Obra 的 TDD 红绿重构，是任何时候构建东西都该做的事，而很多工具没有内置它。

第三类，自主流水线。 比如 BMAD、GSD。这类工具给出一堆工具，让人定义一件事之后可以走开，回来时它已经建好，几乎不用干预。

二、真实的痛点，第一版丑到不想用

这条视频要解决的，是一个很多开发者都踩过的坑。第一版做出来了，回头看却觉得有点丑，不像想要的样子。功夫没少花，就是差口气。

Sean 的解法分两步。他先打开 Claude Design，花时间把东西搭出来，做出一个专业得多、真正想用的参照稿。左边是食谱页现在的样子，右边是它理想中的样子。

接下来要做的，是用一个规格驱动的开发工具，把这个差距一步步弥合掉，把所有页面都搭出来。

这里还藏着一个 Sean 很看重的态度，技能可以串联。用一个工具，不等于不能用别的。他仍然会用 Obra 的 using-git-worktrees 技能建一个工作树，跑完测试，确认开工前的基线是干净的。

三、先对齐再动手，init 与 explore

上手很轻。装上包，进项目目录运行 openspec init，选个环境，工具就就绪了。

它还带一个 onboarding 技能。第一次用，onboard 命令会带着走完第一个功能，很适合新手。

Sean 为了演示每一步，选择手动跑。他回到 Claude Design，复制那里给出的命令，让 Claude Code 去抓取设计稿。

接着敲下第一个命令 explore。

explore 是 Sean 格外看重的一步。很多工具默认使用者已经知道自己要建什么，直接跳进 spec。OpenSpec 给了一个可选的探索期，动手前先跟模型把歧义谈清楚，随时能在要改动的地方深入。

读完全部上下文后，它开始对要做的事做推理。这个例子里有几处歧义要回答。要彻底改 DESIGN.md 里记录的设计系统，这份文件又被 AGENTS.md 引用，两者都得更新。仓库结构也要动，因为新设计稿的信息架构没法干净映射到现有结构。Sean 贴了一点额外上下文，它就开始澄清计划的各个部分。

这一步的价值，是把推进前该留意的点提前标出来。太多人直接上手就建，对话里浮现的假设，模型在构建时当场拍板，结果大概率不满意。explore 是不用太多仪式就能绕开这些坑的办法。

四、三份文档，把要改什么讲清楚

探索充分之后，下一步生成提案，命令是 opsx:propose。拿到手的是三份 Markdown，一份 proposal、一份 system design，另有任务清单。

设计系统文件里，第一块是主要架构决策。设计系统的 token 怎么迁移，这些组件怎么在系统里重建（因为它们和 Claude Design 里的不一样），应用的路由和整体架构怎么变，都写在这里。

提案则更聚焦「这个项目里到底要改什么」。设计系统迁移、搭新页面、建新组件库、留意数据模型和 API 基于新界面要怎么变（Sean 明确说现在先不做全部后端改动）。它是一份非常清晰的 changelog，写清这份 spec 到底要改什么。

然后是分阶段、实际要执行的任务序列。三份文档分工明确，提案回答「是什么、为什么」，设计文档给出「怎么改」的高层，任务文件给出实现步骤。这个约定很实用，所有假设和决策都被清楚记录，每步都有具体任务可依。

最后拿到一个 specs 目录。书签迁移、发现页、关注的人、设计系统迁移，每个主要工作块各有一份独立 spec，写清到底需要哪些场景。

五、多一道视觉校验，validate 与 apply

真正应用改动之前，Sean 特别看中 validate 这一步。这个例子里，他想让工具多做一轮检查，用 Chrome 浏览器扩展 MCP 去验证自己的成果。

这道工序不是流程里自带的。多数工具只在功能上描述一件事该怎么工作，很少说它视觉上到底该长什么样。从另一个工具迁移设计系统时，这恰恰是容易丢的地方。Sean 只是要求加一步，必须验证。现在它做完新 spec，会跑一遍 validate，确保没丢 spec 里的关键细节。

随后跑最后一个命令 apply，把项目目录或标识符传进去，让它开工。

一个小提示，Sean 用 Chrome flag 启动了 Claude，这样自检时能真正和浏览器交互。他认为，这种前端视觉检查，对 vibe coding 的成品质量提升明显。

这一轮连续跑了约两个小时，几乎没怎么干预。他仅有的干预，是某个节点开了 auto mode，让它别再停下来问问题。算上那些停顿，实际花了三四个小时；开了 auto mode 后，纯处理时间是两小时八分钟。

六、跑完看看结果

有几处 Sean 特别想检查。第一处是发现页。设计非常清晰，侧栏、hero 区的「What's Cooking Now?」、筛选搜索选项，再往下是编辑式的内容排布。进到屏幕里看，非常接近。

他在一个很大的屏幕上，侧栏和中间栏的间距有点乱，但顶部区域、人名、菜名、trending forks、editorial pick，这些都很到位。

另一处是用户主页。点进 Ren 的页面，之前非常朴素，几乎空白。现在接近设计稿了，但有几处不对，该有强调色的地方、某些按钮的对齐、按钮应该大致同尺寸且有一个强调。

对于这么大范围的设计系统重构，它已经非常接近。食谱页更是巨大的升级。

规格驱动这一面，正是它能做得这么有效的原因。有清晰的功能需求、清晰的验证步骤，也知道该去核对参照设计稿。

七、archive 归档，让文档不脱节

一个出人意料有用的点，是它怎么收尾一个功能分支。跑 archive 命令，本质是把这套变更积累的 spec 和上下文，同步回应用根部的真值源。

很多人抱怨应用文档越维护越难，这就是 OpenSpec 帮人维护的方式。去看 OpenSpec 文件夹，所有工作都在 changes 文件夹里。

每个净新增功能，书签视图、发现页、关注页、设计系统更新，都拿到自己的 spec 文件。

价值在于，未来改动时，手里有一份持久的真值源，描述这东西该怎么工作。往后改了书签功能再去归档，如果破坏了这份 spec 的关键部分，它会揪出问题，逼人跟它对账。这样就不会冒出黑天鹅，不会出现那些藏在项目里、被改坏了却没人察觉的东西。它逼着为每个主要功能维护一套活着的规格说明。全部完成后，拿到一个 archive 文件夹，任务、提案、怎么保证视觉保真，全被存下来，随时能回头查。

八、进阶工作流与 sync

基础流程之外，另有三套工作流。第一套其实是两个一起用，new 和 continue。让这个工具出众的一个范式，是它对规划采取迭代式。有想法开始规划，过程中冒出信息，想把它重新融回计划里，new 和 continue 就是解法。发起 new 命令。前端改完了，接下来补后端，让 API 路由就位、数据模型就位。