1. OpenSpec实战为什么我们需要规范驱动的开发在传统开发流程中最让人头疼的问题莫过于代码写完了但和需求文档对不上。我见过太多项目在交付时才发现开发人员理解的用户登录功能和产品经理描述的完全不是一回事。这种脱节往往导致返工、延期甚至引发团队矛盾。OpenSpec正是为了解决这个痛点而生。它不是一个简单的文档工具而是一套完整的**规范驱动开发Specification-Driven Development**工作流。核心思想很简单在写代码之前先明确规范Spec——这个规范不是Word文档里几段模糊的描述而是用结构化语言定义的系统行为。举个例子当我们开发用户登录功能时传统做法可能是产品经理写个需求文档开发人员看文档写代码测试人员按自己的理解测试而OpenSpec的做法是在specs/auth/spec.md中定义### Requirement: User Authentication The system SHALL validate user credentials during login. #### Scenario: Successful login - **WHEN** user provides valid username and password - **THEN** system returns JWT token - **THEN** token expires in 24 hoursAI助手根据这份规范生成初始代码任何变更都需要通过Change Proposal流程这种工作流特别适合与AI编码助手协作。当规范足够明确时AI可以生成更准确的代码反过来当代码需要修改时开发者必须先更新规范确保文档永远不会过时。2. 从零开始搭建OpenSpec工作环境2.1 初始化项目让我们用一个电商平台的订单支付模块作为示例。首先在项目根目录运行openspec init .这会创建以下目录结构openspec/ ├── AGENTS.md # AI助手指令 ├── project.md # 项目上下文 ├── specs/ # 规范目录 ├── changes/ # 变更提案 └── archive/ # 归档历史关键文件说明project.md定义项目级约束比如## 技术栈 - 前端React 18 - 后端Node.js 16 - 数据库PostgreSQL 14 ## 代码风格 - TypeScript严格模式 - API响应格式{ data: T, error: string|null }AGENTS.md告诉AI助手如何理解你的规范例如!-- OPENSPEC:START -- 当处理支付相关功能时 1. 优先检查specs/payment/spec.md 2. 所有金额以分为单位存储 3. 必须处理网络超时情况 !-- OPENSPEC:END --2.2 创建第一个规范为支付功能创建规范文件mkdir -p openspec/specs/payment在specs/payment/spec.md中定义基础需求## Requirement: Order Payment The system SHALL process payment for submitted orders. ### Scenario: Credit card payment success - **WHEN** user submits valid card details - **WHEN** card balance ≥ order amount - **THEN** charge the card - **THEN** update order status to paid ### Scenario: Insufficient balance - **WHEN** user submits valid card details - **WHEN** card balance order amount - **THEN** decline payment - **THEN** show Insufficient balance error这种结构化规范比自然语言描述更精确也更容易被AI理解。我曾经在一个项目中测试过使用OpenSpec后AI生成的支付接口代码第一次通过测试的概率从40%提升到了85%。3. 变更管理从提案到实施的完整流程3.1 创建变更提案假设现在需要添加支付超时功能标准的OpenSpec流程如下生成变更IDopenspec list # 检查是否冲突 # 使用动词开头的kebab-case命名 change_idadd-payment-timeout创建提案目录mkdir -p openspec/changes/$change_id/specs/payment编写proposal.md# Change: Add Payment Timeout Handling ## Why - 当前支付接口可能长时间挂起 - 需要15秒超时机制避免资源占用 ## What Changes - 新增支付超时需求 - 修改支付处理流程 - 添加超时错误处理 ## Impact - 修改specs/payment/spec.md - 修改services/payment.ts编写tasks.md- [ ] 1. 添加超时需求到规范 - [ ] 2. 实现后端超时逻辑 - [ ] 3. 前端添加超时提示 - [ ] 4. 测试不同超时场景3.2 实施变更批准提案后AI助手可以根据规范增量生成代码框架。比如在changes/add-payment-timeout/specs/payment/spec.md中## ADDED Requirements ### Requirement: Payment Timeout The system SHALL cancel payment processing after 15 seconds. #### Scenario: Payment timeout - **WHEN** payment processing exceeds 15 seconds - **THEN** cancel the transaction - **THEN** return timeout error - **THEN** unlock reserved inventory基于这份规范AI可能会生成类似代码// services/payment.ts async function processPayment(orderId: string) { const timeout new Promise((_, reject) setTimeout(() reject(Payment timeout), 15000)); try { await Promise.race([actualPayment(orderId), timeout]); } catch (error) { await unlockInventory(orderId); // 规范中明确要求 throw error; } }3.3 归档变更部署完成后运行openspec archive add-payment-timeout --yes这会将变更移动到archive/2023-08-20-add-payment-timeout/自动合并规范变更到specs/payment/spec.md更新系统状态4. 高级技巧应对复杂场景的实践4.1 处理跨模块变更当变更涉及多个模块时比如支付和库存联动建议在design.md中描述交互流程## 支付超时时的库存回滚 mermaid sequenceDiagram Payment-Inventory: 预占库存 Payment-Gateway: 发起支付 Gateway--xPayment: 超时 Payment-Inventory: 释放库存在规范中使用交叉引用### Scenario: Inventory rollback - **WHEN** payment times out - **THEN** release reserved inventory (see inventory/spec.md#hold-release)4.2 规范版本控制技巧虽然OpenSpec会自动管理规范版本但有些经验值得分享使用openspec show change-id --json查看变更详情重要变更添加标签openspec archive add-payment-timeout --yes --tag v2.3回滚时先检查历史openspec list --archive | grep payment4.3 调试规范冲突当多个变更同时修改同一规范时可以检查冲突openspec validate --strict --check-conflicts使用三方合并工具openspec merge-tool add-payment-timeout update-payment-ui我在实际项目中发现规范冲突往往能提前发现设计矛盾。有次两个团队分别修改支付流程OpenSpec在合并时立即提示了状态机不一致的问题避免了线上事故。5. 与AI助手的高效协作模式5.1 优化AI指令在AGENTS.md中添加支付领域特定提示!-- PAYMENT:START -- 1. 所有金额计算使用decimal.js 2. 审计日志必须包含 - 支付渠道 - 请求/响应时间戳 - 最终状态 3. 错误代码遵循规范 - 4XX: 客户端错误 - 5XX: 服务端错误 !-- PAYMENT:END --5.2 典型交互流程AI识别支付相关任务时自动插入指令头根据 openspec/specs/payment/spec.md#timeout 要求 - 必须实现15秒超时 - 必须释放预占库存开发者审核时运行验证openspec validate --ai-output payment.patch自动生成测试用例// 根据Scenario自动生成 test(should timeout after 15s, async () { mockGatewayDelay(16000); await expect(processPayment(orderId)) .rejects.toThrow(Payment timeout); expect(inventory.isLocked(orderId)).toBe(false); });5.3 性能优化案例在处理高并发支付时我们通过规范约束AI的代码生成### Requirement: Concurrent Processing The system SHALL handle ≥1000 concurrent payment requests. #### Scenario: Peak load - **WHEN** 1000 requests arrive within 1 second - **THEN** process at least 800 TPS - **THEN** latency ≤2s for 95% requests这使AI优先选择连接池、批量处理等优化策略而不是直接写简单循环。实测这种约束下的代码性能提升了3倍。