AI 编程的"甜蜜陷阱"

你是否遇到过这些问题?

❌

需求理解偏差

你说"添加用户登录",AI 给你加了邮箱、手机号、第三方登录...但你只想要手机号登录

🔄

反复修改代码

改个小功能,AI 把整个文件都重写了,引入新的 bug,越改越乱

💬

需求丢失

几轮对话后,AI 完全忘了你最初想要什么,代码越写越偏离目标

📝

缺乏文档

几周后回看代码:"这段代码为什么这么写?当时为什么做这个决策?"

🎲

不可预测性

同样的需求,每次 AI 生成的代码都不一样,质量参差不齐

🤝

团队协作困难

团队成员使用不同 AI 工具,代码风格和实现方式完全不统一

OpenSpec 的解决方案

规范驱动开发:先说清楚要做什么,再开始写代码

🎯

需求明确化

AI 会主动询问关键细节,避免猜测。例如:"时长范围是多少?UI 放在哪里?如何影响统计?"

📋

规范先行

生成完整提案文档(为什么做、做什么、怎么做),人工审查批准后再实现

✅

精确实现

AI 严格按照批准的规范写代码,逐项完成任务清单,标记完成进度

📁

完整追溯

每个功能都有提案、设计决策、任务清单、规范文档,形成完整的历史记录

🔧

工具无关

支持 Claude Code、Cursor、GitHub Copilot 等 10+ 主流 AI 工具,团队协作无障碍

⚡

轻量高效

无需 API 密钥,一条命令初始化,立即使用。前期多花 5 分钟,节省几小时返工时间

OpenSpec 适合什么场景?

✅

最适合:现有项目迭代(1→n)

在已有代码基础上添加新功能、优化现有模块、跨文件修改。OpenSpec 的双文件夹架构(specs/ + changes/)专为此设计

✅

最适合:需要高质量代码

生产环境项目、团队协作项目、长期维护项目。规范驱动确保代码质量和一致性

✅

最适合:使用 AI 编码助手

如果你已经在用 Claude Code、Cursor 等工具,OpenSpec 会让效率翻倍,让 AI 更可控

❌

不适合:快速原型验证

如果只是想快速试试一个想法,直接让 AI 写可能更快。OpenSpec 的流程会增加前期时间

❌

不适合:一次性脚本

几十行的小工具脚本,不需要 OpenSpec 的完整流程,直接写更高效

❌

不适合:需求极度不明确

如果连大概想要什么都不知道,OpenSpec 帮不了你。它的价值在于把想法变成清晰规范

工作流程

四步完成从提案到实现的完整开发周期

OpenSpec 工作流程 
┌────────────────────┐
│ 1. 起草变更提案    │  分享你的意图给 AI
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ 2. 审查与对齐      │  编辑规范和任务
│    (反馈循环)      │◀──── 迭代优化 ──────┐
└────────┬───────────┘                      │
         │ 批准的计划                        │
         ▼                                  │
┌────────────────────┐                      │
│ 3. 实现任务        │  AI 编写代码 ────────┘
└────────┬───────────┘
         │ 发布变更
         ▼
┌────────────────────┐
│ 4. 归档并更新规范  │  合并到源规范
└────────────────────┘

支持的 AI 工具

原生支持主流 AI 编码助手的斜杠命令

Claude Code
/openspec:proposal
Cursor
/openspec-proposal
GitHub Copilot
/openspec-proposal
Windsurf
/openspec-proposal
Codex
/openspec-proposal
Amazon Q
@openspec-proposal

快速开始

两步完成安装和初始化

步骤 1: 全局安装 CLI 
# 使用 npm 安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version
步骤 2: 在项目中初始化 
# 进入项目目录
cd my-project

# 运行初始化
openspec init

# 查看活跃的变更
openspec list

使用示例

完整的开发周期演示

创建变更提案 
You: 创建一个 OpenSpec 变更提案,添加用户配置文件搜索过滤器
     (快捷方式: /openspec:proposal 添加配置文件搜索过滤器)

AI:  我将为配置文件过滤器创建 OpenSpec 变更提案
     *生成 openspec/changes/add-profile-filters/
      包含 proposal.md, tasks.md, 规范增量*
验证和审查 
# 确认变更文件夹已创建
openspec list

# 验证规范格式
openspec validate add-profile-filters

# 查看提案、任务和规范增量
openspec show add-profile-filters
实现变更 
You: 规范看起来不错,让我们实现这个变更
     (快捷方式: /openspec:apply add-profile-filters)

AI:  我将处理 add-profile-filters 变更中的任务
     *实现 openspec/changes/add-profile-filters/tasks.md 中的任务*
     *标记任务完成: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
归档完成的变更 
You: 请归档这个变更
     (快捷方式: /openspec:archive add-profile-filters)

AI:  我将归档 add-profile-filters 变更
     *运行: openspec archive add-profile-filters --yes*
     ✓ 变更已成功归档。规范已更新。准备好下一个功能!

命令参考

OpenSpec CLI 常用命令

CLI 命令 
openspec list                      # 查看活跃的变更文件夹
openspec view                      # 交互式仪表板查看规范和变更
openspec show <change>             # 显示变更详情(提案、任务、规范更新)
openspec validate <change>         # 检查规范格式和结构
openspec archive <change> [--yes] # 将完成的变更移至归档(--yes 非交互)

核心特性

📋

规范增量格式

使用 ADDED/MODIFIED/REMOVED 标记清晰展示规范变更,像代码补丁一样管理需求

🏗️

Brownfield 优先

不仅适用于新项目(0→1),更擅长修改现有功能(1→n),特别是跨多个规范的更新

📦

变更文件夹

每个功能的所有相关内容(提案、任务、规范)都在一个文件夹中,便于追踪和管理

🔍

可审计性

所有变更都有明确的提案和任务记录,归档后保留完整的历史追溯

🤝

团队协作

不同团队成员可以使用不同的 AI 工具,共享相同的规范和工作流程

🎨

灵活扩展

支持 AGENTS.md 约定,兼容更多 AI 工具,如 Amp、Jules、Gemini CLI 等

OpenSpec vs 其他方案

选择最适合你的开发方式

OpenSpec vs 直接让 AI 写代码 
【传统方式】
你: 给我加个自定义时长功能
AI: 好的 (开始写代码)
你: 等等,我想要滑块和快捷按钮
AI: 好的 (改代码)
你: 还要显示番茄钟个数
AI: 好的 (再改代码)
结果: 反复修改,代码混乱,没有文档

【OpenSpec 方式】
你: /openspec:proposal 自定义时长
AI: 请先回答 5 个问题...
你: (回答详细需求)
AI: 生成完整提案
你: 审查通过
AI: 开始实现 (一次到位)
结果: 需求明确,实现精确,文档完整

vs. SpecKit

SpecKit: 更适合从零到一的新项目,简单的规范结构

OpenSpec: 专为 1→n 设计,双文件夹架构(specs/ + changes/),显式变更追踪,跨规范更新更容易

vs. Kiro (亚马逊)

Kiro: 更新分散在多个规范文件夹,功能追踪困难

OpenSpec: 将功能的所有变更集中在一个文件夹,便于追踪相关规范、任务和设计决策

vs. 传统需求文档

传统文档(Word/Confluence): 文档和代码分离,容易过时,难以和 AI 集成

OpenSpec: 文档和代码同步,自动更新,AI 原生支持,规范即文档

核心差异总结 
┌─────────────┬──────────────┬──────────────┬──────────────┐
│   方案      │  适用场景    │   优势       │   劣势       │
├─────────────┼──────────────┼──────────────┼──────────────┤
│ OpenSpec    │ 1→n 迭代     │ 变更追踪强   │ 前期稍慢     │
│             │ 现有项目     │ 文档完整     │              │
├─────────────┼──────────────┼──────────────┼──────────────┤
│ SpecKit     │ 0→1 新项目   │ 简单易用     │ 迭代支持弱   │
│             │ 快速启动     │ 上手快       │              │
├─────────────┼──────────────┼──────────────┼──────────────┤
│ 直接 AI     │ 原型验证     │ 最快         │ 不可预测     │
│             │ 小脚本       │ 零配置       │ 无文档       │
├─────────────┼──────────────┼──────────────┼──────────────┤
│ 传统文档    │ 大型企业     │ 流程规范     │ 与 AI 脱节   │
│             │ 合规要求     │ 审批完善     │ 更新困难     │
└─────────────┴──────────────┴──────────────┴──────────────┘

使用建议与最佳实践

让 OpenSpec 发挥最大价值的 5 个技巧

🎯

1. 第一个提案从小功能开始

不要一上来就用 OpenSpec 做大重构。先从一个小功能入手(添加字段、修改 UI 组件、优化算法),熟悉完整流程后再处理复杂需求

❓

2. 认真对待 AI 的澄清问题

当 AI 问你问题时,不要敷衍回答。这些问题往往直指需求的核心模糊点。花 5 分钟认真回答,能节省几小时的返工时间

🔄

3. 提案阶段多迭代

不要急着批准提案去写代码。仔细审查:需求是否完整?技术方案是否合理?有没有遗漏的边界情况?提案阶段改起来很容易,代码写了再改就麻烦了

✅

4. 测试后再归档

归档意味着"这个变更完成了"。在归档前:手动测试核心流程、确保没有明显 bug、验证规范都已实现。保持变更的原子性会让历史记录更清晰

📚

5. 规范文档是活的

OpenSpec 生成的规范不是一次性的。每次添加功能,规范都会更新。几个月后,你会拥有一份完整、准确、与代码同步的项目文档

🎓

额外提示:填充项目信息

初始化后,让 AI 帮你填写 openspec/project.md,描述项目背景、技术栈、代码规范。这让 AI 充分理解你的项目,生成更准确的提案

真实案例:iOS 番茄专注 App

从固定 25 分钟到自定义时长的完整实战

背景:现有项目需要新功能 
项目: ForestFocus (iOS 番茄专注计时器)
现状: 固定 25 分钟专注时长
需求: 添加自定义时长功能 (15/25/45/60/90 分钟)
挑战: 涉及数据模型、UI、统计、树木生长算法等多个模块
Step 1: AI 主动澄清需求 
命令: /openspec:proposal 自定义专注时长

AI 询问的 5 个关键问题:
1. 时长范围是多少?(最小/最大/步长)
2. UI 设计放在哪里?(设置页面 vs 主界面)
3. 如何计算番茄钟个数?(45 分钟算几个番茄钟?)
4. 旧数据如何处理?(向后兼容策略)
5. 树木生长如何计算?(不同时长下的 5 个阶段)

开发者回答:
- 支持 1-180 分钟,快捷按钮 15/25/45/60/90
- 主界面点击时长显示,弹出底部弹窗
- 显示实际时长 + 番茄钟等效(公式: ceil(duration/25))
- 旧数据默认 25 分钟
- 树木阶段按比例: stageDuration = totalDuration / 5
Step 2: AI 生成完整提案 
生成的文件:
📄 proposal.md - 为什么做、做什么、影响哪些模块
📄 design.md - 技术决策(为什么用 UserDefaults 而不是 SwiftData)
📄 tasks.md - 44 个具体任务,分成 9 个阶段,包含 8 个测试任务
📁 specs/ - 4 个能力的规范增量
   ├── timer-session (计时会话)
   ├── tree-visualization (树木可视化)
   ├── statistics-tracking (统计追踪)
   └── data-persistence (数据持久化)
Step 3: 实现与测试 
命令: /openspec:apply add-custom-focus-duration

AI 按照任务清单逐项实现:
✅ Phase 1: 数据模型更新 (FocusSession.swift)
✅ Phase 2: 时长持久化 (DurationPreference.swift)
✅ Phase 3: 计时服务增强 (TimerService.swift)
✅ Phase 4: 时长选择器 UI (DurationPickerView.swift)
✅ Phase 5: 界面集成 (TimerView.swift)
✅ Phase 6: 统计显示 (StatsView.swift)

发现 Bug: 设置 1 分钟后找不到修改入口
修复: 增强 UI 可见性(32pt 粗体 + 绿色边框 + 提示文字)

测试通过: 所有时长正常工作,树木生长正确,统计准确
Step 4: 归档与文档更新 
命令: openspec archive add-custom-focus-duration --yes

归档结果:
✓ 变更移至 openspec/changes/archive/2025-10-17-add-custom-focus-duration/
✓ 规范增量合并到 4 个 spec.md 文件
✓ 新增 8 个需求,20 个场景
✓ 所有验证通过

最终成果:
- 6 个新文件创建
- 8 个现有文件更新
- 43/53 任务完成(核心功能 100%)
- 完整的文档和历史记录
⏱️

时间对比

传统方式: 2-3 小时(反复沟通 + 多次修改)
OpenSpec: 1 小时(5 分钟澄清 + 50 分钟实现 + 5 分钟归档)

📊

质量对比

传统方式: 需求遗漏、代码混乱、无文档
OpenSpec: 需求完整、代码规范、文档同步

🎯

核心价值

前期多花 5 分钟澄清需求,节省几小时返工时间。几周后回看代码,所有决策都有据可查

社区与支持

💬

Discord 社区

加入 OpenSpec Discord 获取帮助和提问,与其他开发者交流使用经验

🐙

GitHub 仓库

在 GitHub 上查看源码、提交问题、参与贡献,遵循 Conventional Commits 规范

📢

关注更新

在 X (Twitter) 上关注 @0xTab 获取最新更新和功能发布信息