OSpec 的主要流程是什么：一个 change 里有哪些文档，AI 每一步在做什么

很多人第一次接触 OSpec，会以为它只是“让 AI 帮你写代码”的一层壳。

但 OSpec 真正想解决的问题，不只是代码怎么写，而是一个需求从“开始”到“交付完成”这整个过程，怎么变得更清楚、更可追踪，也更适合和 AI 一起协作。

如果用最简单的话来讲，OSpec 的核心流程只有三段：

• 先把项目初始化到可执行状态
• 再围绕一个明确需求推进一个 change
• 最后在验收后把这个 change 归档

看起来很简单，但它的关键在于：每个需求不会只留在聊天记录里，而是会落到仓库里的 change 文档中。这样人能看，AI 也能继续接着做。

先理解一个核心概念：什么是 change

在 OSpec 里，一个 change 可以理解成“这一次明确要交付的事情”。

它可以是：

• 一个新功能
• 一个 Bug 修复
• 一次文档更新
• 一次重构
• 一组紧密相关的小改动

重要的不是它一定多大，而是它要足够明确。
OSpec 的默认思路不是把所有事情混在一起做，而是让一个 change 尽量只承载一个清楚的目标。

这样做的好处是：

• 范围更清楚
• 执行过程更容易检查
• AI 不容易越做越散
• 到最后归档时，也知道这次到底完成了什么

OSpec 的主要流程

如果从最公开、最常见的使用方式来看，主流程可以理解成 3 步。

第一步：初始化项目

这一步的目标，是把仓库带到一个 change-ready 的状态。

你可以理解成：不是先开始做需求，而是先把项目整理到“可以正式进入 AI 协作交付”的状态。

在这一步里，AI 主要会帮你做这些事：

• 识别这个项目是不是已经初始化过
• 如果项目信息不够，会补齐基础项目上下文
• 生成或维护一套后续协作要用到的项目知识文档
• 确认仓库里已经具备后续做 change 的基本结构

这一步完成后，项目里通常会有这些基础内容：

• .skillrc
• .ospec/
• changes/active/
• changes/archived/
• docs/project/overview.md
• docs/project/tech-stack.md
• docs/project/architecture.md
• docs/project/module-map.md
• docs/project/api-overview.md

通俗一点说，这一步不是在“做需求”，而是在“把地基打好”。

第二步：开始一个 change

当你有一个明确需求时，就会进入第二步。

这时候，OSpec 会围绕这个需求创建一个独立的 change 目录。后面的执行、记录、验证、归档，都会围绕这个 change 展开。

你可以把它理解成：从这一步开始，这个需求不再只是聊天记录，而是正式变成仓库里可以追踪的一项工作。

一个 change 里通常有哪些文件

一个 active change 里，最核心的几个文件通常是这些：

• proposal.md
• tasks.md
• state.json
• verification.md

很多项目里还会有：

• review.md

如果某个 change 比较复杂，或者触发了额外流程，也可能还会出现更多文档。但对大多数需求来说，上面这几个已经是最核心的一层。

下面用最通俗的方式讲它们分别是干什么的。

proposal.md 是做什么的

proposal.md 可以理解成“这次到底要做什么，为什么做”。

它回答的 usually 是这些问题：

• 这次 change 的目标是什么
• 为什么要做这件事
• 会影响哪些页面、模块或流程
• 这次不做什么

如果你把一个需求直接丢给 AI 就开干，AI 很容易越做越宽。
而有了 proposal.md，AI 就相当于先把边界写清楚，再开始往下执行。

在这一步里，AI 主要做的是：

• 帮你把模糊需求整理成清楚目标
• 写出这次 change 的背景、范围和边界
• 把“要做什么”和“先不做什么”分开

你可以把 proposal.md 理解成：这次工作的说明书。

tasks.md 是做什么的

tasks.md 可以理解成“这次准备怎么做”。

如果说 proposal.md 解决的是“做什么”，那 tasks.md 解决的就是“先做哪一步，后做哪一步”。

里面通常会写：

• 要做的主要任务
• 任务之间的大致顺序
• 哪些已经完成，哪些还没完成
• 有没有额外的可选步骤或检查项

这一步很重要，因为 AI 一旦开始执行，如果没有任务拆分，就容易出现两种情况：

• 一次做太多，范围失控
• 做到一半不知道现在进行到哪了

在这一步里，AI 主要做的是：

• 把 change 拆成可以执行的任务
• 给每个任务安排合理顺序
• 在推进过程中持续勾掉已完成项
• 让你一眼就能看到当前进度

你可以把 tasks.md 理解成：这次工作的施工清单。

state.json 是做什么的

state.json 是 change 的“机器可读状态”。

它和 proposal.md、tasks.md 不太一样。前两个更适合人看，而 state.json 更适合让工具和 AI 知道：这个 change 现在进行到哪一步了。

里面通常会记录这些信息：

• 当前状态是不是 active
• 当前步骤走到哪了
• 哪些阶段已经完成
• 这个 change 关联了哪些文件
• 是否已经归档

通俗一点说，state.json 更像是 change 的运行状态板。

在这一步里，AI 主要做的是：

• 随着执行推进更新当前状态
• 标记 proposal、tasks、verification 等环节是否完成
• 让后续的 verify、archive、finalize 更容易接上

你平时未必会一直手动去看它，但它对整个流程是否稳定非常重要。

verification.md 是做什么的

verification.md 可以理解成“这次怎么证明它真的完成了”。

很多团队的问题不是没做，而是做到最后说不清“怎么确认它真的好了”。
verification.md 就是专门解决这件事的。

里面通常会写：

• 做了哪些验证
• 跑了哪些构建、测试或检查
• 哪些结果已经通过
• 有没有未完成或被豁免的项

这一步里，AI 主要做的是：

• 记录实际执行过的验证动作
• 把验证结果写清楚
• 区分“已经验证通过”和“还没验证”这两件事
• 帮你在归档前把证据留在仓库里

你可以把 verification.md 理解成：这次交付的验收记录。

review.md 是做什么的

review.md 不是每个 change 都一定是主角，但它很常见。

它更像是“这次实现有什么风险、发现了什么问题、有没有需要注意的地方”。

如果 change 比较大、跨模块、风险高，review 就很有价值。

在这一步里，AI 主要做的是：

• 站在 review 视角检查改动
• 记录发现的问题、风险和遗漏
• 帮团队把“做完了”进一步变成“做得是否可靠”

你可以把 review.md 理解成：这次交付的复核意见。

AI 在整个 change 过程中到底做什么

如果把整条流程放在一起看，AI 在 OSpec 里不是只负责“写代码”，而是会在不同阶段做不同的事。

在开始前

AI 会帮助你：

• 理解需求
• 判断范围
• 把模糊想法整理成一个明确 change
• 生成 proposal 和初始任务结构

在执行中

AI 会帮助你：

• 按 tasks 推进实现
• 更新 state
• 根据执行结果调整任务顺序
• 在需要时补充文档、代码、说明和验证动作

在收口时

AI 会帮助你：

• 记录验证结果
• 整理 review 发现
• 确认这个 change 是否已经达到可归档状态
• 把这次交付的结果沉淀到仓库里，而不是只留在聊天里

通俗一点说，AI 在 OSpec 里的角色，不是“替你一下写完所有东西”，而是“陪你把一个 change 从开始推进到能交付、能解释、能归档”。

最后一步：归档这个 change

当这个 change 已经完成开发、验证和验收后，就会进入最后一步：归档。

归档的意思不是把它删掉，而是把它从 changes/active/ 移到 changes/archived/，表示这项工作已经收口。

这样以后再回头看，你仍然能知道：

• 当时为什么做
• 做了哪些任务
• 中间状态怎么推进
• 最后是怎么验证通过的

这也是 OSpec 和普通“AI 聊完就结束”的最大区别之一。
它会把这次交付留下来，变成可追踪、可回看、可交接的仓库记录。

为什么这种流程适合和 AI 一起工作

因为 AI 很擅长推进，但如果没有边界、任务、状态和验证，它也很容易发散。

OSpec 做的事情，本质上就是给 AI 协作加上一层结构：

• 用 proposal.md 管边界
• 用 tasks.md 管执行
• 用 state.json 管状态
• 用 verification.md 管验收
• 用 review.md 管复核
• 用 archive 管收口

这样 AI 每一步都不是在“凭感觉继续”，而是在一个明确 change 里继续。

结语

如果只看表面，OSpec 好像多了几份文档。
但如果从交付过程来看，它其实是在帮团队把“需求、执行、验证、归档”这几件原本很容易散掉的事情，重新收进同一个 change 里。

最重要的不是多了多少文件，而是每次做需求时，你能更清楚地知道：

• 这次要做什么
• 现在做到哪了
• 怎么证明它完成了
• 以后怎么回头看这次改动

这就是 OSpec 的主流程真正想解决的问题。

如果你刚开始使用 OSpec，最容易理解它的方法不是先记命令，而是先记住这一句：

先把项目初始化好，再围绕一个明确需求推进一个 change，最后把这次交付完整地归档下来。