OpenSpec新手教程-20260304

0. OpenSpec 是什么（新手版一句话）

OpenSpec =把“我要做什么”写成可读、可检查、可合并的规范（spec），再让 AI/人按规范实现；实现完成后，把“变更规范”合并回“当前规范”，从而减少 AI 乱发挥和需求漂移。(GitHub)

1. 准备工作（5 分钟内搞定）

1.1 你需要什么

• Node.js ≥ 20.19.0（官方文档/README 都这么写）(GitHub)
• 任意包管理器：npm/pnpm/yarn/bun（都支持）(GitHub)

1.2 安装 OpenSpec CLI

npminstall-g@fission-ai/openspec@latest openspec--version

(GitHub)

2. 第一次上手：在你的项目里初始化 OpenSpec

进入你的项目根目录（没有项目也行，先建个空文件夹）：

mkdirmy-projectcdmy-project# （可选）如果你打算用 Node 项目npminit-y

然后初始化：

openspec init

初始化会做几件关键事：

• 在项目里生成openspec/目录骨架（specs / changes / 可选 config.yaml 等）(GitHub)
• 生成给 AI 用的说明文件（例如AGENTS.md、以及不同工具的命令/规则配置）(thedocs.io)
• 让你选择正在使用的 AI 工具，并为它生成对应“斜杠命令”配置（Claude Code、Cursor、Windsurf、Copilot 等）(thedocs.io)

小提醒：不同 AI 工具的命令写法不完全一样，后面我会给一张对照表。(GitHub)

3. 目录结构怎么读（你只需要记住 2 个核心目录）

初始化后，OpenSpec 项目通常长这样（精简版）：

• openspec/specs/：当前系统“事实真相”（已部署/已认可的行为规范）(thedocs.io)
• openspec/changes/：一次变更一个文件夹，里面放这次改动的“为什么/改什么/怎么做/任务清单/规范增量”(thedocs.io)

一个 change 文件夹里常见四件套：

• proposal.md（为什么、范围、影响）
• specs/（delta specs：只写新增/修改/删除的规范片段