OpenSpec

最受欢迎的 spec 框架。

我们的理念：

→ 流动而非僵化
→ 迭代而非瀑布
→ 简单而非复杂
→ 面向已有代码库（brownfield）而非仅新建项目（greenfield）
→ 从个人项目到企业均可扩展

[!TIP] 全新工作流现已可用！ 我们用新的制品导向工作流重构了 OpenSpec。

运行 /opsx:propose "your idea" 开始。→ 此处了解更多

关注 @0xTab 在 X 上 获取更新 · 加入 OpenSpec Discord 获取帮助和提问。

实际效果

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

OpenSpec 仪表盘

快速开始

需要 Node.js 20.19.0 或更高版本。

全局安装 OpenSpec：

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

然后导航到你的项目目录并初始化：

cd your-project
openspec init

现在与你的 AI 对话：

• 还不确定要构建什么？ 从 /opsx:explore 开始，它是一个零风险的思考伙伴，读取你的代码，权衡选项，并在写任何代码之前形成计划。（探索指南）
• 已经明确目标？ 直接使用 /opsx:propose <你想构建的内容>。

两者都在默认配置中。如果你想要扩展工作流（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard），使用 openspec config profile 选择，然后运行 openspec update 应用。

[!NOTE] 不确定你的工具是否受支持？查看完整列表 – 我们支持 25+ 种工具且还在增长。

同样适用于 pnpm、yarn、bun 和 nix。查看安装选项。

文档

从这里开始： 文档首页 提供了全局地图。OpenSpec 新手？阅读入门指南，然后命令工作方式（你实际输入 /opsx:propose 的地方）。

→ 入门指南：第一步
→ 先探索：通过 /opsx:explore 深入思考再动手
→ 命令工作方式：斜杠命令与 CLI 的运行差异
→ 核心概念速览：整个思维模型，一页纸
→ 示例与配方：真实完整的变更过程
→ 工作流：组合与模式
→ 已有项目：在已有代码库上采用 OpenSpec
→ 编辑变更：更新制品、回退、协调手动编辑
→ 命令：斜杠命令与技能
→ CLI：终端参考
→ 存储：在单独仓库中规划，团队共享（beta）
→ 受支持的工具：工具集成与安装路径
→ 概念：整体架构
→ 多语言：多语言支持
→ 自定义：打造你的专属配置
→ FAQ · 故障排查 · 术语表：快速帮助

社区模式

第三方模式包通过独立仓库分发——这些提供有主见的工作流，将 OpenSpec 与其他工具集成，类似于 github/spec-kit 的社区扩展目录处理工具集成的方式。

→ 浏览目录，详见自定义文档。

为什么选择 OpenSpec？

AI 编程助手功能强大，但当需求仅存在于聊天历史中时，结果不可预测。OpenSpec 添加了一个轻量级的 spec（规格说明）层，让你在写任何代码之前就构建目标达成一致。

• 构建前先达成一致——人机在写代码前对齐规格
• 保持条理清晰——每个变更拥有独立文件夹，包含提案、规格、设计和任务
• 流动工作——任何制品随时可更新，没有僵化的阶段门
• 使用你的工具——通过斜杠命令与 20+ AI 助手协作

与其他方案对比

vs. Spec Kit（GitHub）——完整但沉重。僵化的阶段门，大量 Markdown，Python 配置。OpenSpec 更轻量，允许自由迭代。

vs. Kiro（AWS）——功能强大，但你被锁定在他们的 IDE 中，仅限 Claude 模型。OpenSpec 与你已有的工具配合。

vs. 不使用任何工具——没有规格的 AI 编程意味着模糊的提示和不可预测的结果。OpenSpec 在无需繁文缛节的前提下带来可预测性。

更新 OpenSpec

升级包

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

刷新 Agent 指令

在每个项目中运行以下命令，重新生成 AI 指导并确保最新的斜杠命令生效：

openspec update

使用说明

模型选择：OpenSpec 在推理能力强的模型上表现最佳。建议在规划与实现阶段使用 Codex 5.5 和 Opus 4.7。

上下文卫生：OpenSpec 受益于干净的上下文窗口。在开始实现前清除上下文，并在整个会话中保持良好的上下文卫生习惯。

贡献

小型修复——Bug 修复、拼写修正和小改进可以直接提交 PR。

较大变更——对于新功能、重大重构或架构更改，请首先提交 OpenSpec 变更提案，以便我们在实现开始前对齐意图和目标。

编写提案时，请牢记 OpenSpec 的理念：我们服务于不同编程 Agent、模型和使用场景的广泛用户。变更应该对所有人都友好。

欢迎 AI 生成的代码——只要经过测试和验证。包含 AI 生成代码的 PR 应注明使用的编码 Agent 和模型（例如："使用 Claude Code 生成，模型为 claude-opus-4-5-20251101"）。

开发

• 安装依赖：pnpm install
• 构建：pnpm run build
• 测试：pnpm test
• 本地开发 CLI：pnpm run dev 或 pnpm run dev:cli
• 约定式提交（单行）：type(scope): subject

其他

遥测

OpenSpec 会收集匿名使用统计数据。

我们只收集命令名称和版本信息，以了解使用模式。不收集参数、路径、内容或个人身份信息。在 CI 中自动禁用。

退出方式： export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1

维护者与顾问

详见 MAINTAINERS.md 中核心维护者与为项目提供指导的顾问列表。

许可证

MIT