[JS/TS] OpenSpec规范驱动开发实践：从需求对齐到代码实现的AI编程工作流

在使用AI辅助编程时，你是否遇到过这些问题？

满怀期待地输入需求，AI却理解错核心意图，生成了大量不需要的功能；你只想修改一行代码，它却顺手重构了整个文件；经过几轮对话后，AI已经完全偏离了最初的目标，代码越来越混乱。

这常常让人陷入自我怀疑：是我的描述能力不行？还是AI本身就没那么智能？有没有方法能让AI写代码时像一个靠谱的同事，而非一个天马行空的实习生？

关键在于，我们需要一种方法，在AI开始编写任何代码之前，就将“要做什么”清晰、无歧义地定义下来。

AI编程的效率陷阱与需求漂移

AI编码助手的能力毋庸置疑，它能在几秒内生成数百行代码，效率远超人类。但问题也随之而来——它生成得太快了，快到来不及仔细思考，AI就已经开始“脑补”并扩展需求了。

例如，当你提出：“帮我增加一个用户登录功能。” AI可能会提供：

• 邮箱登录（但你实际想要的是手机号验证）
• 第三方登录（例如微信、GitHub登录，但你并不需要）
• 甚至修改了数据库表结构（而你原本只想调整前端界面）

这并非AI理解能力差，而是因为需求仅存在于松散的聊天记录中，缺乏一个稳定、可复用、可审查的结构化规范。AI被迫在模糊的指令下进行猜测。

OpenSpec：为AI编程设计的规范驱动开发工具

简单来说，OpenSpec是一个旨在实现 「规范驱动开发」 的工具。它的核心价值在于：将“需求共识”从易逝的聊天记录，升级为一套可审查、可追溯、可执行的正式规范。

一个形象的比喻是：

• 直接让AI写代码：如同边画边猜，最终成果充满不确定性。
• 使用OpenSpec：如同先绘制详细的施工图纸，经各方确认无误后，再按图施工，确保结果符合预期。

OpenSpec核心四步工作流

OpenSpec的流程清晰而克制，包含以下四个阶段：

起草提案 → 审查对齐 → 按规范实现 → 归档演进

1. 起草提案：聚焦“做什么”，而非“怎么写”

这是最关键且反直觉的一步。当你提出需求后，AI不会立即编写代码，而是会先提出一系列澄清问题，例如：

• 功能的边界条件是什么？
• 用户界面（UI）应放置在何处？
• 数据结构是否需要向后兼容？
• 核心的业务逻辑或算法口径如何定义？

这一步的目标是：将所有“未来几乎必然导致返工的模糊点”，在编码开始前全部暴露并明确。

2. 审查对齐：在人和AI间建立共识

在此阶段，你可以像评审代码Pull Request一样，详细评审这份结构化后的需求提案：

• 需求描述是否完整无遗漏？
• 技术实现方案是否合理？
• 是否覆盖了所有关键的使用场景？

反复修改，直至消除所有疑虑。在需求阶段进行修改，成本几乎为零；而一旦进入代码阶段，修改成本将呈指数级上升。

3. 按规范实现：AI进行“精准施工”

当提案通过审查后，AI才会基于这份明确的规范开始编写代码：

• 严格遵循已确认的规范条目。
• 逐项完成分解后的开发任务清单。
• 保持代码风格和项目结构的一致性。

这时你会感受到，AI从一个依赖“灵感”的选手，转变为了一个可靠的“执行型”工程师。

4. 归档更新：规范即活文档，历史可追溯

任务完成后，OpenSpec会自动：

• 归档本次变更的所有记录。
• 将更新后的规范合并到项目文档中。
• 形成完整的项目演进历史。

几个月后回顾代码，你将不再困惑于“这段代码当初为何要这样写？”，因为设计决策已被完整记录。

实战案例：为番茄钟App添加自定义专注时长

我曾使用OpenSpec为一个名为ForestFocus的番茄钟应用添加“自定义专注时长”功能。整个过程并非直接编码，而是首先经历了AI连续5轮的深入追问：

1. 时长的可选范围及步长是多少？（如25-120分钟，步长5分钟）
2. 设置入口的UI放在哪个界面？
3. 统计数据（如专注总时长）的口径如何与新模式适配？
4. 旧有的专注记录数据如何兼容处理？
5. 应用内象征成长的“树木”生长阶段如何重新计算？

每一个问题，如果不在编码前思考清楚，都极有可能在后续开发中引发问题甚至返工。

最终，这个需求被拆解为44个清晰的任务，分布在9个实现阶段中逐步完成。UI、数据层、统计逻辑及可视化效果一次实现到位，一些潜在的Bug在代码归档前就被提前发现并修复。其效果并非“减少了修改次数”，而是实现了 “几乎无需返工”。

OpenSpec解决了哪些核心痛点？

1. 固化需求，避免漂移：将需求从“聊天式的模糊理解”转化为“结构化的明确规范”。
2. 技术决策可追溯：所有的设计决策都被记录在design.md等规范文件中，有据可查。
3. 保留完整项目记忆：任何变更的时间、原因、影响范围都有完整记录，关于人工智能工具的协作过程变得透明。
4. 使AI成为可靠执行者：重点不是让AI变得更聪明，而是让其变得更可控、更可预测。

适用与不适用场景

非常适合：

• 改进和迭代现有项目（从1到N的演进）。
• 使用Claude Code、Cursor、GitHub Copilot等AI编程助手的场景。
• 对代码质量、可维护性有较高要求的项目。
• 团队协作或需要长期维护的项目。

不太适合：

• 编写一次性的、简单的脚本。
• 进行快速的、探索性的原型验证。
• 需求本身还处于极度模糊和摇摆的初期阶段。

快速入门指南

通过以下命令可以快速安装并初始化OpenSpec：

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

之后，在你的AI编程工具中，只需输入：

/openspec:proposal [描述你想要实现的功能]

AI将引导你完成后续的完整规范驱动开发流程。

总结

OpenSpec带来的最大启示，并非其功能多么强大，而是它将AI编程从一种“碰运气”的尝试，转变为一种可重复、可管理的“工程化协作”过程。

它建立了一套新的工作范式：

1. 由开发者清晰定义目标。
2. AI协助将目标转化为无歧义的规范。
3. 双方对规范进行确认和审查。
4. AI严格依据规范执行编码。
5. 项目自动积累清晰、可追溯的演进历史。

这才是面向AI时代，更为成熟和高效的软件开发方式。如果你曾受困于AI生成的代码混乱、需求理解偏差，并期望AI能成为一个真正可靠的合作伙伴，那么OpenSpec值得你深入尝试。