AI写代码总跑偏？OpenSpec让需求先"签合同"

AI写代码总跑偏？OpenSpec让需求先"签合同"

跟AI助手聊了半小时，生成了一堆代码，跑起来发现完全不是想要的——这个场景我太熟了。需求只存在于聊天记录里，没有结构化沉淀，AI理解偏差越滚越大，最后只能推倒重来。

OpenSpec的出现像是给AI编程加了个"前置校验层"。它在写代码之前强制你先写一份轻量级的"技术合同"，包含proposal.md、specs/、design.md、tasks.md四个核心文档。这就像盖房子前得有图纸，不能让施工队"看着办"。

核心架构：适配器模式打通20+AI工具

OpenSpec本身是个TypeScript开发的CLI工具，架构设计有个聪明之处——采用适配器模式做工具无关性集成：

┌─────────────────┐
│   OpenSpec CLI  │
└────────┬────────┘
         │
         ├─→ Claude Code
         ├─→ Cursor
         ├─→ GitHub Copilot
         └─→ (20+ 其他工具)

这意味着你不需要切换到特定IDE，在习惯的工具里用slash commands（如/opsx:propose）就能触发工作流。对比AWS的Kiro把你锁定在他们的环境和Claude模型里，OpenSpec的扩展性明显更友好。新工具接入只需要实现对应的适配器，这比重新造轮子务实得多。

目录结构设计也值得说道。每个变更都有独立文件夹，放在openspec/changes/目录下：

openspec/
├── changes/
│   ├── add-dark-mode/
│   │   ├── proposal.md
│   │   ├── specs/
│   │   ├── design.md
│   │   └── tasks.md
│   └── archive/
│       └── 2025-01-23-add-dark-mode/

变更可追溯、便于归档、支持多项目协作，这三个好处直接命中团队协作的痛点。完成的功能一键归档到openspec/changes/archive/，团队成员能清楚看到每个变更的状态，比在Slack里翻聊天记录高效太多了。

Workflow设计哲学：fluid not rigid

OpenSpec和GitHub Spec Kit最大的区别在于工作流的柔性。Spec Kit有刚性的阶段门（phase gates），必须按顺序完成每个阶段才能进入下一个。但OpenSpec允许你在任何时候更新任何artifact。

实际开发场景里，你在实现过程中发现某个需求不合理，可以回头修改specs/文件然后继续开发。而在Spec Kit里，可能需要重新走一遍评审流程——这在敏捷开发里是不现实的。"fluid not rigid"这个设计原则体现了对真实开发节奏的理解。

上手代码示例

安装与初始化

## 全局安装（要求Node.js 20.19.0或更高版本）
npm install -g @fission-ai/openspec@latest

## 进入项目目录初始化
cd your-project
openspec init

Node版本要求比较高，但理解这个必要性——高版本Node提供了更好的TypeScript支持和ES模块系统。老旧的CI/CD流水线可能需要升级，这是投入成本之一。

核心Workflow演示

## 提出需求
You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

## 开始实现
You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

## 归档完成的功能
You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

这个workflow设计直观，有点像Git的流程：propose（相当于commit）→apply（相当于push）→archive（相当于tag）。AI逐步执行任务清单，每完成一项打勾确认，这种可视化反馈让人心里有底。

高级配置与隐私控制

## 启用高级workflow（支持更多命令）
openspec config profile
openspec update

## 关闭遥测（企业用户可能关心这个）
export OPENSPEC_TELEMETRY=0
## 或者使用标准的Do Not Track
export DO_NOT_TRACK=1

OpenSpec默认收集匿名使用数据（仅命令名和版本号），这对企业用户可能是敏感点。好在提供了完整的关闭选项，比某些偷偷摸摸收集数据的工具体面多了。

性能与模型要求

官方推荐使用Opus 4.5和GPT 5.2这类高推理能力模型。这说明OpenSpec的核心逻辑对模型推理能力要求较高——它要让AI理解需求、生成规范、分解任务，这些都比单纯写代码更复杂。

README提到OpenSpec受益于"干净的上下文窗口"，这是实用的建议：

• 在开始实现前清除上下文
• 在会话过程中保持良好的上下文卫生

这实际上在解决AI助手的常见问题：上下文污染导致输出质量下降。每次会话前清空无关信息，让AI聚焦当前任务，输出质量会稳定很多。

适合什么场景？

强烈推荐的场景：

1. 团队协作项目——需求对齐和变更追踪是刚需
2. 复杂功能开发——需要明确需求和设计的大型功能
3. 棕地项目维护——历史项目的需求文档缺失，可以用OpenSpec逐步重建
4. 远程协作——异步沟通需要更明确的需求文档

可能不适合的场景：

1. 快速原型验证——只是验证一个想法，spec层可能增加额外开销
2. 单文件脚本——简单的自动化脚本没必要搞这么复杂
3. 纯探索性开发——需求完全不明确时，可能更适合直接写代码探索

踩坑预警

1. 版本依赖：必须用Node 20.19+，老旧的CI/CD流水线可能需要升级
2. 模型成本：高推理模型通常更贵，频繁使用可能增加成本
3. 团队习惯：需要培养先写需求再写代码的习惯，初期可能觉得繁琐

个人看法

作为一个常年被"先上线再说"思维折磨的开发者，我对OpenSpec的出现是欢迎的。它把规范驱动开发（SDD）从"理论上的好实践"变成了"实际可用的工具"。

但有几点保留意见：

学习曲线方面，虽然号称轻量，但对习惯直接写代码的开发者来说，多一层spec意味着更多工作量。需要团队真正认同其价值才能坚持。

过度工程风险也存在。小项目用这个可能有点杀鸡用牛刀。想象一下为一个只有几个页面的landing page写proposal.md、specs、design.md、tasks.md——这画面太美。

依赖模型质量是关键。整个workflow的顺畅程度高度依赖背后的大模型。如果模型无法准确理解需求或生成合理的spec，整个流程就会卡住。

如果是我来用，我会这么搞：

• 在复杂功能开发时使用完整的workflow
• 简单功能直接用/opsx:propose生成基本框架，然后手动调整
• 结合团队的知识库，把归档的spec作为技术文档沉淀下来
• 对于维护项目，用OpenSpec逐步补齐缺失的需求文档

总结

OpenSpec不是银弹，但它代表了一个正确的方向：让规范成为开发者的助力，而不是负担。它的设计哲学（fluid not rigid, easy not complex）体现了对实际开发场景的深刻理解。

如果你正在用AI写代码但总觉得"对不齐"，或者团队因为需求不清晰反复返工，这个项目值得试试。不过建议先在一个小团队里试运行，确认workflow适合你们的节奏后再推广。

作为一个8年老兵，我见过太多"最佳实践"工具最后变成"最佳摆设"。希望OpenSpec能真正落地，而不是又一个GitHub Trending上的流星。