openspec-agents

openspec-agents

openspec-agents 是 [OpenSpec](https://openspec.sh) 的配套插件，兼容 Claude Code / Codex / ZCode / DeepSeek Harness / OpenCode：提案阶段把标准钉得更死（澄清在前、改动范围与契约变更逐条确认），实施阶段写与审查分离——实现由一个 Agent 写，审查由另一个 Agent 独立判定；完整模式下检查、验收、质量审查再拆给不同角色，按生产级标准把控到收口。

前提：项目正在使用 OpenSpec 管理需求。

| | |

|---|---|

| 适合 | 变更需要真正落进代码库、有验收标准、需通过检查、过程可追溯的团队与项目 |

| 不适合 | 希望快速产出 demo、不走检查与验收的场景 |

| 代价 | 比单个 AI 直接修改更慢，Token 消耗更高 |

| 模型选型 | 实施用 flash 类模型，提案用旗舰模型 |

常见痛点

• AI 一次改一大片，改完声称「完成了」——能编译、测试也通过，但其中夹带的空实现与伪成功未被发现。
• 共用逻辑被改动后，其他调用入口仍在使用旧写法，无人察觉。
• 出了问题想复盘，只能翻到大量对话记录，看不出当时按什么标准放行。

与工具自带工作流的区别

Claude Code 和 DeepSeek Harness 自带的工作流能力擅长并行完成大量独立任务。这个插件解决的是另一件事，两者可以叠加使用。

| | 工具自带的工作流 | 本插件 |

|---|---|---|

| 擅长 | 并行完成大量独立任务 | 单个变更按阶段推进，逐层把关 |

| 如何放行 | 由脚本中的判断决定 | 由程序强制：检查未完成、问题未闭环时无法以「通过」提交 |

| 跨工具 | 各家私有 | 同一套流程跨工具通用 |

| 中断之后 | 进度依附于对话或单次运行 | 进度记录在仓库中，换会话、换工具均可继续 |

一句话：原生工作流负责把任务做完，这个插件负责判定产出是否达到生产级。

局限

使用前请先确认以下三条边界。

存量项目需要一次收敛成本。 判据按理想状态定义（方法不超过 50 行、类职责单一、核心域不依赖框架、构建产物需忽略、覆盖率需达标），且工具检查覆盖全量代码——存量违规同样按原级别上报并阻塞。存量项目首次运行会暴露大量存量问题，只能逐个修复，或逐个走豁免裁定；裁定通过的会沉淀进项目级清单，后续变更不再重复阻塞。

技术栈配套需覆盖到你的栈。 通用规范 skill 与技术栈无关；内置的 Java 后端与前端（Vue / React）配套在此之上补齐具体构建与检查命令（构建工具、格式、静态分析、覆盖率、质量扫描平台接入）。其他技术栈项目审查照常执行，但编译、格式、静态分析、覆盖率、端到端这几项确定性检查没有现成命令，需补一份技术栈 skill（在 frontmatter 声明 stacks / frameworks 即可被识别并加载），否则只能按降级申报跳过。

架构规范只有 DDD 一套。 包组织有两种等价的合法风格——四层分层（domain / application / infrastructure / interfaces）与六边形（内核 + 入站 / 出站适配器），采用哪种由项目声明，未声明时按四层认定。不按 DDD 组织的项目（例如 MVC + Service + DAO 直写）没有对应规范，会被判定为偏离规范并报出问题；项目已有自己的架构规范时以项目规范为准，但该规范需自行写入。

快速开始

项目还没用 OpenSpec 的话，先装 CLI（初始化由插件代做）：

npm install -g @fission-ai/openspec

在项目里调用 /openspec-standard 时，项目还没有 openspec/ 就会先以 Core Profile 初始化，项目根随即出现 openspec/ 目录。

第一步：安装

按你用的工具选一种，装完重启该工具。

Claude Code

claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
claude plugin install openspec-agents@ifrankwang

Codex

codex plugin marketplace add https://github.com/ifrankwang/codex-plugins
codex plugin add openspec-agents@ifrankwang

ZCode

打开 ZCode 插件页，添加市场 ifrankwang/zcode-plugins，然后安装 openspec-agents。

DeepSeek Harness（DSH）

dsh plugin --profile web add @ifrankwang/openspec-agents

web 是 profile 名，换成你自己的（~/.dsh/profiles/ 下的目录名）。装完重启该 profile；作用项目随当前会话所属项目自动确定，同一个 profile 下切换项目不必重装或改配置。编排工具需要在一个项目会话里使用。

要求 DSH 0.2.1 及以上。子代理的角色提示词与工具集由 Agent Preset 承载，profile 需包含 web 应用 bundle（desktop / web 模板都满足）。子代理委派为异步：分派返回后本轮即结束，收到完成通知再继续下一步。

OpenCode

要求 OpenCode 2.x（1.x 的插件接口不兼容）。

npm install -D @ifrankwang/openspec-agents

然后在 OpenCode 配置的 plugins 中登记 @ifrankwang/openspec-agents：

// opencode.json
{