OpenSpec 实战指南
AI Coding 正在经历一次关键转变。过去，AI 编程助手通过代码补全、模块生成不断提升开发效率，但随着应用深入，团队逐渐发现：AI 会写代码，却无法理解项目长期积累的架构决策、开发规范和隐性知识，导致代码一致性和可维护性面临挑战。
如今，AI Coding 正从“让 AI 直接写代码”走向“先定义 Spec，再让 AI 实现”，Spec-Driven Development 正成为新的开发范式，让团队知识沉淀为项目资产，让 AI 从代码生成者转变为规范执行者。
过去一年，AI Coding 的进化速度令人目眩。
从 GitHub Copilot 到 Cursor，从 Claude Code 到 OpenCode，AI 编程助手已经渗透到开发者的日常工作流程中。代码补全、重构建议、Bug 修复、甚至整个模块的生成——AI 正在重新定义"写代码"这件事。
我们已经从：
"帮我写个正则"
发展到：
"帮我实现整个模块架构"
但在经历效率狂欢之后，越来越多团队发现一个更深层问题：
AI 可以写代码，但无法自动理解项目的"灵魂"。
什么是项目的"灵魂"？
是架构决策背后的权衡，是团队多年沉淀的编码规范，是领域知识的隐性积累，是那些从未被写进文档但每个人都默守的约定。
AI 不懂这些。
它可能：
使用错误架构模式——在新模块引入六边形架构，而项目一直是分层架构
违反团队规范——用 PascalCase 命名函数，而团队约定是 camelCase
引入不允许的依赖——擅自添加 moment.js，而项目已统一使用 dayjs
用完全不同风格实现相同逻辑——三种不同的错误处理方式共存于同一代码库
更危险的是：
这些"小问题"会累积。
每次 AI 提交的代码，都在悄悄稀释项目的一致性。直到有一天，你发现代码库变成了一座没人敢动的"屎山"。
原因只有一个：AI 没有被规范约束。
这推动 AI Coding 从：
Chat-Driven（你问我答，凭感觉写代码）进入 Spec-Driven（先有规范，再写实现）时代。
Part1
AI Coding 正在进入 Spec-Driven 时代
当前主流工具，本质都在解决同一个问题：
如何约束 AI。
这些方案各有千秋：
.cursorrules 简单直接，但能力有限，只能表达"不要用什么"、"用什么风格"
CLAUDE.md 更灵活，可以描述工作流程，但仍是单文件约束
OpenCode 的 Spec/Plan 模式更进一步，引入了阶段化设计
但问题在于：
这些规则：
无法跨工具复用——你在 Cursor 写的规则，Claude Code 读不懂
无法继承和组合——新项目要从零开始配置
无法版本化管理——规则的变更历史难以追溯
规范成为工具资产，而不是团队资产。
这就是：AI Coding 的"规则孤岛"。
每个工具都在建立自己的规范体系，而团队的知识被切割成碎片，散落在各个 .xxxrules 文件中。
Part2
OpenSpec：让 Spec 成为真正的 Single Source of Truth
为了解决这个问题，Fission AI 开源了OpenSpec
（https://github.com/Fission-AI/OpenSpec）
OpenSpec 不是 IDE，也不是另一个 AI 编程工具，而是一套 Spec-Driven Development 工作流和规范结构。
它的核心思想是Spec 必须独立于 AI 工具存在，这意味着Spec 不属于 Cursor，不属于 Claude Code，不属于任何工具。
Spec 属于项目本身。
不是工具，任何 AI Coding 工具都可以基于同一个 Spec 工作。
这带来的好处是：
团队知识沉淀在 Spec 中，而不是散落在各工具的配置文件
切换工具时，Spec 随项目迁移，无需重新配置
Spec 可以被 Review、被讨论、被版本控制——就像代码一样
Part3
OpenSpec 的核心结构
OpenSpec 将软件开发拆分为四个明确阶段：
proposal.md
spec.md
design.md
tasks.md这四个文件，构成了一个完整的"需求 → 设计 → 实现"链路。
含义：
关键点：AI 不再负责"思考要做什么"
而是只负责"实现 Spec"，这是一个根本性的角色转变：
以前：AI 既要理解需求，又要设计方案，还要写代码——它怎么可能不出错？
现在：AI 只需按照已经定义好的 Spec 执行——任务边界清晰，错误可控
Part4
最关键原则：Proposal 只创建一次，然后持续修改
很多团队会犯一个错误：
每次有新想法，就创建新的 Proposal。
结果是Spec 文件泛滥，互相矛盾，没人知道哪个是最新的。
正确流程：
第一步：
/opsx:propose 支付模块生成：
openspec/changes/payment/之后：
不要重复 propose
而是持续修改：
proposal.md
spec.md
design.md
tasks.md
例如：
完善 spec.md：
增加：
- webhook 支持
- retry 机制
- error handling 必须符合项目规范AI 会直接修改 spec 文件。
Spec 文件成为唯一真实来源。
Single Source of Truth。
Part5
完整开发流程
这是真实生产环境中的完整 OpenSpec workflow：
Step 1：创建 Proposal（立项）
定义功能目标：
/opsx:propose 新增 Stripe 支付模块生成：
proposal.md此时不要写代码，先完善 proposal：
完善 proposal.md，使其符合现有支付架构Proposal 阶段的核心问题：
为什么要做这个功能？
解决什么问题？
范围边界在哪里？
不做什么？
Step 2：生成 Spec（定义需求）
基于 proposal 生成 spec：
/opsx:continue生成：
spec.md继续修改 spec：
完善 spec.md：
必须支持：
- webhook
- retry
- audit logSpec 阶段的核心问题：
具体有哪些功能点？
接口长什么样？
成功的标准是什么？
Step 3：生成 Design（架构设计）
继续：
/opsx:continue生成：
design.md完善设计：
修改 design.md：
必须复用现有 payment service
禁止新增数据库Design 阶段的核心问题：
模块如何划分？
技术选型是什么？
与现有系统如何集成？
Step 4：生成 Tasks（实现计划）
继续：
/opsx:continue生成：
tasks.md确认任务拆分合理。
Tasks 阶段的核心问题：
任务拆分是否合理？
依赖关系是否清晰？
优先级是否正确？
Step 5：执行实现（AI 写代码）
现在才执行：
/opsx:applyAI 将严格按 spec + design + tasks 写代码，而不是自由发挥。
这一刻，AI 终于成为真正的"实现者"：它不需要猜测需求，不需要做架构决策，只需要执行。
Step 6：验证（可选但推荐）
openspec validate --strict验证：Spec 与实现一致。
Step 7：归档（完成开发）
/opsx:archive paymentSpec 进入 archive，成为项目永久资产。
归档的 Spec 可以被后续功能参考、复用，成为团队知识库的一部分。
完整流程总结：
/opsx:propose
修改 proposal.md
/opsx:continue
修改 spec.md
/opsx:continue
修改 design.md
/opsx:continue
修改 tasks.md
/opsx:apply
/opsx:archivePart6
OpenSpec 最强大的能力：工具解耦
Spec：属于项目，而不是工具
你可以：
用 Cursor 写前端
用 OpenCode 重构后端
用 Claude Code 写测试
它们遵守同一个 Spec，这意味着：
团队不会被单一工具绑定
不同成员可以使用各自顺手的工具
工具升级或替换时，Spec 无需迁移
Spec 成为团队真正的"共同语言"。
Part7
Spec-Driven Development：软件工程范式改变
传统模式是人写代码，AI 辅助。
人的精力被大量消耗在"写代码"这件低价值工作上。
未来模式是人写 Spec，AI 写代码。
人的精力集中在"想清楚要做什么"这件高价值工作上。
开发者角色从 Coder 变为 Architect。
这不是"AI 取代程序员"的故事，这是"程序员升级为架构师"的故事。
AI 负责重复性的代码编写，人负责创造性的架构设计。
分工更清晰，价值更聚焦。
Part8
团队必须遵守的三条最佳实践
原则一：每个 Feature 只创建一次 Proposal
每个 Feature 只创建一次 Proposal，后续持续修改 Spec 进行完善，而不要重复 propose。同一个 Feature 的 Proposal 只需要创建一次，之后通过持续迭代和优化 Spec 来完善方案，而不是反复创建新的 Proposal。
原则二：Spec 必须进入 Git
Spec 必须进入 Git 管理体系，因为 Spec 本身就是代码的一部分，需要像代码一样进行 Review 和 Version Control。Spec 的每一次变更，都记录着项目的发展过程，其变更历史就是整个项目演进的历史。
原则三：Spec 精度决定代码质量
Spec 的精度决定了最终代码的质量。Spec 越精确，AI 的执行结果就越可靠；模糊的 Spec 会产生模糊的代码，而精确的 Spec 才能产生精确的代码。
Part9
结语
AI Coding 工具会不断变化，今天流行 Cursor，明天可能又会出现新的工具。但 Spec 不会改变。Spec 是软件真正的灵魂，它承载着团队对系统的理解、对架构的决策，以及对未来发展的规划。
未来的软件开发模式中，开发者负责维护 Spec，AI 负责实现代码。代码只是 Spec 的编译结果，而 Spec，才是真正值得团队长期投入和精心雕琢的作品。
作者
李冠军｜高级AI交付工程师
不是bug，是隐藏功能
END
往期精选
