这是一个使用 OpenSpec 进行规范驱动开发（Spec-driven Development）的项目示例。

OpenSpec 是 Fission 团队为 AI 编码助手设计的规范驱动开发框架，通过 specs（当前真相）+ changes（变更提案），把"系统应该怎样工作"写成机器和人都能理解的文档。

核心价值：

• 🎯 需求清晰：用 Requirement / Scenario 形式明确表达系统行为
• 📝 变更可追踪：所有变更通过 change proposal 管理，形成清晰的变更历史
• 🤖 AI 行为可控：AI 在写代码前先阅读并遵守 spec，而不是凭 prompt 即兴发挥
• 👥 团队协作：产品、开发、测试、AI 共用同一套"单一真相"

# 1. 安装 Node.js（建议 LTS 版本）
node -v && npm -v

# 2. 全局安装 OpenSpec CLI
npm install -g @fission-ai/openspec@latest
openspec --version

# 3. 在项目中初始化（如果尚未初始化）
openspec init

# 4. 验证安装
openspec list          # 查看当前是否有变更
openspec list --specs  # 查看当前已有 specs

本项目已配置好 Cursor 命令集成，可以直接使用：

• /openspec-proposal：创建变更提案和规格 delta
• /openspec-apply：根据已批准的 change 驱动实现
• /openspec-archive：变更上线后进行归档

.
├── README.md                    # 项目说明文档
├── AGENTS.md                    # 根目录 AI 助手说明（指向 openspec/AGENTS.md）
├── docs/                        # 文档目录
│   └── openspec-training.md     # OpenSpec 培训文档
├── openspec/                    # OpenSpec 配置目录
│   ├── AGENTS.md                # OpenSpec 工作流和规范说明
│   ├── project.md               # 项目级约定（技术栈、风格、命名等）
│   ├── specs/                   # 当前真相（系统已实现的能力）
│   │   └── openspec-training/   # 培训文档能力
│   │       └── spec.md          # Requirements & Scenarios
│   └── changes/                 # 变更提案（应有的未来）
│       ├── refactor-openspec-training-doc/  # 示例变更
│       └── archive/             # 已完成变更的归档目录
└── .cursor/                     # Cursor 配置
    └── commands/                # Cursor 命令定义
        ├── openspec-proposal.md
        ├── openspec-apply.md
        └── openspec-archive.md

openspec/specs/ 目录描述"系统现在应该怎样工作"，按 capability（能力）划分：

• 每个 capability 目录表示一个相对独立的业务/技术能力
• spec.md 用 Requirement / Scenario 格式描述能力
• design.md（可选）记录技术设计决策

openspec/changes/ 目录描述"我们打算把系统改成怎样"：

• 每个 change 目录代表一个变更故事
• 包含 proposal.md（为什么改、改什么）、tasks.md（实施清单）、design.md（可选）
• specs/ 子目录包含对受影响 capability 的 Requirement delta（ADDED/MODIFIED/REMOVED/RENAMED）

1. 创建 Change：使用 /openspec-proposal 创建变更提案
2. 审查提案：团队审查 proposal 和 spec delta
3. 实施变更：使用 /openspec-apply 按 tasks 驱动实现
4. 归档变更：功能上线后，使用 /openspec-archive 归档并更新 specs

# 查看当前活跃的变更
openspec list

# 查看当前所有 specs（已生效能力）
openspec list --specs

# 查看某个 change 或 spec 详情
openspec show <change-id>
openspec show <spec-id> --type spec

# 校验格式/结构
openspec validate <change-id> --strict
openspec validate --strict   # 对全项目做严格校验

# 归档一个已上线的 change
openspec archive <change-id> --yes

• 培训文档：docs/openspec-training.md - 完整的 OpenSpec 使用指南
• 官方仓库：OpenSpec on GitHub
• 项目规范：openspec/AGENTS.md - OpenSpec 工作流和规范说明

本项目包含一个完整的变更示例：refactor-openspec-training-doc，展示了如何：

• 创建 change proposal
• 编写 spec delta
• 定义 tasks
• 实施变更
• 归档变更

查看示例：

openspec show refactor-openspec-training-doc

本项目作为 OpenSpec 的使用示例，欢迎：

• 提出改进建议
• 分享使用经验
• 贡献更多示例

本项目遵循 OpenSpec 项目的许可证。