生成风格割裂
每个人各凭 prompt 发挥，没有统一的 AI 使用规范。
OPEN SOURCE / MIT
让 AI 写出符合团队规范的代码，而不只是能跑的代码。
给 Claude Code、Cursor 和 Codex 装上同一套提案、实施、审查、测试与交付门禁。30 秒初始化，每次变更都可解释、可验证、可追溯。
本地运行无 API KeyNode.js 20+
LIVE PIPELINE07 / 07
$ npx opsx-dev-pipeline init --tool claude --stack backend --yes
Initializing team guardrails...
00
Preflight
passed01
Propose
passed02
Apply
passed03
Review
passed04
Test
passed05
Archive
passed06
Deliver
passedPipeline complete. Change is ready to ship.
WHYWHATHOWTESTSHIP
01 / THE PROBLEM
团队在用 AI 编程，
但你管不了每个人怎么用。
vibe coding 的问题不只是代码质量。真正的风险是：没有人能解释一段代码为何存在、验证过没有，以及谁做了关键决定。
Review 变成考古
变更没有 proposal，reviewer 只能从代码 diff 猜意图。
测试覆盖下降
没有强制门禁，测试对 AI 来说只是建议，不是必须。
决策快速失忆
设计文档从未更新，关键决定散落在一次性聊天里。
敏感文件入库
交付前没有自动扫描，.env 与密钥可能混进提交。
口头约定失效
“下次注意”无法规模化，团队需要工程约束而非记忆。
VIBE CODING快，但不可控
OPSX PIPELINE速度可以被信任
02 / HOW IT WORKS
7 个阶段，一条流水线。
从一句需求到可信交付。
每一步都有状态记录，每个关键节点都由你确认。中断后从断点恢复，不是从头开始。
PHASE 0 / Preflight
预检
确认 OpenSpec、Git 与项目环境均可用。
状态写入完成，允许进入下一阶段
$ node preflight.mjs --json
passopenspec installed
passgit repository clean
doneenvironment ready
›
03 / CORE POWER
统一团队的标准，
不是依赖每个人的自律。
建议可以被跳过，约束不会。可持久化状态机把团队规范变成每次变更都必须经过的工程事实。
pipeline-state.jsonsaved
{
"phase": 4,
"gate": "tests",
"status": "passed",
"decisions": 3
}门禁校验
测试未通过，状态机拒绝进入归档。
状态持久化
流程中断后，精确回到上一个决策点。
原子写入
临时文件加 rename，崩溃不留下半份状态。
重试上限
三轮仍未通过则暂停，主动呼叫人工介入。
决策审计
跳过、合并策略与关键确认永久可追溯。
事实校验
恢复时交叉核对 Git、文件系统与 OpenSpec。
这不是 AI 的"建议"
这是工程的"约束"04 / 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: 旧版导出接口05 / AI TOOLS
选你喜欢的 AI 工具。
标准不随工具改变。
一套模板、一致的门禁逻辑、各自的原生体验。
01CLAUDE
Claude Code
Skill 原生集成，用 /opsx-dev-pipeline 触发全流程。
ADAPTER READY02CURSOR
Cursor
按需加载项目规则，不打断日常编码，需要时召唤。
ADAPTER READY03CODEX
Codex
完整 agent 配置，通过 prompt 入口一键启动。
ADAPTER READYnpx opsx-dev-pipeline list-tools06 / 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
07 / QUICK START
30 秒，
从零到 AI-Ready。
前置条件只有 Node.js 20+ 与 OpenSpec CLI。初始化不会覆盖已有文件，支持先预览安装计划。
- 1安装 OpenSpec全局安装规范引擎
- 2初始化 Pipeline选择 AI 工具与主技术栈
- 3开始首个变更从 proposal 开始，而不是从代码开始
01# 安装 OpenSpec CLI
02npm install -g @fission-ai/openspec@latest
03
04# 初始化团队流水线
05npx opsx-dev-pipeline@latest init
06 --tool claude --stack backend --yes
07
08# 启动第一个变更
09/opsx-dev-pipeline "给 Todo 添加 dueDate"
Pipeline initializedREADY
交互安装 / init静默安装 / --yes计划预览 / --dry-run健康诊断 / doctor模板升级 / upgrade清理卸载 / uninstall
08 / BUILT FOR REAL WORK
< 30s初始化耗时
7阶段门禁
3AI 工具
2技术栈模板
10自动化脚本
MIT开源协议
01团队成员使用不同 AI 工具，能统一管理吗？
能。团队共享同一套 OpenSpec 规范、状态机和门禁规则。目前每个项目绑定一个主 AI 工具，混合工具团队可按子项目初始化。
02需要安装什么？
需要 Node.js 20+ 和 OpenSpec CLI。安装 OpenSpec 后，一条 npx 命令即可完成初始化。
03已有项目还能使用吗？
可以。init 可安装到任意已有项目，默认不覆盖现有文件；.gitignore 等可追加文件会智能合并。
04适合什么规模？
个人项目、小团队与开源项目都适用。价值会随协作者数量和变更频率增加而更明显。
05必须使用 Claude Code 吗？
不必。Claude Code、Cursor 与 Codex 均受支持，共用同一套流水线逻辑。
06和直接写 prompt 有什么区别？
Prompt 只描述当下任务；pipeline 让 prompt 在有 proposal、spec、测试门禁、安全策略和归档规则的系统里运行。
077 个 Phase 都是强制的吗？
审查与单测允许显式跳过，但决定会被记录。提案和归档不可跳过，分别保证目标对齐与变更不失忆。
08流程跑一半中断怎么办？
状态保存在 openspec/.pipeline-state。再次触发时会核对 Git 与文件事实，并从断点继续。
09为什么修复重试最多三轮？
三轮仍未通过通常意味着需求或设计需要重新判断。状态机会暂停并让人介入，避免 AI 无限循环。
10可以自定义各阶段行为吗？
可以。每个 Phase 的行为由 references 下的 Markdown 定义，测试、验证和构建命令可在 openspec/config.yaml 配置。
11能用于 Vue 或 Django 吗？
可以从最接近的内置模板开始，再修改项目上下文、规则和 schema。当前预置模板聚焦 React/Vite 与 Spring Boot。
12前后端项目该选哪个栈？
初始化时选择主栈，随后可在配置中加入第二套 schema。仓库内 fullstack-todo 样例展示了完整用法。
13流水线拒绝哪些 Git 操作？
自动流程禁止全量暂存、强制推送、强制删分支和全局冲突覆盖，并会扫描常见敏感文件。
14确实需要 force push 怎么办？
在流水线之外由你手动判断和执行。pipeline 只保证 AI Agent 不会代替你做高风险操作。
15会上传我的代码吗？
不会。逻辑与状态均在本地 Git 仓库运行，不需要 API Key，也不会把代码发送到额外服务。
16和裸用 OpenSpec 有什么区别？
OpenSpec 提供规范引擎；opsx-dev-pipeline 在其上增加阶段顺序、状态持久化、AI 工具适配和安全交付门禁。
17和 GitHub Actions 有什么区别？
CI 在 push 后检查，pipeline 在 AI 编码过程中约束。两者互补，Phase 6 的推送可以继续触发 CI。
18能替代人工 code review 吗？
不能。Phase 3 是第一轮自动筛查，让人工 reviewer 把注意力放在架构判断与业务逻辑上。
19商业使用有限制吗？
没有。项目使用 MIT 协议，可用于商业项目、私有部署与二次开发。
20当前路线图是什么？
重点包括更多 AI 工具适配、社区栈模板，以及继续完善跨平台的 Node.js 脚本体系。
21遇到问题如何排查？
先运行 opsx-dev-pipeline doctor --json，再把诊断结果提交到 GitHub Issues。
22它会拖慢 AI 编码吗？
它增加的是必要决策点，不是无意义等待。目标是保留 AI 的速度，同时让产出可解释、可验证、可交付。