许振楠~TERRY.XU你有没有遇到过这样的场景给 AI 写了一段很长的 prompt结果生成的代码和想象中差了十万八千里或者每次开新会话都要重新跟 AI 解释一遍项目背景和约定OpenSpec 就是为解决这个问题而生的。什么是 OpenSpecOpenSpec是一个规范驱动开发工具让你和 AI 编程助手在动手写代码之前先把需求说清楚。听起来像是先写文档的老套路不是的。OpenSpec 的核心理念是迭代式而非瀑布式生成的文档不是一次性定稿可以随时修改需求变化时用增量规范Delta Specs记录变更而不是重写整套文档每次变更归档后AI 下次会话直接读取不用再重复交代背景用一句话概括OpenSpec 把你脑子里的需求变成 AI 能理解和执行的结构化文档。三步跑通核心工作流Step 0安装npminstall-gfission-ai/openspeclatest# 验证安装openspec--version# 输出类似 1.3.1也支持 pnpm、yarn、bun 安装选你顺手的就行。Step 1初始化项目mkdirmy-projectcdmy-project# 指定 AI 工具非交互式初始化openspec init--toolsclaude# 或者支持所有工具openspec init--toolsall初始化完成后项目里会生成两个关键目录openspec/ ├── specs/ # 主规范库项目的行为事实来源 └── changes/ # 变更管理目录 └── archive/如果你用的是 Claude Code还会生成.claude/commands/opsx/下的四个斜杠命令文件。Step 2创建变更提案打开 AI 编程助手输入/opsx:propose 给 Todo API 添加完整的 CRUD 接口 - GET /todos - POST /todos - PUT /todos/:id - DELETE /todos/:idAI 会生成4 个制品制品内容proposal.md变更的背景和范围Why Whatdesign.md技术方案和架构决策specs/Delta Specs用 ADDED/MODIFIED/REMOVED 描述需求变化tasks.md具体的实现任务清单这 4 个文件都可以手动编辑。觉得 AI 写的方案有问题直接改design.md。需求描述不够精确改specs/下的文件。改完再 apply不用重新 propose。Step 3执行实现/opsx:applyAI 会按照tasks.md的顺序逐条执行完成后输出汇总报告。Step 4归档变更/opsx:archive归档做两件事把变更目录移到openspec/changes/archive/YYYY-MM-DD-change-name/把 Delta Specs 合并回openspec/specs/主规范库为什么归档很重要随着项目迭代openspec/specs/会越来越完整。AI 下次读到这份规范就知道项目现在有哪些 API、用的什么架构、遵循什么约定——不需要你重复交代。核心工作流总结openspec init │ ▼ /opsx:explore ← 可选先理清思路纯思考不写代码 │ ▼ /opsx:propose ← 生成 4 个制品可编辑 │ ▼ /opsx:apply ← 按 tasks.md 逐条实现 │ ▼ /opsx:archive ← 归档Delta Specs 合并回主规范三条核心命令propose → apply → archive。实战案例Expedia Detail Handler 性能优化以下是一个真实项目中使用 OpenSpec 完成性能优化重构的完整案例展示 4 个制品在实际工程中的样子。背景ExpediaDetailHandler处理 Expedia 酒店详情数据时极慢50 个并发 Task每个 Task 内部串行处理 500 家酒店每家酒店 10-15 次独立 DB 查询。proposal.md — 说清楚 Why What## 根因分析 - P0Task 内串行处理500 家 × 40ms 20s/task - P0每家酒店 10-15 次独立 DB 往返 - P1Mapping 查询无缓存每家各打一次 DB - P1dbDetail 重复查询同一对象查 5-6 次 ## 做什么 1. 批量预取 MappingN 次 → 1 次批查询 2. Task 内部改用虚拟线程并发 3. 消除 dbDetail 重复查询 4. 修正 readHotelFile 误导性注释 ## 不做什么 不改事务边界、不引入批量 DB update、不加 Redis 缓存、不引入 Disruptor关键点proposal 里明确写不做什么防止 AI 过度实现。这是 OpenSpec 最容易被忽视的一栏。design.md — 记录技术决策和理由## 决策 1批量预取 Mapping 在 for 循环前调用 batchSelectMapping() 一次性获取所有 mapping 存入 HashMap。 不用 Redisper-batch 生命周期 HashMap 足够。 ## 决策 2虚拟线程并发 for 循环改为 Executors.newVirtualThreadPerTaskExecutor()try-with-resources。 不用 epsDetailExecutor该线程池已被 50 个 Task 占满内部再提交会死锁。 ## 决策 3消除 dbDetail 重复查询 saveOrUpdateCombine() L265 已查一次 dbDetail各子方法不应再各自 findByHotelId()。关键点design.md 不只写做什么更要写为什么不用另一种方案。这里记录了不用 epsDetailExecutor 是因为会死锁——这种隐性约束如果不写下来下次 AI 很可能重蹈覆辙。specs/ — 用 GIVEN/WHEN/THEN 描述行为## Spec 1批量预取 Mapping GIVEN 一个包含 N 家酒店的 batch WHEN 进入 for 循环前 THEN 调用 batchSelectMapping() 一次性批查异常时降级为空 map 兜底单条查询 ## Spec 2虚拟线程并发 GIVEN Task 内部处理 500 家酒店 WHEN 使用 newVirtualThreadPerTaskExecutor() THEN 每家酒店独立 Callable异常单独捕获不影响其他completedIds 用线程安全集合 ## 非功能性规格 - 500 家酒店 batch 内 detail_mapping 查询从 ≥500 次降到 1 次 - 不产生新 DB 死锁 - completedIds 使用线程安全结构关键点specs 里的非功能性规格查询次数、线程安全是验收标准apply 完成后可以用/opsx:verify逐条核对。tasks.md — 可执行的任务清单- [x] 1. 新增批量 Mapping 查询接口batchSelectMapping复用已有 findByPlatformAndHotelPltIds - [x] 2. 重构 ExpediaReadTask虚拟线程 mappingCache processSingleHotel 私有方法 - [x] 3. 消除 dbDetail 重复查询审查结论无重复无需修改 - [x] 4. 注释修正 - [ ] 5. 单元测试batchSelectMapping 测试 ExpediaDetailHandlerTest - [ ] 6. 集成验证本地触发 handler确认批查次数为 1全量编译通过关键点tasks.md 是进度看板也是 AI 的执行脚本。任务 3 的审查结论直接写在 checkbox 里——“无重复无需修改”——这样下次会话 AI 不会重复做这个检查。实战收益优化项优化前优化后Mapping 查询次数/batch500 次1 次batch 内并发度1串行~500虚拟线程dbDetail 查询次数/酒店5-6 次1 次整体吞吐估算1×3-5×从这个案例学到什么proposal 的不做什么和根因分析同等重要明确边界防止 AI 过度实现design 要记录为什么不用另一种方案隐性约束如死锁风险不写下来就会丢失tasks 的审查结论要写进 checkbox避免下次会话重复调查specs 的非功能性规格是验收标准查询次数、线程安全这类约束要量化⚡ 重点用openspec config profile解锁更多命令默认安装后你只有 4 个斜杠命令/opsx:explore /opsx:propose /opsx:apply /opsx:archive对于入门使用已经够了。但如果你想要更精细的控制需要主动切换到扩展模式openspec config profile# 在交互式菜单中选择 expandedopenspec update# 更新斜杠命令文件这一步不能少切换后你将获得额外的 6 个命令命令用途/opsx:new创建变更脚手架不自动生成文档适合手动精调/opsx:continue继续未完成的变更根据依赖关系创建下一个制品/opsx:ffFast-forward一键生成所有规划文档/opsx:verify验证实现是否符合 specs 中的规范/opsx:bulk-archive批量归档多个变更/opsx:onboard引导式教程带你走完整个工作流什么时候需要扩展模式Core 模式适合个人项目、小团队快速迭代单次功能开发需求相对清晰刚开始用 OpenSpec先跑通核心流程Expanded 模式适合复杂功能需要分阶段细控用/opsx:new/opsx:continue想验证 AI 实现是否真的符合规范用/opsx:verify多个并行变更需要批量处理用/opsx:bulk-archive希望有人带着走一遍彻底搞懂流程用/opsx:onboard一句话Core 模式是默认档Expanded 模式是进阶档。openspec config profile是解锁进阶档的开关不运行这条命令这些命令根本不会出现在你的 AI 工具里。进阶技巧用config.yaml固化项目约定交互式初始化会自动生成openspec/config.yaml。如果你用的是--tools参数非交互式初始化可以手动创建# openspec/config.yamlschema:spec-drivencontext:|Tech stack: TypeScript, Express, PostgreSQL API conventions: RESTful, JSON responses Error format: { code, message, details }rules:proposal:-Include rollback plan for database changesspecs:-Use Given/When/Then format for scenarios配置之后每次 propose 时 AI 会自动遵循这些约定——不用在 prompt 里重复声明技术栈和规范。完整 CLI 命令速查openspec init# 初始化项目openspec init--toolsclaude# 非交互式指定工具openspec config profile# 切换工作流模式core / expandedopenspec update# 更新斜杠命令文件openspec list# 列出活跃变更openspec list--specs# 列出所有规范openspec showname# 查看变更详情openspec status--changename# 查看制品完成进度openspec validate# 验证格式openspec view# 交互式仪表盘常见问题Q每次 propose 生成的文档不满意能改吗可以直接编辑文件。OpenSpec 的核心理念是iterative not waterfall生成的文档是活文档随时可改改完再 apply。Q归档后发现需求写错了能撤销吗不需要撤销。重新/opsx:propose一个新变更就行Delta Specs 天然支持增量修改——新变更里用 MODIFIED 描述对旧需求的调整。Q支持哪些 AI 工具Claude Code、Cursor、Windsurf、GitHub Copilot、Cline、RooCode、Amazon Q 等 20 工具openspec init --tools all可以一次配置全部。Qtasks.md 里的审查结论要怎么记录直接写在 checkbox 后面。比如审查结论无重复无需修改——这样下次会话 AI 不会重复做同样的调查也不会误以为这个任务被跳过了。总结OpenSpec 解决的核心问题是让 AI 编程从「模糊 prompt → 不确定输出」变成「明确规范 → 可预期实现」。上手路径很简单npm install -g fission-ai/openspeclatestopenspec init --tools claude/opsx:propose→/opsx:apply→/opsx:archive如果 Core 模式的 4 个命令不够用记住这一条openspec config profile# 解锁扩展模式的 6 个额外命令openspec update# 刷新命令文件这是很多人初次使用 OpenSpec 时容易忽略的一步但它决定了你能用到多少工具。*官方文档https://openspec.pro **GitHubFission-AI/OpenSpec *