收录于 AI

2026-04-08 约 633 字预计阅读 3 分钟 - 次阅读

OpenSpec 工程化规范总结

什么是 OpenSpec

OpenSpec 是一个面向 AI 编码助手的规范驱动开发框架（Spec-Driven Development，SDD）。它的核心理念是在编写任何代码之前，先创建可审查的规范（Spec），让人类开发者和 AI 编码助手能够就项目意图达成共识。

该项目在 GitHub 上已获得 37,000+ 颗星，是 AI 开发工具领域最受欢迎的项目之一。

核心价值

1. 解决 AI 编程的沟通问题

传统编程中，开发者通过代码表达意图。但 AI 编程助理解读代码时可能会产生偏差，导致：

实现与预期不符
重复修改
项目失控

OpenSpec 通过在编码前明确定义规范来解决这个问题。

2. 版本控制意图

OpenSpec 充当「意图的版本控制」：

规范文件可以被审查
可以版本化管理
可以追踪意图的演变
便于人类和 AI 协同理解

3. 防止「氛围编程」

「Vibe Coding」（氛围编程）是指盲目跟随 AI 生成代码，缺乏深思熟虑的设计。OpenSpec 强制要求在编码前思考和规划。

OpenSpec 规范结构

1. Project Spec（项目规范）

定义项目的整体结构和目标：

1
2
3
4
5
6
7


name: my-project
description: A web application for task management
version: 1.0.0
techStack:
  - React
  - TypeScript
  - Node.js

2. Feature Spec（功能规范）

定义具体功能的实现要求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


feature: user-authentication
description: User login and registration system

requirements:
  - Email/password authentication
  - JWT token management
  - Password reset functionality

acceptanceCriteria:
  - Users can register with email
  - Users can login and receive token
  - Invalid credentials show error message

3. Code Spec（代码规范）

定义具体的代码实现要求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


component: UserService
language: TypeScript

structure:
  - class UserService
    - method: authenticate()
    - method: register()
    - method: resetPassword()

constraints:
  - Use bcrypt for password hashing
  - JWT expiry: 24 hours
  - Rate limiting: 5 attempts per minute

OpenSpec 工作流程

1. 需求分析

与用户沟通，明确：

项目目标
功能需求
技术约束
验收标准

2. 编写规范

创建规范文档：

项目规范（Project Spec）
功能规范（Feature Spec）
代码规范（Code Spec）

3. 审查规范

人类开发者审查规范：

检查需求完整性
验证技术可行性
确认验收标准

4. AI 编码

基于规范进行编码：

AI 严格按照规范实现
规范作为验收依据
偏离规范时警告

5. 验证交付

对照规范验证：

功能是否满足需求
代码是否符合规范
验收标准是否达成

OpenSpec 核心原则

1. 明确性（Clarity）

规范应该是明确的、无歧义的：

使用具体语言
避免模糊描述
列出所有边界情况

2. 可验证性（Verifiability）

每个规范应该有验收标准：

可以测试
可以验证
可以量化

3. 完整性（Completeness）

规范应该覆盖所有方面：

功能需求
非功能需求
边界情况
错误处理

4. 一致性（Consistency）

规范内部应该保持一致：

术语统一
格式统一
逻辑连贯

与其他方法的对比

特性	OpenSpec	传统文档	Prompt Engineering
时机	编码前	编码中/后	编码时
结构化	强	弱	中
AI 友好	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐
版本控制	支持	有限	不支持
人类审查	友好	一般	困难

实际应用案例

案例一：Web 应用开发

规范示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


feature: task-management
requirements:
  - Create, read, update, delete tasks
  - Assign tasks to users
  - Set due dates and priorities
  
techStack:
  - React + TypeScript
  - Node.js + Express
  - PostgreSQL
  
acceptanceCriteria:
  - [ ] CRUD operations work correctly
  - [ ] Users can assign tasks
  - [ ] Due dates can be set and viewed
  - [ ] All API responses < 200ms

案例二：API 开发

规范示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


endpoint: /api/users
method: GET

request:
  params:
    - name: page
      type: integer
      required: false
      default: 1
    - name: limit
      type: integer
      required: false
      default: 20
      
response:
  status: 200
  body:
    users: array
    pagination: object
      
errors:
  - 401: Unauthorized
  - 500: Internal Server Error

案例三：组件开发

规范示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


component: Button

props:
  - name: variant
    type: 'primary' | 'secondary' | 'danger'
    required: true
  - name: size
    type: 'small' | 'medium' | 'large'
    default: 'medium'
  - name: disabled
    type: boolean
    default: false
    
events:
  - onClick: () => void
    
styles:
  - borderRadius: 4px
  - padding: 8px 16px

工具和集成

1. VS Code 插件

OpenSpec 提供 VS Code 插件：

规范语法高亮
自动补全
预览生成

2. CLI 工具

1
2
3
4
5
6
7
8


# 初始化项目
openspec init

# 验证规范
openspec validate

# 生成代码骨架
openspec generate

3. 集成 CI/CD

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# .github/workflows/openspec.yml
name: OpenSpec Validation
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate Specs
        run: openspec validate

最佳实践

1. 规范粒度

不要过度细化：保持规范可读
不要过于笼统：确保可操作性
找到平衡点：足够具体但不过于繁琐

2. 验收标准

使用「可验证」的语言
列出具体的测试用例
定义成功/失败的标准

3. 迭代更新

规范需要随需求变化
保持规范和代码同步
记录规范变更历史

4. 团队协作

统一规范格式
定期审查规范
分享最佳实践

常见问题

1. 规范会不会太耗时？

初期可能需要时间投入，但长期来看：

减少返工
提高代码质量
便于维护

2. AI 会遵循规范吗？

大多数 AI 助手会优先遵循规范：

规范提供了明确的约束
偏离规范会降低成功率
人类审查可以发现偏差

3. 如何处理规范变更？

记录变更原因
更新规范版本
重新审查代码

总结

OpenSpec 为 AI 编程提供了一个结构化、可审查的规范框架。它的核心价值在于：

建立共同理解：人类和 AI 就项目意图达成共识
提高代码质量：通过预先规划减少错误
便于维护：规范成为项目的文档和契约

对于使用 AI 编程助手的开发者来说，OpenSpec 是一个值得尝试的工程化实践。它不仅提高了开发效率，更重要的是，它让 AI 编程变得更加可控和可靠。

参考链接

GitHub 仓库：https://github.com/Fission-AI/OpenSpec
官方网站：https://openspec.dev
文档：https://docs.openspec.dev