开源项目 GitHub Trending 2026-09-18T12:01 正文 ok 1211 words

OpenSpec：面向 AI 编程助手的规格驱动开发框架

英文标题：🔥 Fission-AI/OpenSpec

OpenSpec 是 Fission-AI 推出的开源规格驱动开发（SDD）框架，旨在让开发者在 AI 编程助手开始写代码前，先以 Markdown 规格对需求、设计和任务达成一致。该项目提供 `/opsx:explore`、`/opsx:propose`、`/opsx:apply` 和 `/opsx:archive` 等工作流，并支持 30 多种 AI 助手及工具集成。OpenSpec 要求 Node.js 20.19.0 或更高版本，可通过 npm 全局安装；其 Stores 功能目前处于 beta 阶段，用于跨仓库共享规划和规格。对开发团队而言，它试图以轻量、可迭代的规格层降低 AI 编程中需求仅存在于聊天记录、结果不可预测的问题。

打开原文相关 3 · 机会 2

34.2 KB

2.2 KB

553 B

2.4 KB

751 B

588 B

566 B

450.3 KB

53.8 KB

中文

最受喜爱的规格框架。

我们的理念：

→ 灵活而非僵化
→ 迭代而非瀑布式
→ 简单而非复杂
→ 不仅为绿地项目打造，也为棕地项目而生
→ 可从个人项目扩展至企业级应用

提示

现已提供新工作流！ 我们已利用全新的工件引导式工作流重构 OpenSpec。

运行 /opsx:propose "你的想法" 即可开始。→ 在这里了解更多

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

你：/opsx:explore
AI：你想探索什么？
你：我想要深色模式，但不确定如何以干净的方式实现。
AI：让我看看你的样式设置……
     这里最简洁的路径是：CSS 变量 + 一个小型主题上下文，
     并配合系统偏好检测。不需要新增依赖。要确定范围吗？
你：好的，就这么做。

你：/opsx:propose add-dark-mode
AI：已创建 openspec/changes/add-dark-mode/
     ✓ proposal.md — 我们为什么要做、会改变什么
     ✓ specs/       — 需求与场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实施检查清单
     已准备好实施！

你：/opsx:apply
AI：正在执行任务……
     ✓ 1.1 添加主题上下文提供程序
     ✓ 1.2 创建切换组件
     ✓ 2.1 添加 CSS 变量
     ✓ 2.2 接入 localStorage
     所有任务均已完成！

你：/opsx:archive
AI：已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/
     规格已更新。可以开始下一个功能了。

这些规格实际是什么样子？

纯 Markdown——包含具体场景的需求，无需学习特殊语法。以下内容会被写入上面创建的 specs/ 文件夹：

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

这些内容由你的 AI 编写；在开始写任何代码之前，由你审查方案。

OpenSpec 由 OpenSpec 构建——浏览此仓库实际运行中的规格和正在推进的变更，查看大规模应用下的真实示例。

OpenSpec Dashboard

对于个人开发者，OpenSpec 能让你和 AI 在单个仓库中保持一致。对于团队而言，难点随之转移：一个功能横跨 API 服务器、Web 应用和共享库；需求由一个团队负责、供其他团队使用；规划在任何代码存在之前就已开始。

Stores 是答案——在独立仓库中进行规划。它采用你已经熟悉的同一套 openspec/ 结构（specs 和 changes），与其他内容一样通过 git push 共享。整个团队和每个编程 Agent 都可以跨所有仓库读取的单一事实来源。

跨仓库功能 —— 一个变更、一份计划，即使代码最终落在三个仓库中。
共享需求 —— 平台团队拥有规格；产品团队以只读方式引用这些规格，且位置就在其编程 Agent 可读取之处。不再有逐渐偏离实际的 wiki。
代码之前先规划 —— 现在就在 Store 中记录计划；代码仓库之后再跟进。

Stores 处于 beta 阶段。请从 Stores 用户指南开始。

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

全局安装 OpenSpec：

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

然后进入项目目录并初始化：

cd your-project
openspec init

想让 AI 来完成吗？ 将设置提示词粘贴到你的编程助手中——它会安装 CLI、运行 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 应用。

/opsx:propose 是规范名称；你的工具可能将其写作 /opsx-propose（Cursor、GitHub Copilot）、@opsx-propose（Amazon Q）或 $openspec-propose（Codex）。openspec init 会针对你选择的工具输出正确形式——参见如何调用。

从这里开始： 文档首页 汇总了全部内容。初次使用 OpenSpec？请阅读入门指南，然后阅读命令工作原理（即你实际输入 /opsx:propose 的位置）。

→ 入门指南：第一步
→ 先探索：在确认之前，先通过 /opsx:explore 想清楚
→ 命令工作原理：斜杠命令与 CLI 分别在哪里运行
→ 核心概念速览：一页掌握完整心智模型
→ 示例与配方：从头到尾的真实变更
→ 工作流：组合与模式
→ 现有项目：在棕地代码库中采用 OpenSpec
→ 编辑变更：更新工件、回退与协调手动编辑
→ 命令：斜杠命令与技能
→ CLI：终端参考
→ Stores：在独立仓库中规划，并在团队中共享（beta）
→ 支持的工具：工具集成与安装路径
→ 概念：各部分如何协同工作
→ 多语言：多语言支持
→ 自定义：打造适合你的 OpenSpec
→ 社区展示：使用 OpenSpec 及为 OpenSpec 构建的项目与资源
→ FAQ · 故障排除 · 术语表：快速帮助

社区 Schema

通过独立仓库分发的第三方 Schema 套件——它们提供具有明确观点的工作流，将 OpenSpec 与其他工具集成，类似于 github/spec-kit 的社区扩展目录处理工具集成的方式。

→ 在自定义文档中**浏览目录**。

当需求只存在于聊天记录中时，AI 编程助手虽然强大，却难以预测。OpenSpec 添加了一个轻量级规格层，让你在开始编写任何代码之前，就先对要构建的内容达成一致。

构建前达成一致 —— 人类与 AI 在代码编写前对规格达成共识
保持有序 —— 每项变更都有自己的文件夹，包含提案、规格、设计和任务
流畅协作 —— 可随时更新任何工件，不设僵化的阶段门槛
使用现有工具 —— 通过斜杠命令支持 30 多种 AI 助手

对比 Spec Kit（GitHub）—— 完整但偏重。具有严格的阶段门槛、较多 Markdown 和 Python 设置。OpenSpec 更轻量，并允许自由迭代。

对比 Kiro（AWS）—— 功能强大，但你会被锁定在其 IDE 中，并且仅限使用 Claude 模型。OpenSpec 可与现有工具配合使用。

对比什么都不用 —— 没有规格的 AI 编程意味着模糊提示词和不可预测的结果。OpenSpec 在避免繁琐流程的同时带来可预测性。

升级软件包

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

刷新 Agent 指令

请在每个项目中运行此操作，以重新生成 AI 指引，并确保最新的斜杠命令已启用：

模型选择：OpenSpec 最适合高推理能力模型。我们建议在规划和实施阶段均使用 Codex 5.5 和 Opus 4.7。

上下文卫生：OpenSpec 可从干净的上下文窗口中受益。开始实施前请清理上下文，并在整个会话中保持良好的上下文卫生。

在提交 PR 前，请先针对核心设计变更发起讨论，或创建 issue，并在 PR 中关联对应的 issue 或讨论。新功能、重要重构和架构变更必须先有 OpenSpec 变更提案。

→ CONTRIBUTING.md：从第一个 issue 到 PR 合并的完整流程

遥测

OpenSpec 会收集匿名使用统计信息。

我们仅收集命令名称和版本号，以了解使用模式。不收集参数、路径、内容或 PII。在 CI 中会自动禁用。

退出收集（满足任一项即可）：

openspec config set telemetry.enabled false（全局配置；未设置即表示启用）
export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1（环境变量优先于配置）

维护者与顾问

请参阅 MAINTAINERS.md，查看帮助指导该项目的核心维护者与顾问名单。

MIT

English / 原文

The most loved spec framework.

Our philosophy:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

Tip

New workflow now available! We've rebuilt OpenSpec with a new artifact-guided workflow.

Run /opsx:propose "your idea" to get started. → Learn more here

Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.

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.

What do the specs actually look like?

Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the specs/ folder created above:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Your AI writes these; you review the plan before any code is written.

OpenSpec is built with OpenSpec — browse this repo's live specs and in-flight changes for real examples at scale.

OpenSpec Dashboard

Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.

Stores are the answer — planning in a repo of its own. The same openspec/ shape you already know (specs and changes), shared by git push like anything else. One source of truth your whole team and every coding agent can read, across every repo.

Cross-repo features — one change, one plan, even when the code lands in three repos.
Shared requirements — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
Plan before code — capture the plan in the store now; the code repos catch up later.

Stores are in beta. Start with the Stores User Guide.

Requires Node.js 20.19.0 or higher.

Install OpenSpec globally:

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

Then navigate to your project directory and initialize:

cd your-project
openspec init

Want your AI to do it? Paste the setup prompt into your coding assistant — it installs the CLI, runs openspec init, and verifies the result.

Now talk to your AI:

Not sure what to build yet? Start with /opsx:explore, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. (Explore guide)
Already know what you want? Go straight to /opsx:propose <what-you-want-to-build>.

Both are in the default profile. If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.

/opsx:propose is the canonical name; your tool may spell it /opsx-propose (Cursor, GitHub Copilot), @opsx-propose (Amazon Q) or $openspec-propose (Codex). openspec init prints the right form for the tools you picked — see How To Invoke.

Start here: the Documentation Home maps everything. New to OpenSpec? Read Getting Started, then How Commands Work (where you actually type /opsx:propose).

→ Getting Started : first steps
→ Explore First : think it through with /opsx:explore before you commit
→ How Commands Work : where slash commands run vs the CLI
→ Core Concepts at a Glance : the whole mental model, one page
→ Examples& Recipes: real changes, start to finish
→ Workflows : combos and patterns
→ Existing Projects : adopt OpenSpec on a brownfield codebase
→ Editing a Change : update artifacts, go back, reconcile manual edits
→ Commands : slash commands & skills
→ CLI : terminal reference
→ Stores : plan in a separate repo, shared across your team (beta)
→ Supported Tools : tool integrations & install paths
→ Concepts : how it all fits
→ Multi-Language : multi-language support
→ Customization : make it yours
→ Community Showcase : projects and resources built with and for OpenSpec
→ FAQ · Troubleshooting · Glossary : quick help

Community schemas

Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how github/spec-kit's community extension catalog handles tool integrations.

→ Browse the catalog in the customization docs.

AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.

Agree before you build — human and AI align on specs before code gets written
Stay organized — each change gets its own folder with proposal, specs, design, and tasks
Work fluidly — update any artifact anytime, no rigid phase gates
Use your tools — works with 30+ AI assistants via slash commands

vs.Spec Kit (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.

vs.Kiro (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.

vs. nothing — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.

Upgrade the package

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

Refresh agent instructions

Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:

Model selection : OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.

Context hygiene : OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.

Open a discussion (for core design changes) or an issue before you open a PR, and link the issue or discussion from the PR. New features, significant refactors, and architectural changes need an OpenSpec change proposal first.

→ CONTRIBUTING.md : the full process, from first issue to merged PR

Telemetry

OpenSpec collects anonymous usage stats.

We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.

Opt-out (any one is enough):

openspec config set telemetry.enabled false (global config; unset means on)
export OPENSPEC_TELEMETRY=0 or export DO_NOT_TRACK=1 (env overrides config)

Maintainers & Advisors

See MAINTAINERS.md for the list of core maintainers and advisors who help guide the project.

MIT