OpenSpec 实测：五步搞定 AI 编程，需求不跑偏、修改有记录

发布时间：2025-12-28 20:03

定期监测并记录自己的跑步数据以追踪进步 #生活乐趣# #运动健身乐趣# #跑步热衷者#

今天介绍一个能让 AI 编程变“听话”的新工具：OpenSpec。它不是什么复杂平台，而是一个轻量级命令行工具 + 一套标准协作流程，核心就一句话：先定规矩，再写代码。

一、OpenSpec 是什么？给你的 AI 配上“需求图纸”

你可以把它理解为 “AI 编程的项目经理” 。它不做具体编码（你还是用你熟悉的 Cursor、Copilot 等工具），而是帮你和 AI 之间建立清晰的“施工契约”。

定位：它不是替代你的 AI 编程工具。它是给这些工具配的“需求翻译器”和“进度跟踪器”。尤其擅长迭代现有项目（从 1 到 N），对已有代码进行可控的增强和重构。二、它能干什么？让每次改动都清晰可查

1、极简上手：npm install 一下，几条命令就能用。

2、无缝兼容：支持 Cursor、Claude Code、Copilot 等主流工具，直接集成到它们的聊天命令里。

3、全程留痕：每次功能改动，自动生成四份“档案”：

提案文档（为什么要做？做什么？)设计决策（为什么用这个方案？)任务清单（具体分几步实现？)规范更新（比如，新增的数据结构长啥样？)

4、变更可溯：所有历史提案、讨论、实现记录都沉淀下来，项目怎么演进的，一目了然。

四、怎么用？五步走，像管理项目一样管理 AI

假设你要给项目加一个“Word 转 Markdown”功能：

1、【起草提案】：别急着写代码。先对 AI 说：/openspec:proposal 添加Word转Markdown功能。AI 会反过来问你关键细节（支持哪些格式？遇到图片怎么处理？），然后生成一份结构化的“需求说明书”和任务列表。此时一行代码都没写。

2、【审查对齐】：你和 AI 一起评审这份“说明书”。需求全了吗？技术方案靠谱吗？这时修改成本几乎为零。这一步是重点，稍微不留神需求就搞错了。

3、【实施编码】：确认无误后，执行 /openspec:apply。AI 才会开始，严格按照任务清单编码，一步一个脚印。

4、【归档更新】：功能测试通过后，执行 /openspec:archive。这次改动的所有“档案”会自动合并到主项目文档里，形成一次干净的交付记录。

5、【规范演进】：随着一次次“提案-归档”，你的项目会拥有一份和代码实时同步的“活文档”，它就是项目最权威的“宪法”。

五、一些真心建议从小功能试起：先拿“改个按钮颜色”走通全流程，建立信心。珍惜 AI 的提问：它追问的每个细节，都是你未来可能踩的坑。提案阶段多打磨：这时改需求动动嘴，写完代码再改可能要命。把规范当核心资产：代码会重构，但这份持续生长的“活文档”，才是项目长期的导航图。如果只是个人项目，个人感觉，非必要无需使用。六、实战案例深度解析：Word 转 Markdown

1、进入项目目录

cd wd2md

2、运行初始化

openspec init

系统会提示你选择任何原生支持的 AI 工具，比如 Claude Code、Cursor 等等

然后项目的目录内就会有如下变化，比如当选择 Claude Code 时 Claude.md 里会增加说明，内容实际是和根目录中 AGENTS.md 一样，是一份 OpenSpec 说明。

# OpenSpec InstructionsThese instructions are for AI assistants working in this project.Always open `@/openspec/AGENTS.md` when the request:- Mentions planning or proposals (words like proposal, spec, change, plan)- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work- Sounds ambiguous and you need the authoritative spec before codingUse `@/openspec/AGENTS.md` to learn:- How to create and apply change proposals- Spec format and conventions- Project structure and guidelinesKeep this managed block so 'openspec update' can refresh the instructions.

同时在当前项目。claude 目录里添加了一些命令：proposal、apply、archive，主要是 prompt 说明

.claude├── commands│ └── openspec│ ├── apply.md│ ├── archive.md│ └── proposal.md

然后就是增加 AGENTS.md 及 openspec 目录，openspec 目录就是后续我们主要讨论生成需求及协作的文件。

AGENTS.mdopenspec├── AGENTS.md├── changes│ └── archive├── project.md└── specs

3、完善项目文档 project.md

1.填写你的项目上下文："请阅读 openspec/project.md 并帮助我填写项目详情、技术栈和约定规范" 2.创建你的第一个变更提案："我想要添加 [在此处填写你的功能]。请为此功能创建一个 OpenSpec 变更提案" 3.了解 OpenSpec 工作流程："请根据 openspec/AGENTS.md 解释 OpenSpec 工作流程，并说明我应如何在此项目中与你协作"

针对老项目，在 claude code 中填写"请阅读 openspec/project.md 并帮助我填写项目详情、技术栈和约定规范"，最后就会得到更新后的 project.md

4、生成功能变更提案

把需求描述清晰：/openspec:proposal 需求描述

/openspec:proposal 添加 word转markdown的能力 ... ...

可以对生成内容检查确认，当然也是让 AI 去修改，这就相当于和开发人员来回确定需求。

openspec├── AGENTS.md├── changes│ ├── add-word-to-markdown│ │ ├── design.md│ │ ├── proposal.md│ │ ├── specs│ │ │ ├── document-converter│ │ │ │ └── spec.md│ │ │ └── word-to-markdown│ │ │ └── spec.md│ │ └── tasks.md│ └── archive├── project.md└── specs

5、代码开发执行

直接 /openspec:apply 就开始按提案讨论好的执行了