在传统的代码狂写模式里需求往往漂浮在聊天记录、Jira 条目甚至脑袋里。等到真正落地时常常出现「我以为是这样实现的」与「实际需求不符」的尴尬。OpenSpec 把这场混乱装进一套文件体系，让 AI Neng在明确的 规格 与 任务清单 中精准作业，从根本上降低幻觉、提升可追溯性。

核心理念：先写 proposal.md → 再生成增量 specs/ → 用 design.md 描绘技术方案 → Zui后拆成原子化的 tasks.md。每一步dou有人审查，每一步dou被文件永久保存。

proposal.md回答「我们为什么要改」；背景、目标、范围，一句话概括。

specs/列出“系统现在应该怎么表现”，也叫 Source of Truth。

design.md把抽象的行为翻译成架构图、技术选型、数据迁移方案。

tasks.md把设计拆成若干可独立完成的工作项，AI 按顺序执行。

/opsx:explore → /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive

下面我们用一个实际功Neng——列表查询支持多条件筛选——来把这些命令串联起来让你直观感受每一步的价值。

你: /opsx:explore
列表查询需要支持用户自定义过滤条件，包括日期区间、状态枚举以及关键字模糊搜索。
请帮我梳理涉及的后端接口、数据库字段以及可Neng的性Neng瓶颈。

A.I. 会返回一份结构化报告：

接口层：/api/v1/items/search?...

DB 表：items

潜在瓶颈：

全表扫描导致响应时间> 2 秒；建议使用复合索引。

Date 范围查询若不加索引会导致大量回表。

此时没有任何文件被创建，只是一次“思考”过程，却Yi经把后面的工作量大幅压缩。

你: /opsx:propose add-multi-filter
# 背景
用户希望在后台管理页面对商品列表进行灵活筛选，以提升运营效率。
# 目标
1) 支持任意组合的过滤条件；
2) 返回分页结果，默认每页 20 条；
3) 性Neng不低于 200 TPS。
# 范围
- 新增搜索 API；
- 在 DAO 层加入动态查询构造器；
- 单元测试覆盖所有组合情况。

A.I. 随即生成四个工件：

/openspec/changes/add-multi-filter/proposal.md

/openspec/changes/add-multi-filter/specs/search-filter.md

/openspec/changes/add-multi-filter/design.md

/openspec/changes/add-multi-filter/tasks.md

你: /opsx:apply add-multi-filter
正在读取 tasks.md...
✓ Yi创建 SearchController 接口
✓ Yi实现 FilterBuilder 动态拼装 SQL
✓ Yi编写 PaginationHelper
✓ 完成单元测试
全部任务Yi完成！ 🎉

Ru果你在途中手动改了几行代码，AI 会自动检测差异，只跑未完成的任务，省去重复劳动。

你: /opsx:verify add-multi-filter
✅ 完整性：所有 tasks Yi标记完成  
✅ 正确性：实际返回字段与 specs 定义一致  
✅ 一致性：分页逻辑统一使用 PaginationHelper  
⚠️ 警告：状态枚举缺少 “ARCHIVED” 分支，请补充对应代码。
A.I. 把缺口列出来你只需在对应文件中补上实现，然后再跑一次 `apply` 即可。
5️⃣ 归档阶段：让历史成为活文档 
你: /opsx:archive add-multi-filter
✓ Delta Specs 合并至 openspec/specs/search-filter.md  
✓ 变geng目录移动至 openspec/archive/2026-04-add-multi-filter/  
归档成功！项目现在拥有一份完整、可追溯的搜索功Neng规格。
以后任何人打开 `openspec/specs` douNeng直接kan到「搜索」到底是怎么运作的——不需要翻旧 PR，也不必猜测业务意图。
三、团队协作模式实战 
# 模式一：同一变geng多人分工 

A 同学负责前端：`/opsx:apply add-multi-filter --scope frontend`，生成 UI 表单与调用代码。
B 同学负责后端：`/opsx:apply add-multi-filter --scope backend`，专注业务逻辑实现。
两人分别执行 `/opsx:verify …​` 检查各自模块是否满足 specs；出现冲突时用 `/opsx:sync …​` 同步增量规格。

`/opsx:archive` 将整个变geng闭环，形成统一版本历史。

# 模式二：并行多个变geng后批量合并 
→ /opsx:new export-csv 
→ /opsx:new audit-log 
→ ... 
→ /opsx:bulk-archive   # 自动检测冲突并提示手动合并
这种方式特别适合微服务团队，同步推进多个独立功Neng，而不会相互踩踏。
四、落地建议 & 常见坑点 

# 前期沟通不可省：花半小时把 proposal 写清楚，比后期调试省掉数十小时。利用 `/opsx:explore` Zuo需求预研，让所有参与者站在同一张地图上。

# 配置上下文极其重要：`openspec/config.yaml` 中填入技术栈、代码风格、CI 要求等信息。这样每次生成 `tasks.md` 时 AI douNeng自动遵循约定，无需反复交代背景。
# 每个 Change 必须单一职责：`add-rate-limiter` 专注限流；若要再加熔断器，请另建 `add-circuit-breaker`。职责混杂会导致 specs 冲突和回滚困难。
# Verify 不容跳过：`verify` 是防止 “实现偏离规格” 的Zui后防线。即使kan起来hen小的问题，比如缺少异常日志，也会在归档前被捕获并修正。
# 人机协同而非机器替代：A.I. Neng快速生成稿子，但它不会主动问「边界条件该怎么处理」。因此 proposal 与 design 必须经过人工审阅，才Neng真正发挥 OpenSpec 的价值。
# 小技巧：每天结束前跑一次 `openspec list`，快速扫视当前活跃变geng，有助于保持全局视野，不至于因为切换太快而忘记正在Zuo什么。

五、如何把 OpenSpec 融入现有工具链 
下面是一段常见的初始化脚本，仅供参考：
# 安装 CLI
npm i -g @fission-ai/openspec@latest
# 项目根目录执行 init，会询问使用哪款 AI 助手
# 初始化后会自动生成 .open-spec.yaml 与 slash‑command 文件
# 别忘了重启 IDE，使插件生效！
cd your-project && openspec init
# 推荐立即编辑 config.yaml 填入 context 信息
vim openspec/config.yaml
# 完成后即可开始第一轮探索或直接提案
Ru果项目Yi经有大量遗留代码，只需在根目录运行 `openspec init --import-existing`，系统会尝试逆向抽取现有 API 行为生成初始 specs，为后续增量迭代奠定基础。
六、 —— 从“随心所欲”到“规章严明” 
OpenSpec 并不是要把人逼得死板，它想Zuo的是提供一个安全阀门和记事本结合体”。当需求还停留在脑子里时你Ke以随意敲几句聊天；当准备落地时就让 OpenSpec 把思路固化为文件，让 AI 在明确边界内奔跑。这样既保留了创意自由，又避免了因信息缺失产生的幻觉风险，geng重要的是——整个团队dou有了一本实时geng新且可信赖的技术文档。🚀 


    本文作者：秋筠
    如有疑问或想一起实践 OpenSpec，可关注