引言：大道至简

在前两篇文章中，我们共同探讨了规格驱动开发（SDD）的核心理念，并对三大主流工具进行了全景式扫描。其中，OpenSpec 以其“无侵入、纯文件、跨工具”的轻量级特性脱颖而出，成为许多团队和个人开发者拥抱 SDD 的首选入口。

但 OpenSpec 的魅力远不止于其易用性。它的设计背后，蕴含着一套深刻而优雅的工程哲学。它证明了，一个强大的系统，其根基可以异常简单。本文将深入 OpenSpec 的内核，剖析其 “规格即真理” 的核心思想，并通过其精巧的目录结构和工作流，展示如何用最朴素的文件系统，构建起一个高效、可靠的人机协作闭环。

图1：OpenSpec 的核心哲学——“规格即单一事实来源”。一份结构化的 Spec.md 文件，成为连接 AI、Git、测试与文档的中心枢纽。

---

一、设计哲学：为什么是“纯文件”？

OpenSpec 的设计始于一个根本性的洞察：任何需要额外服务器、数据库或复杂配置的工具，都会在无形中提高采用门槛，并可能成为未来的技术负债。

因此，OpenSpec 做出了一个大胆而明智的选择：完全基于文件系统。这意味着：

• 零运维成本：你不需要部署任何服务，只需一个文本编辑器。
• 天然版本控制：所有的规格文件都存在于 Git 仓库中，与代码同生共死，享受完整的版本历史、分支管理和代码审查流程。
• 极致的可移植性：你的项目可以在任何地方被克隆、理解和继续开发，因为所有上下文都已内嵌在 specs/ 目录中。
• 与现有生态无缝集成：无论是 VS Code、Cursor 还是 JetBrains IDE，它们都能完美地读取和索引这些 Markdown 文件。

这种“纯文件”策略，使得 OpenSpec 不是一个需要你去适应的“新工具”，而是一种你可以轻松融入现有工作流的“新习惯”。

---

二、核心结构：specs/ 与 changes/ 的双轨制

OpenSpec 的全部奥秘，都藏在项目根目录下的两个文件夹里：specs/ 和 changes/。这两个目录构成了一个清晰、高效的双轨工作流。

图2：OpenSpec 的目录结构与工作流。changes/ 是创新的孵化器，specs/ 是知识的沉淀池，二者通过标准化的流程紧密相连。

1. changes/ 目录：创新的孵化器

• 角色：这里是所有新想法、新功能、Bug 修复的起点。
• 内容：每个待办事项都以一个独立的 .md 文件形式存在，例如 add-dark-mode.md 或 fix-login-timeout.md。
• 状态：这些文件代表的是“未完成的承诺”或“待验证的提案”。它们是动态的、可变的，鼓励团队在此进行讨论和迭代。

2. specs/ 目录：知识的沉淀池

• 角色：这里是项目所有已实现能力的权威记录，是系统的“活字典”。
• 内容：文件通常以 [feature-name]-v[version].md 命名，如 user-authentication-v1.md。每个文件都描述了一个稳定、已上线的功能模块。
• 状态：这些文件是静态的、只读的（除非有新的变更提案被批准）。它们是新人了解项目、AI 理解上下文、以及未来重构工作的唯一可靠依据。

工作流：从提案到归档

1. 创建提案：openspec proposal add-dark-mode 命令会在 changes/ 目录下生成一个模板文件。
2. 协同精炼：开发者与同事或 AI 助手共同完善提案细节，明确需求、约束和技术方案。
3. 应用与实现：openspec apply add-dark-mode 命令会将提案内容固化，并触发 AI 生成代码。开发者进行最终审查和调整。
4. 归档沉淀：功能上线后，运行 openspec archive add-dark-mode，该提案文件会被重命名为 dark-mode-v1.md 并移入 specs/ 目录，正式成为项目知识资产的一部分。

这个简单而强大的双轨制，确保了项目的 活力（通过 changes/ 快速迭代）与 稳定性（通过 specs/ 积累可靠知识）得以兼得。

---

三、实践价值：OpenSpec 如何解决实际问题？

场景1：棕地（Brownfield）系统改造

面对一个缺乏文档、逻辑混乱的遗留系统，直接重构风险极高。使用 OpenSpec，你可以采取“逆向规格化”策略：

• 针对一个待改造的模块，先在 changes/ 中编写你对其当前行为的理解（即逆向工程出的 Spec）。
• 与团队确认这份 Spec 的准确性。
• 然后，再基于这份准确的 Spec，提出新的改进方案。
• 这样，每一步改造都有据可依，大大降低了“改出新 Bug”的风险。

场景2：高效的跨团队协作

当多个团队需要对接同一个 API 时，传统的 Swagger 文档常常滞后于代码。而 OpenSpec 要求 API 提供方在 specs/ 中维护一份最新的、结构化的规范。消费方团队可以直接将此 Spec 作为集成的唯一依据，甚至可以用它来生成 Mock Server 或客户端 SDK，从根本上解决了“联调靠猜”的痛点。

场景3：AI 上下文管理

对于 AI 编程助手而言，最大的挑战是理解项目的全局上下文。specs/ 目录的存在，为 AI 提供了一个高质量、高信噪比的知识库。当你要求 AI 修改某个功能时，它可以首先查阅 specs/[feature].md，确保自己的修改不会破坏已有的契约和约束。

---

四、结语：简单，但不简陋

OpenSpec 的力量，在于它用最简单的 Unix 哲学——“一切皆文件”——解决了一个复杂的现代工程问题。它没有炫酷的 UI，没有复杂的后台，但它提供了一种清晰、可靠、可持续的工作方式。

它提醒我们，优秀的工程工具，其目标不是取代人类的思考，而是放大人类的意图。通过将模糊的“氛围”转化为精确的“规格”，OpenSpec 让人与 AI 的协作变得前所未有的高效和愉快。

预告：在下一篇《动手实践：用 OpenSpec 重构一个真实项目》中，我们将不再停留于理论，而是手把手带你在一个开源项目上应用 OpenSpec，从创建第一个提案到完成归档，体验完整的 SDD 工作流。敬请期待！