OpenSpec 详解与 Course 结合使用指南
一、OpenSpec 是什么
OpenSpec是由 Fission AI 团队发起的轻量级开源规范驱动开发（Spec-Driven Development, SDD）框架和命令行工具（CLI），核心理念是先写规格（Spec），再写代码，专为 AI 辅助编程场景设计。
核心定位与价值
- 解决 AI 编程中需求模糊、幻觉、需求偏移问题，将散落在聊天记录中的需求固化为结构化规范
- 提供可审查、可追溯、确定性的 AI 开发工作流，让人类开发者主导，AI 严格执行
- 无需 API 密钥、极简配置、广泛兼容主流 AI 编码工具（Cursor、Claude Code、GitHub Copilot 等）
- 采用双文件夹模型：
openspec/specs/：当前系统真实行为规范（事实来源 Source of Truth）openspec/changes/：正在提议的更新（变更提案）
核心工作流（5 阶段）
- 创建变更提案（proposal）：明确需求与目标
- 编写并审核规范（spec）：细化技术方案、约束条件
- AI 实施（implementation）：AI 基于规范生成/修改代码
- 测试验证（validation）：验证代码符合规范要求
- 归档与更新规范（archival）：将变更合并到主规范中
二、OpenSpec 安装与基础使用
1. 安装（Node.js 环境）
# 全局安装最新版本npminstall-g @fission-ai/openspec@latest# 验证安装成功openspec --version2. 初始化项目
# 在现有项目根目录执行初始化openspec init# 生成目录结构your-project/ └── openspec/ ├── specs/# 存放主规范文件│ └── README.md └── changes/# 存放变更提案3. 核心命令
| 命令 | 功能 |
|---|---|
openspec init | 初始化 OpenSpec 目录结构 |
openspec new <proposal-name> | 创建新的变更提案 |
openspec apply <change-id> | 应用变更提案并更新主规范 |
openspec list | 列出所有变更提案及其状态 |
openspec archive <change-id> | 归档已完成的变更提案 |
三、详细使用示例（完整实战）
以React+TypeScript 项目添加用户登录组件为例
示例 1：创建变更提案并编写规范
创建新提案
openspec new feature/add-login-component自动生成文件：
openspec/changes/20260113-feature-add-login-component/编写规范文件（
spec.md）# 功能：添加用户登录组件 ## 项目上下文 - 技术栈：React 18+TypeScript+Tailwind CSS - 现有架构：组件采用函数式+hooks，表单使用 React Hook Form ## 需求与目标 1. 实现登录表单（用户名+密码） 2. 支持表单验证（必填、密码最小长度 6） 3. 实现登录按钮与提交逻辑（调用 /api/login 接口） 4. 显示登录状态与错误提示 ## 约束条件 - 组件名：LoginForm（PascalCase） - 样式：使用 Tailwind CSS，遵循项目现有设计规范 - 安全：密码输入框使用 type="password"，不显示明文 - 可测试：添加单元测试（Jest+React Testing Library）
示例 2：AI 实施与代码生成（结合 Claude Code）
将规范提供给 Claude Code 并生成代码
# 调用 Claude CLI，传入规范文件catopenspec/changes/20260113-feature-add-login-component/spec.md|claude codeClaude 生成符合规范的代码（示例简化版）
// src/components/LoginForm.tsx import React from 'react'; import { useForm } from 'react-hook-form'; interface LoginFormInputs { username: string; password: string; } const LoginForm: React.FC=() => { const { register, handleSubmit, formState: { errors } }=useForm<LoginFormInputs>(); const onSubmit=(data: LoginFormInputs) => { // 调用登录 API fetch('/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) }); }; return ( <form onSubmit={handleSubmit(onSubmit)} className="space-y-4 p-6"> <div> <label>用户名</label> <input {...register('username', { required: '用户名必填' })} className="w-full p-2 border rounded" /> {errors.username && <p className="text-red-500">{errors.username.message}</p>} </div> <div> <label>密码</label> <input type="password" {...register('password', { required: '密码必填', minLength: { value: 6, message: '密码至少 6 位' } })} className="w-full p-2 border rounded" /> {errors.password && <p className="text-red-500">{errors.password.message}</p>} </div> <button type="submit" className="w-full bg-blue-500 text-white p-2 rounded">登录</button> </form> ); }; export default LoginForm;
示例 3：验证与归档
- 测试代码符合规范要求（单元测试、手动测试）
- 应用变更并更新主规范
# 获取变更 ID（查看列表）openspec list# 应用变更openspec apply20260113-feature-add-login-component# 归档变更openspec archive20260113-feature-add-login-component - 主规范
openspec/specs/components.md自动更新，添加 LoginForm 组件规范
OpenSpec 不仅是 AI 辅助编程的工具，更是一种规范驱动的开发理念。
