OpenSpec 学习总结（面向本仓库落地）

来源：Fission-AI/OpenSpec —— 面向 AI Coding Assistant 的 Spec-driven development (SDD) 框架，通过“变更文件夹 + 一组标准产物”把需求、设计、任务从聊天里沉淀出来，提升可控性与可追溯性。

1. OpenSpec 解决什么问题

OpenSpec 的定位是给 AI 编程加一层“轻量 spec”，避免需求只存在于聊天窗口导致的漂移与不可复现：

Agree before you build：先对齐再写代码（至少把关键点写成产物）。
Stay organized：每个变更独立目录，包含 proposal/spec/design/tasks。
Work fluidly：强调“可迭代、非瀑布”，产物可以随时修改更新。
Tool-agnostic：通过 slash commands 集成多种工具/代理。

它的哲学（README 原文要点）：

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

2. 核心产物（Artifacts）与目录形态

README 的示例工作流中，一个变更通常会生成类似结构：

openspec/changes/<change-name>/
- proposal.md：为什么要做、改动范围是什么（偏“业务/动机/边界”）
- specs/：需求与场景（可拆分多个 spec 条目）
- design.md：技术方案（架构、数据流、取舍、风险）
- tasks.md：实现 checklist（可执行、可验证）

完成后可归档到：

openspec/changes/archive/<date>-<change-name>/...

3. 常用命令/工作流（README 主线）

3.1 最常用的三步

/opsx:propose "your idea"
- 生成变更目录与四类产物（proposal/specs/design/tasks），准备进入实现。
/opsx:apply
- 按 tasks.md 开始执行实现任务（逐项完成）。
/opsx:archive
- 归档本次变更目录，进入下一项工作。

3.2 扩展工作流（README 提到的命令集合）

OpenSpec 还有“expanded workflow”命令集（如：/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard），可通过配置 profile 选择并用 openspec update 应用到项目。

4. 安装与更新（README 要点）

Node 版本要求：Node.js 20.19.0+
全局安装：
- npm install -g @fission-ai/openspec@latest
初始化项目：
- openspec init
升级 OpenSpec：
- npm install -g @fission-ai/openspec@latest
刷新/更新项目内指令与命令集：
- openspec update

5. Telemetry（使用统计）与关闭方式

README 说明 OpenSpec 会收集匿名使用统计（仅命令名与版本，不含参数/路径/内容/PII；CI 默认关闭）。

关闭方式：

export OPENSPEC_TELEMETRY=0 或
export DO_NOT_TRACK=1

6. 在本仓库的落地：现状与建议配置点

本仓库已存在 openspec/config.yaml，内容要点：

schema: spec-driven
支持写入：
- project context：在创建 artifacts 时提供给 AI 的项目背景（技术栈、规范、目录结构、敏感信息规则等）
- per-artifact rules：对 proposal/specs/design/tasks 分别加约束（字数、必须包含 Non-goals、任务粒度、验证要求等）

建议你们把仓库已有的工程规范（例如各子系统目录约定、代码风格、禁止/必须项）浓缩进 config.yaml 的 context:，并为 tasks 加上“每条任务必须包含验证命令/预期结果”的规则，这样 /opsx:apply 的执行会更稳定、更可验收。

（本总结只覆盖 README 主线能力；如需更细的命令说明与 schema 自定义方式，可继续阅读 OpenSpec 仓库的 docs/ 与 schemas/。）

openspec-学习总结.md 3.7 KB Link permanente Histórico Raw