TypeScript OpenSpec 规范驱动让AI先规划再写代码

AI 编程助手很强大，但当需求只存在于聊天记录里时，结果常常不可预测。你让助手加个功能，它可能直接改代码，却没和你确认到底要做什么、边界在哪里。OpenSpec 给这类协作加了一层轻量规范：在写任何代码之前，人和 AI 先就规格（spec）达成一致。它不是一个笨重的流程工具，而是一套可以随项目生长、随时修改的 Markdown 规范文件。

项目基本信息

一、项目介绍

OpenSpec 是一个规范框架（spec framework），核心思路是把功能需求写成人类和 AI 都能读的 Markdown 规格文件。每个变更（change）拥有独立文件夹，里面包含提案（proposal）、规格（specs）、设计（design）和任务清单（tasks）。AI 在写代码前先产出这些文件，你 review 通过后再动手实现。它支持 30 多个主流 AI 编程工具，包括 Cursor、GitHub Copilot、Claude Code、Codex、Amazon Q 等，通过斜杠命令触发，例如 /opsx:explore 用于无负担地探讨想法，/opsx:propose 用于直接提出变更方案。

二、核心优势

第一，先对齐再构建。需求在规格里写清楚，避免模糊提示带来的不可预测结果。第二，组织清晰。每个变更独立成文件夹，提案、规格、设计、任务各司其职。第三，流动式迭代。任何产物都能随时修改，没有僵化的阶段门禁。第四，工具无关。无论你用哪个 AI 助手，OpenSpec 都能通过对应的斜杠命令集成。第五，团队可共享。通过 Stores 功能，可以把规格放在独立仓库里用 git 同步，跨多个代码仓库保持单一事实来源。

三、适用场景

个人开发者可以用它约束 AI 助手，让每次改动都有据可查。团队场景中，一个功能可能横跨 API 服务、Web 应用和共享库，OpenSpec 的 Stores 让平台团队拥有规格、产品团队只读引用，避免 wiki 漂移。它也适合绿地和棕地项目——无论是从零开始还是改造老代码库，都能平滑接入。

四、安装教程

OpenSpec 是单文件二进制，macOS 和 Linux 可直接用脚本安装：

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

Windows 用 PowerShell：

irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

如果习惯包管理器，也可以全局安装 npm 包（需要 Node.js 20.19.0 以上）：

npm install -g @fission-ai/openspec@latest

或者 macOS 用 Homebrew：brew install openspec。装好后进入项目目录执行 openspec init 完成初始化。常见报错多来自 Node 版本过低，Alpine Linux 首次运行还需先装 apk add libstdc++ libgcc。

五、使用示例

进入项目目录并初始化：

cd your-project
openspec init

当你还不确定要做什么时，先和 AI 探讨：

/opsx:explore

AI 会读取你的代码、权衡方案并 shaping 出计划。确认方向后提出变更：

/opsx:propose add-dark-mode

AI 会创建 openspec/changes/add-dark-mode/ 目录，生成 proposal.md、specs/、design.md 和 tasks.md，等待你确认后再执行 /opsx:apply 实现，最后用 /opsx:archive 归档，规格随之更新。

六、常见问题

问：OpenSpec 和 GitHub Spec Kit 有什么区别？答：Spec Kit 更详尽但偏重，有僵化的阶段门禁和大量 Markdown、需要 Python 环境；OpenSpec 更轻，迭代自由。问：和 AWS Kiro 比呢？答：Kiro 绑定自家 IDE 且限 Claude 模型，OpenSpec 不绑定工具。问：不想上报使用数据怎么办？执行 openspec config set telemetry.enabled false 或设置环境变量 OPENSPEC_TELEMETRY=0。问：升级后斜杠命令没更新？在 project 里执行 openspec update 重新生成 AI 指引。

七、总结

OpenSpec 解决的是 AI 编程说得清但做不准的痛点。它用一层轻量、可读、可共享的规范，把先想清楚再写代码变成默认工作流，而不是靠运气。对于希望让 AI 助手真正可控、可审计的个人和团队，它值得一试。