我用了一段时间 AI 编码助手后发现：AI写代码不在于工程多复杂、提示词写的多精妙，而在于规范。了解了规格驱动开发之后我觉得有必要记录一下我的心得。
另外，推荐一下我写的OpenSpec插件，方便直接使用OpenSpec，open-vsx.org/extension/r…
一个让我头疼的问题
你有没有遇到过这种情况：
让 AI 帮你写个功能，它理解偏了，给你写了一堆不需要的代码。或者代码风格完全不统一，每次都要手动调。再或者几个月后回来看项目，根本想不起来当时为什么这么设计。
我遇到过。而且不止一次。
后来我发现，这些问题的根源都一样：我和 AI 之间缺了一份明确的"规范"。不要觉得“代码就在那，AI会读取代码，根据代码修改......”。 记住你不是一个人在开发，一个团队想要有知识积累、能合作开发就必须要把需求、设计、实施这些步骤规范化。哪怕是独立开发者或者自己维护着一个项目，你依然需要项目有记忆，如果你不希望每次开发都要去梳理代码，那么就维护好这些信息，正所谓己不所欲，勿施于人。
OpenSpec 的规格文档、chang归档等设计能够协助你在项目中快速建立、维护自己的项目知识库（至于如何在公司级别维护多个项目的项目知识库，后续会为大家介绍）。
GitHub: github.com/Fission-AI/…
OpenSpec 是什么？
OpenSpec 是 Fission-AI 开源的一个框架，专门给 AI 编码助手用。它的核心思想很简单：在写代码之前，先把需求、设计、任务都写清楚，形成一份"规范"。AI 根据这份规范来写代码，就不会跑偏。
它的哲学挺有意思的：
- 灵活不僵化（fluid not rigid）
- 迭代不瀑布（iterative not waterfall）
- 简单不复杂（easy not complex）
- 适应老项目，不只是新项目（built for brownfield）
- 从个人到企业都能用（scalable）
这五个原则里，我觉得"适应老项目"这条最实用。大多数时候我们不是从零开始，而是在一堆老代码上改。OpenSpec 对这种场景支持得很好。
工作流：四个阶段
OpenSpec 把一次变更分成四个阶段：
Start a Change (/opsx:new)
→ Create Artifacts (/opsx:ff, /opsx:continue)
→ Implement Tasks (/opsx:apply)
→ Archive & Merge (/opsx:archive)
翻译成人话就是：
- 新建变更（说清楚要做什么）
- 生成工件（规划怎么做）
- 实施任务（动手写代码）
- 归档（记录存档）
这个流程看起来有点繁琐，但实际用起来还好。主要是因为大部分工作都是 AI 做的，你只需要 review。
项目结构
OpenSpec 要求你在项目里创建一个 openspec/ 目录，长这样：
openspec/
├── specs/ # 系统当前行为的描述
│ └── <domain>/
│ └── spec.md
├── changes/ # 正在进行的变更
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # Delta规范
└── config.yaml # 项目配置
specs/ 目录
这个目录存放系统的"当前真相"。比如认证模块的行为是什么样的，支付流程是怎么走的。用 Given-When-Then 的格式写：
# User Authentication Spec
## Requirements
### Requirement: Email Login
The system MUST allow users to login with email and password.
#### Scenario: Successful login
- GIVEN a registered user
- WHEN user submits valid credentials
- THEN user is authenticated and redirected to dashboard
changes/ 目录
每个功能、修复、重构都是一个独立的 change。每个 change 里有：
- proposal.md：为什么做这个？做什么？
- specs/：相对于当前规范的变更（Delta Specs）
- design.md：技术方案
- tasks.md：实施清单
Delta Specs：最有意思的设计
Delta Specs 是 OpenSpec 最好的设计之一。它不是重写整个规范，而是只写"变动的部分"：
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
## MODIFIED Requirements
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA)
归档的时候，OpenSpec 会自动把 ADDED 追加到主规范，MODIFIED 替换掉旧的，REMOVED 删掉。这样主规范始终保持最新，而且每个变更都有记录。
实战：添加暗黑模式
我用一个真实的例子演示一下。假设要给一个 React 项目加暗黑模式。
步骤 1：新建变更
You: /opsx:new add-dark-mode
AI: Created openspec/changes/add-dark-mode/
Ready to create: proposal
这一步只是创建了一个空的变更目录。
步骤 2：生成所有工件
You: /opsx:ff
AI: Creating artifacts for 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!
/opsx:ff 会一次性生成所有文件。看看生成的 proposal.md：
# Proposal: Add Dark Mode
## Why
Users have requested dark mode to reduce eye strain during night usage.
## What
Add theme switching capability with light/dark modes.
## Capabilities
- Theme toggle in settings
- localStorage persistence
- CSS custom properties for theming
## Impact
- No breaking changes
- New CSS variables need to be documented
design.md 会写技术方案：
# Design: Dark Mode Implementation
## Technical Approach
1. Use React Context for theme state
2. CSS custom properties for color values
3. localStorage for persistence
4. System preference detection (prefers-color-scheme)
## Architecture
- ThemeProvider component wraps app
- useTheme hook for components
- ThemeToggle component in header
tasks.md 会列出具体的任务：
# Tasks: Dark Mode
- [ ] 1. Create ThemeContext
- [ ] 1.1 Define theme types (light/dark)
- [ ] 1.2 Create ThemeProvider component
- [ ] 1.3 Add localStorage persistence
- [ ] 2. Add CSS Custom Properties
- [ ] 2.1 Define color variables
- [ ] 2.2 Add dark mode values
- [ ] 3. Create ThemeToggle Component
- [ ] 3.1 Design toggle UI
- [ ] 3.2 Add accessibility labels
步骤 3：实施
You: /opsx:apply
AI: Working through tasks...
✓ 1.1 Created ThemeContext with light/dark state
✓ 1.2 Added CSS custom properties to globals.css
✓ 1.3 Implemented localStorage persistence
...
All tasks complete!
AI 会按顺序完成任务，每完成一个打勾。
步骤 4：归档
You: /opsx:archive
AI: Archiving add-dark-mode...
✓ Merged specs into openspec/specs/ui/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
Done! Ready for the next feature.
归档会做两件事：把 Delta Specs 合并到主规范，把变更移到 archive/ 目录。
这里要注意的另一个问题是归档有的时候并不会帮你自动合并到主规范中，AI会跟你确认一下是否需要Sync:
Delta specs: 存在 2 个 delta spec，尚未同步到 main specs：
- xxxx：主仓库中尚无对应 openspec/specs/...../spec.md，同步会新增该文件并写入本次 ADDED 需求。
- zzzz：主仓库中尚无对应 openspec/specs/...../spec.md，同步会新增该文件并写入本次 ADDED 需求。
若要把本次变更固化到主 spec，可在归档后执行：
openspec sync-specs --change .....
（需在归档目录或通过 --change-dir openspec/changes/archive/2026-03-01-..... 指定该 change；具体以你本地 openspec 用法为准。）
总结： add-embedding-cache 已成功归档；可选任务未完成、delta 未同步到 main，可按需补做或执行 sync。
你可以简单的执行/opsx-sync ......即可。
为什么我觉得 OpenSpec 有用
先对齐，再编码
以前我跟 AI 的对话是这样的：
我：帮我加个暗黑模式
AI：好的（直接开始写代码）
结果写了一堆我不需要的功能。
用了 OpenSpec 之后：
我：/opsx:new add-dark-mode
AI：先生成 proposal 和 design
我：（review 之后）可以，实施吧
AI：按你的要求做
多了一步 review，但省了后面改来改去的时间。
变更历史可追溯
每个变更都有完整的记录：为什么做、做了什么、怎么做的、分几步实施的。
几个月后回来看，不用猜当时是怎么想的。
灵活，不僵化
你可以在任何阶段修改工件。proposal 写得不够详细？改。design 有问题？改。tasks 粒度太粗？细化。
没有那种"这个阶段必须做完才能进下一个"的门禁。
工具无关
OpenSpec 支持 20 多个 AI 助手，包括 Claude Code、GPT-5、Codex，还有一些本地模型。不绑定特定工具。
快速开始
安装
npm install -g @fission-ai/openspec@latest
初始化
cd your-project
openspec init
这会在你的项目里创建 openspec/ 目录结构。
基本用法
在 AI 助手里输入：
/opsx:new <feature-name>
/opsx:ff # 生成所有工件
/opsx:apply # 实施
/opsx:archive # 归档
CLI 命令
openspec list # 列出活跃变更
openspec show <name> # 查看变更详情
openspec validate <name> # 验证规范格式
openspec view # 交互式仪表板
什么时候用，什么时候不用
适合用的场景：
- 团队协作项目（specs 作为团队规范）
- 长期维护的系统（变更历史可追溯）
- 老项目改造（适应 brownfield）
- 需要切换模型（工具无关，规范持久化）
不太适合的场景：
- 快速原型（可能过于正式）
- 一次性脚本（文档成本比收益大）
- 简单 bug 修复（直接改更快）
跟其他方案比怎么样
跟"没有规范"比
没有规范的时候，你和 AI 之间的需求全靠聊天记录。聊着聊着就忘了最初想做什么。OpenSpec 把需求写成文档，随时可以查。
跟 Spec Kit 比
Spec Kit 更全面，但也更重。有僵化的阶段门禁，必须按顺序来。OpenSpec 更轻量，可以自由迭代。
跟 Kiro (AWS) 比
Kiro 功能强大，但锁在他们的 IDE 里。OpenSpec 用你现有的工具就行。
我踩过的坑
1. 不要一开始就全面铺开
我第一次用的时候，想给整个项目都加上 OpenSpec。结果搞了一周还没弄完。
后来改成先在一个模块试水，效果好很多。
2. 工件要简洁
proposal 写 1-2 段就够了，不要写成 RFC。design 写关键技术决策就行。tasks 要细，每个任务 2-5 分钟能完成。
太长的文档没人看，包括未来的自己。
3. 定期更新 specs/
specs/ 目录是项目的真相。如果不及时更新，就会和实际代码脱节。我一般每周花 15 分钟检查一次。
4. 用好 config.yaml
context: |
React + TypeScript 项目
遵循 Functional Programming
rules:
- "先写测试再写实现"
- "不用 any"
把项目特定的规范写进去，AI 生成的工件会更贴合你的项目。
常见问题
OpenSpec 会不会增加很多文档工作？
不会。工件是 AI 生成的，你只需要 review 和微调。相比于"写了代码发现理解错了"的返工，这点投入划算。
我用 Claude Code，怎么用 OpenSpec？
安装后直接用斜杠命令：/opsx:new、/opsx:ff、/opsx:apply、/opsx:archive。
Delta Specs 和主规范有什么区别？
主规范是系统的当前行为（truth），Delta Specs 是相对于主规范的变更（ADDED/MODIFIED/REMOVED）。归档时，Delta 会自动合并到主规范。
能在 CI/CD 里用吗？
可以。OpenSpec 有 CLI 命令，容易集成：
- name: Validate OpenSpec specs
run: openspec validate ${{ github.event.pull_request.title }}
下一篇我会用一个完整的项目案例，展示从需求到代码的全流程。包括怎么写 proposal、怎么拆 tasks、怎么处理意外情况。
如果你在用 AI 编码助手，或者团队在探索 AI 辅助开发，可以试试 OpenSpec。不一定适合所有场景，但值得一试。
