vibedevops

name	vibedevops
description	Vibe coding 但不放弃理解，生产级 DevOps 保障。用于 /vibedevops、看懂 AI 改动、项目地图、变更摘要、复述测试、跨 App/多模型路由、Claude/Codex/Reasonix/Kimi 切换、交接架构、HANDOFF、AGENTS.md、密钥泄露、CI、回滚、监控和生产就绪体检。提供变更解释契约、单写入者多模型工作流、AGENTS.md/HANDOFF/ADR 跨 agent 交接架构，以及模板化机械门禁。通用于所有项目与所有厂商 agent。

VibeDevOps — vibe coding，但不放弃理解

核心理念：vibe coding 的速度可以全拿，理解不能全丢。 理解不是看懂每一行代码，而是始终能回答四个问题——改了什么、为什么改、动了哪里、怎么验证。这套 skill 把"理解"从感觉变成流程和文件。

一、变更解释契约（每次改动都生效，零成本）

每次让 AI 动手，在需求后面追加这段固定指令：

改动前，先告诉我你打算改哪些文件、每个文件改什么、为什么，等我确认再动手。 改动完成后，请输出：① 变更文件清单 ② 每个文件改动的一句话说明 ③ 如果涉及多个文件，说明它们之间的调用关系 ④ 如果引入了新的目录或文件，说明它在项目结构中的位置。

配套动作：改动后跑 git diff，让 AI 逐段解释。 diff 是性价比最高的学习材料——真实、具体、就是你自己的代码。

二、三阶段理解进阶路线

阶段一：让 AI 被迫"解释"（第 1–2 周）

不改变自己，先改变下的指令——即上面的变更解释契约。目标是每次改动都留下可读的解释痕迹。

阶段二：建立项目地图（第 2–4 周）

把"黑盒文件夹"变成脑子里的地图：

1. 跑结构：tree -L 3，让 AI 用一句话概括每层目录的职责。
2. 找入口：每个项目都有入口（main.py / index.ts / App.vue…），从入口顺着 import / 调用链走一遍主流程。
3. 画一张图：核心文件 + 依赖关系画成框图（手绘也行），贴在旁边。每次改动后更新它——这就是活文档。

阶段三：小步验证（第 4 周起）

用工程习惯把理解固化下来：

• 小步提交：一个功能拆成多个 commit，每个 commit 都能说清"这一步为什么存在"。
• 复述测试：改完后不看 AI 的解释，自己向 AI 复述"改了什么、为什么这么改"，让 AI 纠正。能讲出来才算懂。
• 预测练习：提需求前先猜"这大概会动哪几个文件"，再和实际改动对比。猜错的地方就是知识盲区。

三、交接架构：把理解固化进仓库

对话里的理解会随上下文压缩蒸发；落盘的不会。这套架构让任何厂商的 agent（Claude / Codex / Cursor / Gemini / Windsurf / Kimi）进任何仓库都能秒接续：

文件	作用
AGENTS.md	唯一权威协作守则：接续三步（开始前）、收尾三件套（结束前）、验证命令、Git 纪律、反模式。所有厂商文件只是指针，冲突时以它为准
docs/HANDOFF.md	交接状态板：当前目标 / 已完成 / 进行中（含文件位置）/ 已知坑 / 下一步 / 验证方式。任何 agent 上手先读它
docs/adr/	架构决策记录（ADR），治"忘了为什么这么改"。对话里想通但没落的决策，等于没发生过
厂商指针	CLAUDE.md / GEMINI.md / .cursorrules / .windsurfrules / .github/copilot-instructions.md —— 无论谁进来，都被指向同一份 AGENTS.md

模板见 templates/，一键部署脚本见 scripts/deploy-handoff.sh（幂等、支持 --dry-run）。

接续三步（agent 开始工作前必做）：

1. 按固定顺序读：README* → AGENTS.md → docs/HANDOFF.md → docs/adr/ → git log -10 --oneline
2. 先跑一次验证命令确认基线是绿的；基线红 → 先修基线，绝不在红基线上叠改动
3. 用自己的话复述当前任务与验收标准，确认与 HANDOFF 一致后再动手

收尾三件套（结束工作前必做）：

1. 跑完整验证命令，确认全绿
2. 更新 docs/HANDOFF.md
3. 提交 git，不留未提交的半成品

多 App / 多模型切换

把 App 视为无状态入口，把 Git、AGENTS.md 和 docs/HANDOFF.md 视为状态机。详细角色路由与接棒格式见 references/model-routing.md。

必须遵守：

1. 一个分支/工作树同一时刻只有一个写入者；其他模型只读审查。
2. 换 App 前先验证、更新 HANDOFF、提交；下一棒从该 commit 接续。
3. HANDOFF 记录当前写入者、App/模型、分支与 HEAD、验收标准、验证证据、fallback 状态和下一棒唯一动作。
4. 不复制整段聊天历史；只传仓库事实、决策、证据和必要视觉素材。
5. 需要并行写入时使用不同 worktree 和不同分支，合并前由一个主工程负责人收口。

部署纪律（跨仓库批量部署时）：

• 只新增、不覆盖；已存在的厂商文件备份（.bak）后追加指针块
• 每个仓库单独提交（消息含"交接架构"），可随时 git revert 回滚
• 工具厂商自管的内部仓库（.codex/、.claude/ 等）跳过，动了会搞坏工具
• 没有 git 的目录这套架构立不住，先 git init 再部署

本机全局同步： install.sh 将 Claude、Codex、OpenCode/OpenChamber、Cursor、Gemini、Qwen、Windsurf 的用户级入口收敛到 ~/AGENTS.md，并把 VibeDevOps/Flow 以符号链接安装到各 Agent。厂商专属配置只追加权威指针或 import，首次修改前备份；OpenCode 使用官方全局入口 ~/.config/opencode/AGENTS.md 的直链，避免规则复制后漂移。

原生 Reasonix 运行时： templates/reasonix-runtime/ 提供 macOS launchd 与 Linux systemd --user 常驻模板，幂等配置 Reasonix 的 OpenCode Go Provider、凭据文件、85% 官方 compaction 阈值和 loopback /healthz。从仓库根目录运行 ./install.sh --with-reasonix-runtime；OpenChamber 的 Reasonix-Go 仍只是 Reasonix 风格 Agent，不冒充原生进程。

镜像生命周期： templates/image-lifecycle/ 同时治理开发机/部署机 Docker 与 GHCR。任何容器引用的镜像、每仓库最新版本、current/last-known-good digest 和生产/回滚 tag 都必须保护；禁止 docker image rm --force 与自动删除 volume。docker builder prune --force 仅用于关闭交互确认，必须限定过期且未使用 cache。成功部署后回收部署机旧镜像；下次构建前必须重试清理欠账并通过容量门禁；GHCR 每日执行 retention。清理失败应告警并阻止资源继续恶化，但不回滚已经通过功能/指标门的健康发布。本机 Docker 守卫用 ./install.sh --with-image-lifecycle；只有明确授予 delete:packages 后才用 --with-ghcr-retention 增加账号级清理。

踩过的坑（部署脚本作者注意）：

• macOS 自带 bash 3.2 下 set -u 对空数组展开误报 unbound variable——不要用 set -u，用 ${arr[@]+"${arr[@]}"} 防御式展开
• .gitignore 忽略整个 docs/ 时交接文件会被漏掉——提交用 git add -f，文件一旦被跟踪即恢复正常跟踪
• 部署前检查 .git/index.lock 残留（确认无进程后清除）
• bash 3.2 下 $VAR 后紧跟全角字符（；，：（）等）会被吞进变量名，set -u 时报 unbound variable——shell 里变量后接中文一律 ${VAR}

四、生产级保障包（上线前后的机械防线）

Vibe Coder 的典型事故不是看不懂代码，而是密钥泄露、没有 CI、上线靠祈祷、出事不会回滚。所有保障都做成模板 + 脚本 + AGENTS.md 规则三件套——不靠自觉维持，自觉是最不可靠的关卡。

4.1 密钥与安全基线（第一事故源）

防线按依赖成本从零到高排列（规范全文见 templates/security/SECRETS.md）——机械防线不能建立在"用户记得装某个工具"上：

• 第 0 层（零安装）：GitHub Secret scanning + Push protection 打开——服务端强制，装不上/被忘/换机器都不影响，所以排第一
• 第 1 层（单二进制）：templates/security/pre-commit 提交前拦截（gitleaks → Infisical（如已装）→ 兜底正则）；.env.example 入库、真 .env 永不入库
• 第 2 层（solo/小团队默认）：sops + age 把部署密钥加密进 git（模板 templates/security/sops.yaml）——零服务依赖、离线可用、密钥与代码同生命周期；repo secrets 收敛为一个 age 私钥
• 漏了能救：先轮换后清理（git filter-repo）→ 查调用日志 → 落 ADR
• 团队化之后才升级 Infisical（集中托管 + 按权限分发 + 运行时注入，需要云或自托管后端）；升级条件与 CI 机器身份用法见 SECRETS.md 第八节。同时跑两套密钥体系比没有体系更糟，二选一

4.2 CI 三件套（templates/ci/）

• pr-check.yml：密钥扫描 + lint/type/test，PR 必过（含 Node/Python/Go 三语言注释替换段）
• runner-canary.yml：托管 CI 故障日的分层定位探针——self-hosted 调度、构建机 checkout、分域名连通三问，先实证再路由（ADR 0006）；所有必过 job 的 runs-on 走仓库变量，额度/账单故障期一条 gh variable set 切自建 runner
• deploy.yml：PR 合并进 main 后，按 Xserver→Mac 构建 fallback、GitHub hosted→Xserver GHCR push fallback 路由同一份不可变制品，以 OIDC 短期身份自动部署；功能层 smoke/canary 失败自动回滚并复验，端到端强制小于 30 分钟
• image-retention.yml：每日清理 GHCR 过期 manifest/SHA 版本，至少保留 30 个版本并保护生产/回滚 tag；部署机清理由 deploy.sh cleanup-images 在成功推广后执行
• 回滚标准动作：见 RUNBOOK

授权边界：PR 合并就是生产部署授权。 审核、CI 和发布时间决策都在合并前完成；合并后不得再次等待人工 approve。workflow_dispatch 只用于重试、回滚和事故恢复，不能成为正常发布的唯一入口。需要等待发布时间窗口时延迟合并 PR。

完整流水线、不可变制品、渐进发布、OIDC、供应链锁定和观测指标见 references/ci-cd-best-practices.md。

4.3 回滚与事故应急（templates/RUNBOOK.template.md）

• 上线即留退路：每次部署前写下"这步怎么 revert"；git revert 优先于修复 patch
• 数据库变更纪律：迁移前一行命令备份；expand-contract 拆两次部署；AI 生成的 DROP/全表 ALTER/UPDATE 必须逐行人工过目
• 事故三板斧：止损（回滚/降级）→ 定位（Sentry → 日志 → 最近 git log）→ 复盘（blameless 5-why，产出 ADR）
• 破坏性命令三级分级 + manifest 备份（references/dangerous-commands.md）：Blocked 永拒 / Dangerous 先备份再确认 / Warning 提示；破坏性操作前的备份必须带 manifest（时间戳、原命令、路径映射），恢复按 manifest 精确放回；体检/诊断输出契约=阈值+当前值+severity+可复制的修复命令

4.4 监控与环境（templates/production-checklist.md）

• 监控四件套：/health 返回依赖真实状态（禁硬编码 200）、Sentry、可用性监控、告警到人
• 环境可复现：版本锁定文件 + 安装一条命令 + infisical run 拿密钥；验收标准"新机器 clone 到跑通 ≤ 5 分钟"
• 依赖更新：templates/renovate.json——非 major 分组周更，major 单独 PR 人工过目

4.5 弱网 / 资源受限环境：降级路由与补验欠账（templates/build-gate/）

中国开发者的典型组合：本机性能有限、CI 免费额度会耗尽且静默失败、自建构建机连通不稳、代理工具抢路由、拉境外镜像慢。对策不是"找一台更强的机器"，而是把"在哪验证"变成显式机制：

• 机器角色锁死：开发机只做内循环（受影响测试 + 类型检查）；专用构建机做全量验证；生产机只拉已验证制品、绝不构建。角色写死，每台机器的资源消耗才有上限。
• 三级路由门禁：CLOUD（CI）→ BUILDER（专用构建机）→ LOCAL（本机兜底），自动降级，三条路跑同一条命令、写同一份 docs/BUILD-EVIDENCE.md，区别只在证据强度标注。CI 额度查不到时按不足处理——"以为 CI 在跑其实没跑"是最危险的静默失败。
• 降级会「装了却没生效」，四个已验证的坑（2026-08 实战复盘，详见 templates/build-gate/README.md）：① 门禁判 [ -d .git ] 会拒绝所有 git worktree，而交接协议恰恰要求用 worktree 并行；② 门禁镜像与生产镜像不同源时，绿了也没有意义；③ 验证命令写成 .venv/bin/... 这类只在本机成立的形式，一进干净容器就 127；④ 三级降级只覆盖 CI，不覆盖 CD——CI 一死就无法发布，这一点必须事前写明。
• self-hosted runner 通常不计费：把 PR 门禁迁到自有构建机，才是额度/账单问题的根治；每次手动降级是治标。2026-08-17 实证：账单欠费只拒 hosted job（3 秒 0 步被拒），self-hosted 照常调度执行，Packages/API/git 也全部正常——瘫的不是托管方，是 runs-on: 里写死的 hosted 标签。
• runner 不写死，由仓库变量路由（ADR 0006）：runs-on: ${{ vars.CI_RUNNER && fromJSON(vars.CI_RUNNER) || 'ubuntu-latest' }}，CD job 用 CD_RUNNER。默认 hosted 优先不变；故障期一条 gh variable set 切自建 runner，恢复一条 delete 切回——分钟级、零代码、无需重跑 PR 流程。区域特化（镜像前缀 CI_REGISTRY_MIRROR、pip/npm 源、buildx cache 类型）同套变量走，默认官方源。
• 无人值守 failover 闭环（ADR 0007，templates/ci/runner-failover.sh + hosted-canary.yml）：把上面的手动切换升级为自治——检测托管 job 的账单/额度拒绝签名（conclusion=failure 且 0 步且无 runner）→ 自动切自建 runner；故障期定时 workflow_dispatch 一个钉死 ubuntu-latest 的探针仓（账单坏时被拒=零成本），探针绿=托管恢复→自动切回。纳管范围=自动发现（注册 runner 即纳管）。安全阀：只回收自己设的变量（managed 标记）、runner 不在线不切、发现失败沿用缓存不缩圈、并发锁。
• 仓库接入自治（ADR 0010，templates/build-gate/onboard-reconcile.sh + onboard-repo.sh）：failover 只救「已注册 runner」的仓——没注册的新仓是它的盲区，必撞额度 0 步失败，而「建仓后记得跑接入命令」不是机制。对策 = 状态收敛：构建机 root 对账循环（30 分钟一轮）把「OWNER 名下每个有 workflows 的仓都有 runner + 路由变量」收敛成事实；即时通道 onboard-repo.sh <owner/repo> 是同一份实现的单仓模式，两个入口永不漂移。纪律：只做加法（绝不覆盖已有变量值——异构车道配置安全）、「已注册」以平台侧 API 为准（config.sh 断链留下的 .runner_migrated 残留会把本地判定骗成已配置）、注册失败整目录重来、注册单写入者（双通道并发 --replace 互相吊销凭据）、新单元出厂即带出网配置（否则注册到网络层补配之间存在裸奔空窗，首个 job 的包管理器直连超时）。首轮全量对账即清账（实测 35 仓补 runner、367 个变量），历史欠账与新欠账一视同仁。
• 断连型 job 自愈重跑：self-hosted 出境抖动会把跑到一半的 job 打成 Abandoned（failure 但无任何 failed step 且已分配 runner）——这是基建签名不是代码红，watcher 识别后自动 （每 run 上限 2 次）。

模板与部署说明：templates/build-gate/（bash 3.2 兼容，macOS 自带 bash 可直接跑）。

4.6 验证自治：把「人是唯一 verifier」拆掉（ADR 0011，templates/verification/ + templates/skill-testing/）

4.1–4.5 解决的是怎么把代码安全送上生产；这一节解决的是送上去的东西是不是对的—— 而后者在多数团队里仍然由人逐个检查。人做 verifier，整条流水线的吞吐上限就等于一个人的 检查速度，前面并行多少 agent 都会堵在这里。瓶颈的性质不是质量不够，是并行度。

判据很硬：再多门禁也替代不了验证能力。门禁能拦已知错误，拦不住「界面点不动」 「首屏慢一倍」「截图里那个错位来自哪个组件」——这类事实只能通过实际操作产品获得。

四层，顺序不可颠倒：

• ① 能力层（verify-web.sh）：agent 自己打开页面、采集 console/失败请求/性能与内存 指标/截图，产出机器可判的证据 JSON，任一判据越界即非零退出——于是它同时是门禁。 能力来自浏览器调试协议通道（实测 cdp('Performance.getMetrics') 可取 JSHeapUsedSize/Nodes/Documents，配合 navigation timing 得到首屏耗时）。 curl 拿到 200 只证明服务器回了字节，证明不了页面能用。 自身也踩过绿色谎言：早期版本打开一个错误页照样报「通过」，因为没有「页面到底加载没加载」 的判据——现补 DOM 规模与主文档状态双判据，守卫测试锁死。 诊断侧另有 capture-trace.sh：CPU trace 与 heap snapshot 按需采集（实测产出 681KB / 2,743 条 trace 事件、32MB / 406,422 节点的堆快照，可直接拖进浏览器 DevTools 的 Performance / Memory 面板）。它不进常态门禁——单次堆快照数十 MB， 多次对比会吃满内存；trace 与门禁的关系是「诊断」而非「拦截」。
• ② 地图层（feature-map.template.yaml + check-feature-map.sh）：功能名 → 路由 → 组件 → 进入条件 → 验证方式 → 已知坑。让「一张截图」「某某页面坏了」这类模糊输入 可被机械翻译成可复现的操作序列。过期的地图比没有地图更危险——它让 agent 自信地 走到错的地方，所以校验器进 PR 门禁：路由/组件/i18n 前缀三项与代码对不上即红。 尤其校验路由↔组件的对应：只验路由存在是不够的，路由表里同时有 /messages 与 /inbox 时地图写错一个照样通过，而 agent 会被带到另一个页面（实测踩过）。
• ③ 技能层：每次发现 agent 在猜测、漏读代码、走错方向，把该失败模式写成一条 skill。 失败模式不写成可执行技能就只是叙事——写在 ADR 与交接文档里的教训需要人读到、 想起来、并照做；写成 skill 才会在下一次自动生效。
• ④ 技能测试层（templates/skill-testing/）：skill 必须像代码一样被测——多个 sub-agent 独立执行同一批任务样本，rubric 打分，两个模型交叉评分且分歧取低 （分歧说明 rubric 或任务描述不清，该改的是 fixture 不是 skill），与基线比对防退化。 没测过的 skill 与没写过的 skill，可靠性上没有区别——这是 ADR 0009 在技能层的同构。 分三类属性测，缺一不可：触发准确性（该用时用了/不该用时没用）、执行正确性、结果质量； 只测结果质量是常见错误——最常见的失败其实是根本没触发，而那时结果看着还挺正常。

前提是先有机械门（templates/ci/set-branch-protection.sh）：实测本组织六个主力仓 main 全部零保护——CI 红也能点 Merge、谁都能直推 main 触发生产部署。脚本按 「要求 CI 通过 + 不要求 review（单人仓要求 review 等于锁死自己）+ 管理员可绕过 （逃生门）+ 禁 force push」设置，并带一道安全阀：拒绝设一个该仓从没在 PR 上跑过的 check 名——设错名字的后果是 PR 永远 BLOCKED，界面只显示「Waiting for status」， 极难看出是配置错。摸底实测到三类不能设为必需的 check：monorepo 里带 paths: 过滤的 job 不是每个 PR 都跑（13 个样本里只出现 6 次）、if: ${{ false }} 的永久 skipped job、 以及 matrix 渲染出的 check 名（如 pytest (sqlite)）——改矩阵就静默失配。

四层齐备后，自动合并才安全（templates/ci/automerge-tiers.sh）：按可逆性分三档—— T1 纯文档/测试/文案，CI 绿即合；T2 有运行时影响，需 CI 绿 + 门禁自证有效 + 实际操作过 产品的证据 + 部署侧自动回滚；T3 不可逆或影响面超出可验证范围（迁移/密钥/生产编排/ 流水线自身/真钱路径/认证授权），永远人工，不接受任何证据豁免。混合改动按最危险的那个 文件定档，不被大量安全文件稀释。人的角色从 verifier 变成 auditor。

五、与 /flow 的关系

/flow（见 ../flow/SKILL.md）是工作流主干：思考→计划→实现→自检→出活→部署→复盘，带安全关卡。VibeDevOps 是理解层与治理层：flow 管"活怎么干完"，vibedevops 管"你和下一个 agent 还懂不懂这个项目、敢不敢让它上线"。两者共用同一套安全关卡：计划须确认、出 PR 前 git diff --stat、PR CI 全绿才合并；合并 main 后由 CD 自动部署、验证和失败回滚。

六、调用 /vibedevops 时的编排行为

• 无参数：探测当前仓库交接健康度（有无 AGENTS.md / HANDOFF.md / ADR / 验证命令是否已填），给出缺口清单和下一步。
• /vibedevops 地图：执行阶段二——扫目录结构、找入口、沿调用链走主流程，输出带注释的项目地图。
• /vibedevops 交接：在当前仓库部署交接架构（先 --dry-run 给清单，确认后落笔）。
• /vibedevops 路由：读取 references/model-routing.md，按任务风险、视觉依赖、上下文规模和成本选择主模型与专项审查者；不默认让四个模型全部参与。
• /vibedevops fallback：读取 references/model-routing.md，先区分额度/限流/上游故障与请求/代码错误；只对前者按任务类型执行有限 fallback，并把失败模型、证据、下一跳和冷却状态写入 HANDOFF。
• /vibedevops 接棒：核对工作树、当前写入者、分支/HEAD、验收标准和验证证据；接棒条件不满足时停止写入并报告缺口。
• /vibedevops 复述：基于最近的 git diff / commit，向用户提问"这次改了什么、为什么"，纠正其复述。
• /vibedevops 体检：生产就绪评分（0–100），按下表逐项探测、输出得分与缺口清单。评分不止是报告，scripts/health-check.sh --min <分数> 低于阈值退出码 1，可直接挂 pre-push / CI 当门禁——分数不够拦下，不靠自觉：

维度	分值	判定规则
测试	15	有测试目录、配置或 scripts/test-*.sh，且验证命令非"待补充"
CI	15	PR 检查（8）+ push main 自动部署（4）+ 功能 smoke/canary 与失败自动回滚（3）
密钥	20	.env 在 gitignore（5）+ 无密钥入库痕迹（10，git log -p 抽样 / 跑 gitleaks）+ 有注入或加密方案（5，sops+age / Infisical 任一）
监控	15	/health 真实依赖检查 + 错误追踪接入（按实现度给分）
回滚预案	10	RUNBOOK 存在且含回滚/备份步骤
环境可复现	10	版本锁定文件 + README 有 5 分钟跑通说明
交接文件	15	AGENTS.md / HANDOFF.md / ADR 齐备且非模板未填状态

• 执行原则：扫描与解释无副作用可直接做；写入交接文件、git init、批量部署前必须给用户确认清单。