拥抱AI编程，用中文进行规范驱动开发：OpenSpec汉化版正式发布
在 AI 辅助编程日益普及的今天，许多开发者都遇到过这样的困境：当你让 AI 开发一个复杂功能时，最初的几轮对话还很顺利，但随着代码量的增加，AI 开始“忘记”之前的约定，生成的代码偏离了最初的设计，甚至出现逻辑前后矛盾的“幻觉”。
这并非 AI 不够聪明，而是因为上下文（Context）的丢失和意图的模糊。
为了解决这个问题，GitHub 上知名的 Spec 驱动开发框架 OpenSpec 应运而生。今天，我非常高兴地宣布 OpenSpec 中文版（OpenSpec-cn） 正式发布！它不仅完全保留了原版的精髓，更针对中文开发者的习惯进行了彻底的汉化，让 Spec 驱动开发（SDD）变得触手可及。
什么是 Spec 驱动开发（SDD）？
传统的开发模式往往是“需求 -> 代码”，中间缺乏一个确定的、可验证的契约。而在 Spec 驱动开发（Spec-Driven Development）中，我们将流程变为“需求 -> 规范（Spec）-> 代码”。
在这个流程中，Spec 是“真实来源（Single Source of Truth）”。
它不再是躺在 Wiki 里过时的文档，而是存储在代码仓库中、结构化的、甚至可以直接被 AI 读取和执行的“代码的一部分”。在使用 AI 编程时，SDD 的优势尤为明显：
- 锁定意图：在写下一行代码前，你和 AI 先对“要做什么”达成共识（Proposal）。
- 减少幻觉：AI 不再需要从冗长的聊天记录中猜你的意图，而是直接依据明确的 Spec 进行编码。
- 可维护性：几个月后，当你（或你的同事）再看这段代码，Spec 清楚地告诉你当初为什么这么写，以及它的预期行为是什么。
OpenSpec：让 SDD 落地
OpenSpec 是一个轻量级的框架，它通过一套标准的文件结构和工作流，让 SDD 变得简单易行。它主要包含两个核心概念：
- Specs (
openspec/specs/)：当前系统的真实状态。这里存放着系统现有的功能规范。 - Changes (
openspec/changes/)：对未来的提案。当你想要修改系统时，你不是直接改代码，而是先创建一个 Change Proposal（变更提案）。
工作流：从提案到归档
OpenSpec 强制执行一个严谨的“三步走”流程：
- 起草（Draft）：创建一个新的 Change 文件夹（例如
openspec/changes/add-login），在里面写下proposal.md（为什么改、改什么）和tasks.md（怎么改），以及该变更涉及到的 Spec 增量（openspec/changes/add-login/specs/**/spec.md）。 - 实施（Implement）：AI 根据通过审核的 Proposal 和 Spec 增量（Delta）来编写代码，并按
tasks.md的清单逐项完成。 - 归档（Archive）：功能上线后，将 Change 归档。此时，Change 中的 Spec 增量会被合并到主 Specs 中，成为新的“真实来源”，历史提案则被移入
openspec/changes/archive/。
为什么需要 OpenSpec 中文版？
虽然原版 OpenSpec 非常强大，但对于中文开发者来说，全英文的指令、模板和反馈信息无疑增加了认知负担。特别是在定义复杂的业务逻辑时，使用母语能更精准地描述需求，减少歧义。
OpenSpec-cn (OpenSpec 中文版) 做了以下彻底的本地化工作：
- 全中文 CLI：从
openspec-cn init到报错信息，全部中文化，交互更友好。 - 中文模板：生成的
AGENTS.md（给 AI 看的说明书）和project.md、proposal.md模板全部汉化，AI 会用中文与你交互。 - 中文关键词：支持
## 新增需求、## 修改需求、#### 场景：等中文 Markdown 标记，写文档就像写中文博客一样自然。 - 完全兼容原版：目录结构和规范格式与英文版 OpenSpec 一致，可以在同一个团队里混用英文版和中文版 CLI。
快速上手指南（含 CodeBuddy Code 实战示例）
1. 安装与初始化
首先，通过 npm 全局安装 OpenSpec 中文版：
npm install -g @studyzy/openspec-cn
然后，在你的项目根目录下初始化：
cd my-project
openspec-cn init
初始化过程中，CLI 会询问你正在使用的 AI 助手（如 CodeBuddy Code、Cursor、Claude Code、VS Code 等），并自动为你：
- 在项目根目录生成
openspec/目录结构：openspec/project.md：项目级约定与背景openspec/specs/：当前真实的功能规范openspec/changes/：新的变更提案
- 生成面向 AI 的说明文件
openspec/AGENTS.md - 为支持的工具安装或更新 OpenSpec 相关的斜杠命令（例如 CodeBuddy Code 中的
/openspec:proposal、/openspec:apply、/openspec:archive）
初始化完成后，建议先跑几条命令熟悉当前状态：
# 查看当前有哪些活跃变更
openspec-cn list
# 查看当前已经存在的规范能力
openspec-cn spec list --long
# 打开交互式仪表盘（终端 UI）
openspec-cn view
如果你是第一次在项目里使用 OpenSpec-cn，可以先打开 openspec/project.md，补充项目说明、技术栈和约定，然后在 AI 助手里给 CodeBuddy Code 发送这样的指令：
“请阅读 openspec/project.md 和 openspec/AGENTS.md，并帮我总结这个项目的上下文和规范驱动开发流程。”
2. 在 CodeBuddy Code 中创建你的第一个变更
假设我们要给项目添加一个“用户登录”功能，并希望整个过程都由 Spec 驱动。下面以 CodeBuddy Code 为例：
2.1 使用 /openspec:proposal 搭建变更骨架
-
在 CodeBuddy Code 的命令行对话中输入：
/openspec:proposal 添加用户登录功能 -
CodeBuddy Code 会调用 OpenSpec-cn，在
openspec/changes/下生成一个新的变更目录（例如add-user-login）：openspec/changes/add-user-login/ ├── proposal.md ├── tasks.md └── specs/ └── auth/ └── spec.md其中：
proposal.md：描述“为什么要改”和“打算改什么”；tasks.md：列出实现步骤清单（后端、前端、测试等）；specs/auth/spec.md：描述这次变更对认证能力（auth）的增量规范。
-
你可以在编辑器里打开
openspec/changes/add-user-login/specs/auth/spec.md，看到类似这样的内容（全中文结构）：## 新增需求 ### 需求：用户登录 系统应允许用户使用账号密码登录。 #### 场景：登录成功 - **当** 用户输入正确的用户名和密码 - **则** 系统返回 JWT Token - **且** 跳转至首页 -
回到 CodeBuddy Code，对 AI 说：
“请根据 openspec/changes/add-user-login 下的 proposal.md、tasks.md 和 specs/auth/spec.md，帮我补充更完整的验收场景和边界条件，再更新这些文件。”
这一步会让 Spec 更加细致、可测，避免后期实现阶段出现“补需求”的情况。
2.2 使用 /openspec:apply 驱动实现
当 Proposal 和 Spec 增量已经打磨到比较稳定的版本时，就可以进入实现阶段：
-
在 CodeBuddy Code 里输入：
/openspec:apply add-user-login -
CodeBuddy Code 会根据
openspec/changes/add-user-login/下的proposal.md、tasks.md和增量 Spec：- 逐条读取
tasks.md中的任务； - 在代码库中实施相应修改（后端接口、前端页面、测试用例等）；
- 实现完成后，将对应的任务从
- [ ]勾选为- [x]，确保任务清单与实际代码状态一致。
- 逐条读取
你可以随时插话，例如：
“在实现第 2.2 条任务前，请先向我解释你打算修改哪些文件，以及对应的测试策略。”
这样可以在保持自动化效率的前提下，保留必要的人类审查和控制。
2.3 使用 /openspec:archive 归档变更
当 tasks.md 中的所有任务都已经完成、测试通过，并且相关代码已经合并 / 上线后，就可以通过 CodeBuddy Code 触发归档：
/openspec:archive add-user-login
此时 AI 会调用底层的 OpenSpec-cn CLI，将该变更归档，一般等价于在本地执行：
openspec-cn archive add-user-login --yes
归档完成后：
openspec/changes/add-user-login/会被移动到openspec/changes/archive/YYYY-MM-DD-add-user-login/；- 增量规范会被合并进
openspec/specs/**/spec.md中，成为新的真实规范； - 之后如果你再让 CodeBuddy Code 理解当前的认证规则，只需要让它阅读
openspec/specs/auth/spec.md即可。
3. 验证、实现与任务跟踪（CLI 视角）
除了通过斜杠命令驱动 CodeBuddy Code，你也可以直接使用 CLI 命令，从工程视角掌控整个生命周期。
在开始写代码前，先用 CLI 严格校验一次变更：
# 只校验这个变更
openspec-cn validate add-user-login --strict
# 或者一次校验所有变更
openspec-cn validate --strict
如果存在格式问题（例如某个“需求”下面没有任何“场景”），OpenSpec-cn 会用中文错误信息提示，并指向具体文件，方便修正。
实现过程中，可以用下面的命令查看进度和内容：
# 查看某个变更的详情（包含 proposal、tasks 和 spec 增量）
openspec-cn show add-user-login
# 只看增量规范，方便 Code Review 或脚本处理
openspec-cn show add-user-login --json --deltas-only
你也可以把 openspec-cn validate --strict 加入到 CI 流水线中，强制所有 PR 在合并前通过 Spec 校验，这样可以避免“规范文件和变更文件不同步”的情况。
4. 归档与让 Spec 成为“真实来源”（CLI 视角）
如果你更偏向手动控制归档时机，也可以直接在本地执行：
openspec-cn archive add-user-login --yes
归档时会发生几件事：
openspec/changes/add-user-login/被移动到openspec/changes/archive/YYYY-MM-DD-add-user-login/；- 该变更中的增量规范被合并进对应的
openspec/specs/**/spec.md中，成为系统当前的“真实规范”； - 此后，如果你再让 CodeBuddy Code 查看当前认证规范，只需要让它读取
openspec/specs/auth/spec.md即可，不再依赖过往的聊天记录。
如果你只是做了一次工具层面的调整（例如只修改了提示词，而没有真正修改业务行为），可以使用：
openspec-cn archive some-tooling-change --skip-specs --yes
这样就不会动到已有 Specs，只归档变更记录。
结语
AI 编程不仅仅是让 AI 写代码，更是关于如何更高效地与 AI 协作。OpenSpec 中文版通过结构化的文档和母语化的交互，为您和包括 CodeBuddy Code 在内的各类 AI 编程助手之间，搭建了一座清晰、可审计、可演化的桥梁。
拒绝模糊，拒绝幻觉，让每一次代码提交都掷地有声。
欢迎大家试用 OpenSpec-cn，如果您有任何建议或反馈，欢迎在 GitHub 上提交 Issue！
- GitHub: https://github.com/studyzy/OpenSpec-cn
- NPM:
@studyzy/openspec-cn
浙公网安备 33010602011771号
