AI 时代的软件工程：如何用 OpenSpec 驱动“全自动”开发

在与 AI（如 Cursor, Codex）协作时，开发者常遇到“逻辑断层”或“幻觉代码”。为了解决这一痛点，
OpenSpec 应运而生。它不是一个工具，而是一套文档驱动（Document-Centric）的协作标准。

通过 OpenSpec，可以实现从“模糊需求”到“原子化提交”的全自动转化。

第一步：确立“项目宪法” —— project.md

project.md 是 AI 的长期记忆，定义了项目的“生存边界”。无论新旧项目，这都是第一步。

1. 存量项目（已有基础代码）

如果项目已动工，可以让 AI 扫描现有结构来填充上下文：

Prompt: “Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions.”

2. 全新项目（从零开始）

对于新项目，需要通过对谈明确核心约束：

• Tech Stack: 明确指定的框架（如 SwiftUI, Vision）。
• Hard Constraints: 关键的技术标准（如导出分辨率、间距、性能指标）。
• Conventions: 架构模式（如 Service Layer, MVVM）。
• ……

第二步：设计蓝图 —— 提案（Proposal）连发

OpenSpec 的核心原则是：设计阶段严禁编写业务代码。当面对复杂功能时，应先让 AI 生成一套完整的提案。

• Proposal 目录：AI 会在 openspec/changes/ 下为每个模块建立独立的“施工图纸”。
• 澄清讨论 (Clarification)：AI 会在 design.md 中标注 Open Questions。
• 例如： 讨论 UI 的交互细节、阴影的参数、或算法的边界。
• 价值：修改 Markdown 的成本远低于重构 Swift 代码。在动笔前，所有模糊点都已通过文档对齐。

第三步：存盘设计 —— 锁定 Git 基准线

在执行代码生成前，务必将所有 .md 设计文档提交。这一步是为了确保“方案”与“实现”在 Git 历史中是分离的。

git add openspec/changes/
git commit -m "docs: finalize design proposals for core modules"

第四步：全量自动化实施 —— Pipeline 模式

当所有图纸通过校验后，可以启动“多米诺骨牌”式的自动化模式。通过设定强制执行，让 AI 按照依赖顺序自我迭代。

自动化执行策略：

1. Atomic Commits: 要求 AI 每完成一个 Task 必须执行 Git 提交。
2. Context Refresh: 在开启每个新提案前，强制 AI 重新阅读 project.md。
3. Auto Archive: 完成后自动归档已执行的提案。

第五步：归档与清理 —— 保持上下文纯度

执行 openspec archive [proposal-name] --yes 是流程的终点。

• 物理清理：归档会将文件移出 changes/ 目录。
• 防止干扰：这能防止 AI 在处理下一个任务时被旧的、已实现的逻辑文档干扰，确保 AI 的“注意力”始终集中在当前任务。

结语：慢即是快

OpenSpec 将开发者从“码农”提升为“架构师”。通过前期的文档约束和全自动化的原子提交，得到的不仅是代码，而是一个逻辑严密、可追溯、高质量的项目仓库。