OPEN SOURCE · MIT LICENSE · v0.2.20+

AI 写代码，
团队审计每一次变更。

8 阶段门禁 · 子Agent 对抗验证 · PreToolUse 钩子 · 多工具共存 · Route 分级。给 Claude Code、OpenCode、Cursor 与 Codex 装上同一套规范、审计与交付流程。

本地运行无 API KeyNode.js 20+多工具共存PreToolUse 钩子

~/workspace/todo-app LIVE PIPELINE · 07 / 07

$npx opsx-dev-pipeline init --tool claude --stack backend --yes

Pipeline complete · 2 blocked · 2 fixed · 0 bypassed

WHYWHATHOWREVIEWSHIP

OpenSpecClaude CodeOpenCodeCursorCodexReactSpring BootFastAPINode.js 20+TypeScriptPython 3.10+Java 17+OpenSpecClaude CodeOpenCodeCursorCodexReactSpring BootFastAPINode.js 20+TypeScriptPython 3.10+Java 17+

01 / THE PROBLEM

AI Agent 越来越自主，
但你管不了它每一步怎么决策。

速度前所未有的快，问题也跟着前所未有的多：决策链断裂、敏感文件漏网、规则形同虚设……下面八条是团队最常踩到的坑。

Agent 自主失控

Agent 自己写代码、调试、部署，决策速度远超人类 review 能力。

交互黑箱

Agent 之间的交互你根本看不到，不知道它们做了什么决定。

Review 变成猜测

变更没有 proposal，reviewer 只能从代码 diff 猜意图。

决策链断裂

三个月前的变更没有一条完整记录，为什么这样写没人知道。

敏感文件漏网

Agent 把 .env 提交了，安全扫描没拦住，规则对 Agent 不起作用。

规则形同虚设

"下次设个规则"→ 下次换了个 Agent，规则没用上。口头约定无法规模化。

工具碎片化

团队一半人用 Claude Code、一半用 Cursor，脚本、门禁、命名约定全部割裂。

危险命令被默许

Agent 顺手 rm -rf、push --force、chmod 777——prompt 写了也拦不住。

AI AGENT 失控快，但不可控

OPSX PIPELINE速度可以被验证

02 / HOW IT WORKS

8 个阶段，一条流水线。
从一句需求到可信交付。

每一步都有状态记录，每个关键节点都由你确认。中断后从断点恢复，不是从头开始。

PHASE 0 / Preflight

预检

确认 OpenSpec、Git、Manifest 与 Route 选择均可用。

状态写入完成，允许进入下一阶段

pipeline / add-todo-due-date

$ node preflight.mjs --json

passopenspec 1.7+

passgit repository clean

doneroute: standard

›

03 / CORE POWER

统一团队的标准，
追溯每一次变更的完整身份。

可持久化状态机把团队规范变成每次变更都必须经过的工程事实。创建者、机器指纹、需求关联、阶段耗时——完整身份链永久可追溯。

pipeline-state.jsonSaved

{
  "phase": 4,
  "gate": "tests",
  "status": "passed",
  "tools": ["claude", "opencode"]
}

门禁校验

测试未通过，状态机拒绝进入归档。

状态持久化

流程中断后，精确回到上一个决策点。

原子写入

临时文件加 rename，崩溃不留下半份状态。

重试上限

三轮仍未通过则暂停，主动呼叫人工介入。

决策审计

跳过、合并策略与关键确认永久可追溯。

事实校验

恢复时交叉核对 Git、文件系统与 OpenSpec。

身份追溯

git config + 机器指纹 + 时间戳 —— 完整身份链。

阶段耗时

每个 Phase 的开始/结束时间精确记录，定位瓶颈。

需求关联

关联 JIRA/外部需求 ID，代码变更有业务上下文。

010

混合执行

独立命令与 pipeline 混合使用，状态自动对齐。

011

并发控制

多 Agent 操作时乐观锁检测冲突，拒绝覆盖。

012

多工具追踪

manifest.tools 记录每个工具的资产归属，sync/upgrade 逐个刷新。

这不是 AI 的"建议"

这是工程的"验证"

04 / ADVERSARIAL REVIEW

AI 写的代码，
由另一个 AI 独立审查。

AI 写代码很快，但它审查自己时有天然的确认偏差。子Agent 对抗验证——独立上下文、盲审、结构化输出，让 AI 互相挑战。

盲审— Blind Review

子Agent 只收到 raw diff + 项目规范原文，不收到主Agent 的任何评价。

独立身份— Independent Identity

提示词明确 'You did NOT write this code. The author is someone else.'

结构化输出— Structured Output

子Agent 返回 JSON findings，主Agent 可以验证但不能软处理或删除。

两种审查策略

策略 A（默认）— 单Agent 综合审查

主Agent 写代码 → 1 个子Agent 盲审（正确性/安全/性能/可维护性/规范一致性）→ 有争议 → 升级到第二个独立子Agent 裁决 → 两个子Agent 意见一致 → 按有问题处理，主Agent 不得推翻

策略 B（高风险触发）— 3Agent 并行审查

认证/授权/支付/敏感数据/加密领域 → 3 个子Agent 并行：安全审计 + 正确性审查 + 规范审查 → 投票机制：≥2 票认为有问题 → 按有问题处理

子Agent 发现 finding主Agent 验证

可自动验证 → 读代码确认事实

需判断 → 升级到第二个子Agent

两个子Agent 一致 → 按有问题处理，主Agent 不得推翻

两个子Agent 不一致 → 标记为"需人工判断"

05 / SPEC-DRIVEN

先对齐"做什么"，
再让 AI 决定"怎么做"。

规范是 AI 与人类之间的合同。AI 按合同交付，你按合同验收，分歧在写代码前就被看见。

比较项Prompt-Driven Spec-Driven

输入一段话proposal + spec + design + tasks

AI 理解"我觉得你想要……""根据 spec 第 3 条……"

验证肉眼对比openspec validate 自动校验

追溯Prompt 淹没在聊天里完整制品链永久存档

恢复重新描述一遍从 archived change 继续

DELTA SPECS

只记录这次改变了什么。

新增、修改、移除都有明确语义；归档时自动合入主规范，文档永远与代码同步。

## ADDED Requirements
### Requirement: Todo 支持到期日

## MODIFIED Requirements
### Requirement: Todo 创建接口

## REMOVED Requirements
### Requirement: 旧版导出接口

06 / AI TOOLS

4 款 AI 工具，
统一门禁，统一资产归属。

Claude Code 与 OpenCode 享受 PreToolUse 钩子自动注入；Cursor 与 Codex 按文档手动接入。一套模板、一致的门禁逻辑、各自的原生体验。

01推荐

Claude Code

Skill 原生集成，Agent 架构天然支持独立子Agent 对抗验证，PreToolUse 钩子自动写入 settings.json。

钩子自动注入

02AUTO HOOKS

OpenCode

与 Claude Code 同级的 4 号工具适配器，PreToolUse 钩子由 opsx 自动注入 opencode.json。

钩子自动注入

03MANUAL

Cursor

按需加载项目规则，不打断日常编码；hooks.json 由你按文档手写一份。

钩子按文档手动接入

04MANUAL

Codex

完整 agent 配置，通过 prompt 入口一键启动；Codex hook 仍属 feature flag，按文档手动接入。

钩子按文档手动接入

内置 5 套 tech-stack 模板

backendjava-spring-bootJava 17+ / Spring Boot 3.x / Maven+Gradle
backendpython-fastapiPython 3.10+ / FastAPI / Pydantic / SQLAlchemy / pytest / Ruff / mypy
frontendreact-viteReact 18+ / TypeScript / Vite / Vitest + RTL
fullstackjava-reactMonorepo: Java Spring Boot + React 18+
fullstackpython-reactMonorepo: Python FastAPI + React 18+

npx opsx-dev-pipeline list-tools

07 / MULTI-TOOL

同一仓库，
多套 AI 工具并存。

Schema v2 把 manifest.tools 升级为数组；你可以为不同成员分别安装 Claude Code / OpenCode / Cursor / Codex，第二次 init 不再覆盖前者的资产。 sync / upgrade / doctor 都按多工具维度工作。

MANIFEST 工具追踪

同一仓库，多套工具栈并存。

每次 init 只安装选中工具的资产，sync / upgrade 会按manifest.tools 逐个刷新；doctor 会列出全部已装工具与active tool。

1
Claude CodePreToolUse 钩子自动注入
2
OpenCodePreToolUse 钩子自动注入
3
CursorHook 需手动接入
4
CodexHook 需手动接入

~/workspaceSTEP 1 / 4

$ opsx-dev-pipeline init --tool claude --stack backend --yes

renderclaude skills & commands

render settings.json + scripts/hooks/

state{ "tools": ["claude"], ...

renderpreparing next tool...

›

命令	manifest.tools	结果
`init --tool claude`	`claude`	安装 Claude Code 资产
`init --tool opencode`	`claude, opencode`	补装 OpenCode，不覆盖前者
`doctor --json`	`tools: [claude, opencode], active: claude`	诊断时列出全部已装工具
`uninstall --tool cursor`	`claude, opencode`	按工具粒度卸载

团队混用，但门禁统一

Claude Code 用户和 Cursor 用户在同一仓库里写代码，OpenSpec schema、状态机、Hook 脚本共用同一份。

重复 init 不再覆盖

已经 init 过 Claude Code，再 init OpenCode 不会覆盖前者资产；manifest.tools 会同步记录 ["claude", "opencode"]。

按工具卸载

opsx-dev-pipeline uninstall --tool cursor 只删 .cursor 下的托管文件，Claude Code 的 skills/commands 保持原样。

升级同步所有工具

sync/upgrade 遍历 manifest.tools 中的每个 ID，逐个重新渲染受管文件，多工具资产同步刷新。

08 / ROUTE 分级

按风险等级，
自动选择流水线重量。

Phase 0 会根据需求描述推荐 trivial / standard / full 三档 Route。错别字走最短路径，核心业务全流程覆盖。Route 写进状态文件，只能向上升级、不能降级。

琐碎route.trivial

错别字、格式化、注释、import 清理

最佳入门

Phase 026

标准route.standard

新功能、Bug 修复、重构

团队默认

Phase 01256

完整route.full

核心业务、数据库迁移、安全相关

高保障

Phase 01234567

trivial 跳过 Phase 1/3/4/5/7；standard 跳过 3/4/7；full 完整执行 8 个 Phase。

09 / PIPELINE HOOKS

规则下沉到宿主层，
不是写在 prompt 里。

PreToolUse 钩子由 opsx 自动注入 Claude Code 与 OpenCode 的宿主配置，Cursor / Codex 按文档手动接入。危险命令、敏感文件——从根上拦下。

危险 Bash

AUTO

block-dangerous-bash.sh

敏感文件写入

AUTO

block-sensitive-write.sh

block-dangerous-bash.sh

PreToolUse · Bash

rm -rf /、rm -rf ~、rm -rf .destructive-rm-blocked
git push --force / --force-with-leaseforce-push-blocked
git branch -Dforce-branch-delete-blocked
chmod 777 / chmod -R 777world-writable-chmod-blocked
curl <url> | sh、wget <url> | bashremote-pipe-shell-blocked
mkfs.ext4 /dev/sda1filesystem-format-blocked
dd if=/dev/zero of=/dev/sdaraw-disk-write-blocked

block-sensitive-write.sh

PreToolUse · Write / Edit

.env / .env.* / *.envsensitive-env-blocked
*.key / *.pem / *.p12 / *.pfx / *.secretsensitive-key-blocked
credentials.json / service-account.jsonsensitive-credentials-blocked
openspec/.pipeline-state/*.jsonpipeline-state-write-blocked（请用 dev-pipeline-state.mjs）
.git/ 内部文件git-internal-write-blocked

按工具的接入方式

工具	模式	注入位置
Claude Code	AUTO	`.claude/settings.json + scripts/hooks/`
OpenCode	AUTO	`.opencode/opencode.json + scripts/hooks/`
Cursor	MANUAL	`按 docs/hooks/cursor.md 手写 .cursor/hooks.json`
Codex	MANUAL	`按 docs/hooks/codex.md 手写 ~/.codex/config.toml`

不需要钩子？init --feature no-hooks 即可关闭；--feature hooks / --feature no-hooks 互斥。

10 / SAFETY GATES

交付之前，
安全检查不会沉默。

高风险操作不会被揉成一个"确认"按钮。每一道防线都给出明确事实、独立决策和可审计记录。

LOCAL ONLY代码与状态不会上传

敏感文件扫描

.env、私钥块与 credentials.json 自动检测并警告

危险操作禁用

拒绝 git add -A、push --force 与 branch -D

分步确认

commit、push、merge、删分支与 tag 各自确认

冲突协议

逐文件解决，禁止全局 --ours / --theirs 覆盖

Fast-forward Only

发现分叉立即暂停，不自动 rebase 或静默覆盖

尊重 Git Hooks

Hook 失败必须修复或显式确认 --no-verify

11 / QUICK START

30 秒，
从零到 AI-Ready。

前置条件只有 Node.js 20+ 与 OpenSpec CLI。初始化不会覆盖已有文件，支持先预览安装计划；钩子按工具 auto / manual 自动选择。

1
安装 OpenSpec全局安装规范引擎
2
初始化 Pipeline选择 AI 工具、stack 与 tech-stack
3
补装其它工具init --tool opencode 等可叠加安装
4
开始首个变更从 proposal 开始，而不是从代码开始

INSTALL.sh

01# 安装 OpenSpec CLI

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

04# 初始化 Claude Code 流水线

05npx opsx-dev-pipeline@latest init --tool claude --stack backend --yes

07# 叠加 OpenCode，hooks 由 opsx 自动注入

08npx opsx-dev-pipeline init --tool opencode --stack backend --yes

10# 启动第一个变更

11/opsx-dev-pipeline "给 Todo 添加 dueDate"

manifest.tools = ["claude", "opencode"]READY

交互安装 / init静默安装 / --yes计划预览 / --dry-run健康诊断 / doctor模板升级 / upgrade清理卸载 / uninstall按工具卸载 / uninstall --tool

12 / BUILT FOR REAL WORK

< 30s初始化耗时

8Phase 0–7 门禁

4AI 工具适配器

5tech-stack 模板

13E2E 测试场景

3Route 风险等级

2PreToolUse 钩子

MIT开源协议

13 / FAQ

你可能想问的，
都在这里。

还有未覆盖的问题？带上 doctor --json 的结果来 GitHub Issues。

前往 Issues

01团队成员使用不同 AI 工具，能统一管理吗？

能。一份 OpenSpec schema、共享状态机和门禁规则。manifest.tools 会同时记录 claude / opencode / cursor / codex 中已安装的若干个；sync / upgrade 都会逐个刷新。

02需要安装什么？

需要 Node.js 20+ 和 OpenSpec CLI 1.6+。安装 OpenSpec 后，一条 npx 命令即可完成初始化。

03已有项目还能使用吗？

可以。init 可安装到任意已有项目，默认不覆盖现有文件；.gitignore 等可追加文件智能合并，README.md 也会保留你的修改。

04适合什么规模？

个人项目、小团队与开源项目都适用。价值会随协作者数量和变更频率增加而更明显。中小型功能开发（< 500 行 diff）最佳适配；大型重构建议拆分为多个小变更；一次性脚本可用 trivial Route。

05必须使用 Claude Code 吗？

不必。Claude Code、OpenCode、Cursor 与 Codex 均受支持，共用同一套流水线逻辑。Claude Code 因 Agent 架构天然支持对抗验证，推荐追求最强审查保障的用户使用；OpenCode 同样获得 auto 钩子集成。

06和直接写 prompt 有什么区别？

Prompt 只描述当下任务；pipeline 让 prompt 在有 proposal、spec、测试门禁、安全策略、归档规则与 PreToolUse 钩子的系统里运行。

078 个 Phase 都是强制的吗？

审查与单测允许显式跳过，但决定会被记录。提案和归档不可跳过，分别保证目标对齐与变更不失忆。Route 决定哪些阶段被跳过：trivial 跳过 1/3/4/5/7，standard 跳过 3/4/7，full 完整执行。

08Route 选错了怎么办？能降级吗？

Route 只能向上升级：`trivial → standard → full`。如果低估了风险，可以用 `dev-pipeline-state.mjs route <change> upgrade <route>` 升档。降级会被拒绝，避免跳过已发生的审查门。

09流程跑一半中断怎么办？

状态保存在 openspec/.pipeline-state。再次触发时会核对 Git 与文件事实，并从断点继续。多工具场景下 manifest.tools 同时记录每个工具的状态归属。

10为什么修复重试最多三轮？

三轮仍未通过通常意味着需求或设计需要重新判断。状态机会暂停并让人介入，避免 AI 无限循环。

11可以自定义各阶段行为吗？

可以。每个 Phase 的行为由 references 下的 Markdown 定义，测试、验证和构建命令可在 openspec/config.yaml 配置。

12支持 Python / Django / Vue 吗？

python-fastapi 与 react-vite、python-react 已内置；从最接近的内置模板开始，再修改项目上下文、规则和 schema。Vue 需自行替换 schema 片段。

13能多装几个 AI 工具吗？

可以。init 支持重复执行：先 `init --tool claude` 再 `init --tool opencode` 即可叠加工具，manifest.tools 会累积记录。Cursor/Codex 也可按相同模式补装。

14可以只卸载某一个工具吗？

可以。`opsx-dev-pipeline uninstall --tool cursor` 只删除 .cursor 下的托管资产；manifest.tools 同步收敛，但其他工具的 skills/commands 不会被影响。

15PreToolUse 钩子会拦截所有 AI 操作吗？

钩子只在 Claude Code 与 OpenCode 中自动安装；Cursor 需要按 docs/hooks/cursor.md 手写 .cursor/hooks.json；Codex 0.141+ 需开启 `[features] hooks = true`。钩子纯 Node.js，无外部依赖。

16会上传我的代码吗？

不会。逻辑与状态均在本地 Git 仓库运行，不需要 API Key，也不会把代码发送到额外服务。

17和裸用 OpenSpec 有什么区别？

OpenSpec 提供规范引擎；opsx-dev-pipeline 在其上增加阶段顺序、状态持久化、AI 工具适配（含多工具组合）、安全钩子与交付门禁。

18能替代人工 code review 吗？

不能。子Agent 对抗验证是在人工 review 之前的第一轮自动化交叉验证——让 AI 先相互挑战，把可自动检测的问题消灭在人工 review 之前。

19商业使用有限制吗？

没有。项目使用 MIT 协议，可用于商业项目、私有部署与二次开发。

20遇到问题如何排查？

先运行 opsx-dev-pipeline doctor --json，它会列出已安装工具、active tool 以及模板版本诊断，再把结果提交到 GitHub Issues。

21子Agent 对抗验证和普通 AI 审查有什么区别？

普通 AI 审查是同一个模型审查自己写的代码——存在确认偏差。子Agent 对抗验证启动一个独立 Agent，它有独立的上下文，不知道主Agent 的判断，收到的只是 raw diff 和项目规范原文。它被明确告知"你没有写这些代码，作者是别人，你的任务是找出问题"。

22我用独立命令写了提案，能用 pipeline 继续吗？

可以。独立命令执行时会自动记录到 .pipeline-state 的 phaseHistory 中。当你后续触发 pipeline 时，Hermes 会检测已有状态，通过 Gate 补偿策略自动对齐——不需要从头开始，也不会丢失之前的决策记录。

23混合模式下，如果我跳过了一些门禁怎么办？

Gate 补偿策略分三级处理：① 可推断的 Gate→ 自动通过；② 需重检的 Gate；③ 必须确认的 Gate → 无论如何都会询问你。

24状态文件能告诉我谁在什么时候做了什么吗？

能。状态文件包含：创建者身份（git config + 邮箱）、机器环境信息（OS/Node 版本）、需求追溯 ID、唯一指纹、阶段耗时。完整链路：Who → When → Where → Why → What → How → Review → Test。

25支持英文本地化吗？

支持。`init --lang en` 会切换模板、prompt、commit message 与面向用户的错误提示，默认仍为 zh。manifest.lang 字段会持久化偏好。

READY TO STANDARDIZE?

让团队的 AI 编码从"各凭本事"，
变成 "统一标准"。

npx opsx-dev-pipeline@latest init

查看 GitHub 开源 MIT本地运行多工具共存

AI 写代码，团队审计每一次变更。

AI Agent 越来越自主，但你管不了它每一步怎么决策。