openspec
OpenSpec 规范驱动开发助手 - 基于 OPSX 工作流的 AI 辅助编程框架。 在编写代码前与 AI 就需求达成一致,使用 Schema 驱动的工件依赖系统管理变更。 触发条件(满足任意一项即触发): 1. 用户提及 "openspec"、"opsx"、规范驱动开发、spec-driven 2. 用户想要开始新功能开发、重构或探索复杂需求 3. 用户抱怨 AI 理解偏差或频繁返工 4. 用户使用斜杠命令如 /opsx:new、/opsx:ff、/opsx:apply 等 5. 项目初始化或准备重大变更时 6. 需要生成 proposal、design、tasks 等规范文档时 推荐使用:改进现有项目(棕地开发)、需要高质量实现的关键功能、团队协作开发。 不推荐:快速原型验证(0→1 探索)、一次性小脚本、需求极度不明确的创新探索。
How do I install this agent skill?
npx skills add https://github.com/ruan-cat/monorepo --skill openspecIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a development framework for specification-driven programming. It uses a custom CLI tool ('openspec') and a set of markdown-based documents to manage development tasks. No malicious patterns, obfuscation, or unauthorized data access were detected. It primarily interacts with project files and local CLI commands to maintain code quality and specification consistency.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
OpenSpec 规范驱动开发助手
OpenSpec 是规范驱动的 AI 编程框架。核心理念:在编写代码前,与 AI 就需求达成一致。
- 流动而非僵化 - 随时处理任何工件,无阶段门控
- 迭代而非瀑布 - 边构建边完善理解
- 简单而非复杂 - 最小化设置和仪式
- 棕地优先 - Delta 方式修改现有系统
斜杠命令
| 命令 | 功能 |
|---|---|
/opsx:explore | 探索想法、调查问题、明确需求 |
/opsx:new | 启动新变更 |
/opsx:continue | 创建下一个就绪工件 |
/opsx:ff | 快进 - 一次创建所有规划工件 |
/opsx:apply | 实施任务,按需更新工件 |
/opsx:verify | 验证实现的完整性、正确性、一致性 |
/opsx:sync | 同步 delta specs 到主规范(可选) |
/opsx:archive | 归档完成的变更 |
/opsx:bulk-archive | 批量归档多个变更 |
/opsx:onboard | 交互式教程 |
工作流模式
快速功能流(需求明确时):
/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive
探索式流程(需求不明确时):
/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply
增量式流程(需要更多控制时):
/opsx:new → /opsx:continue (重复) → /opsx:apply → /opsx:archive
工件系统(默认 Schema: spec-driven)
工件依赖链:
proposal → specs → design → tasks → implement
工件类型:
- proposal.md - 变更提案(Why/What/Impact)
- specs/ - Delta 规范(ADDED/MODIFIED/REMOVED)→ 详见
references/delta-specs-format.md - design.md - 技术设计
- tasks.md - 任务清单(带复选框)→ 编写规范详见
references/tasks-writing-guide.md
工件状态:BLOCKED(缺少依赖)→ READY(依赖完成)→ DONE(文件存在)
目录结构
openspec/
├── config.yaml # 项目配置(可选)
├── specs/ # 当前系统行为(事实来源)
├── changes/ # 活跃变更
│ └── add-feature/
│ ├── .openspec.yaml
│ ├── proposal.md
│ ├── specs/
│ ├── design.md
│ └── tasks.md
├── archive/ # 已归档变更
└── schemas/ # 自定义工作流(可选)
tasks.md 核心要求
详细规范请读
references/tasks-writing-guide.md
两条最重要的原则:
- 文件级粒度:每个任务条目必须包含
[操作类型] 文件路径 - 具体改动描述,禁止写无法定位文件的模糊任务 - 试点分层:任务总数 ≥ 5 时,必须先划分「试点批次(Pilot Batch)」验证方向后,再推进「主体任务」
- 执行中动态补全:
/opsx:apply、/opsx:verify或人工复核发现任务遗漏时,先回写当前 change 的tasks.md,再继续实现或验收
格式速记:
- [ ] [修改] `packages/foo/src/bar.ts` - 增加 processItem() 方法,实现单条数据处理
执行中动态补全
当 /opsx:apply、/opsx:verify 或人工复核发现当前 change 存在任务遗漏时,必须先把遗漏项写回 openspec/changes/<change>/tasks.md,再继续实现或验收。tasks.md 是唯一可执行任务源,不得只把遗漏写在聊天 checklist、进度报告或子代理反馈里。
补全任务必须保持 OpenSpec checkbox 格式:
- [ ] [操作类型] 路径 - 具体动作与验收标准
发现缺口但未写回 tasks.md 时,不得声明相关实现、验收或 change 已完成。任务补全后必须运行:
openspec validate <change-name> --strict
更新与迭代决策
相同意图? → YES: 更新现有变更 / NO: 启动新变更
>50% 重叠? → YES: 更新现有变更 / NO: 启动新变更
原始能完成?→ NO: 更新现有变更 / YES: 启动新变更
验证
/opsx:verify 检查三个维度:
- Completeness - 所有任务完成,需求已实现
- Correctness - 匹配规范意图,处理边界情况
- Coherence - 设计决策反映在代码中
执行长任务的注意事项
- 文件级粒度执行 - 每次只修改一个文件,立即标记完成
- 先试点再推进 - 先完成「试点批次」,验证通过后继续「主体任务」
- 及时更新任务文件 - 完成任务后立即更新
tasks.md的复选框;发现遗漏任务时先补写tasks.md并 strict validate - 并行子代理 - 启动多个子代理分模块完成任务
- 中文回复 - 始终用中文回复用户
- 重读任务要求 - 上下文合并后重新阅读规范
- 连续执行 - 一次性完成
tasks.md全部任务 - 禁止批处理脚本 - 使用具体的文件编辑,不用脚本批量修改
- 主从代理调度:主代理阅读全部任务、分配子代理、监听反馈;子代理严格按要求完成任务
常用 CLI 命令
openspec init # 初始化项目
openspec list # 列出活跃变更
openspec status --change <name> # 查看工件状态
openspec validate <name> --strict # 严格格式校验
openspec archive <name> --yes # 归档变更
配置、自定义 Schema、故障排除详见
references/configuration.md
参考文件
| 文件 | 内容 |
|---|---|
references/tasks-writing-guide.md | tasks.md 编写规范(文件级粒度 + 试点分层详解) |
references/delta-specs-format.md | Delta Specs 完整格式规范 |
references/configuration.md | config.yaml 配置、自定义 Schema、故障排除 |
外部参考资源
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ruan-cat/monorepo/openspec">View openspec on skillZs</a>