gstack 数据迁移评审专家全解SCOPE_MIGRATIONS 触发机制与数据库变更安全审查清单【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack本文围绕 gstack 的/review技能中数据迁移专家Data Migration Specialist展开它是一份面向数据库迁移代码的专项审查清单由bin/gstack-diff-scope检测出的SCOPE_MIGRATIONS信号自动激活以并行子代理形式在 PR 落地前对 diff 进行可回滚性、数据丢失风险、锁时长、回填策略、索引创建和多阶段部署安全性六大类检查。读完本文你可以掌握该专家在 gstack Review Army 中的完整触发链路、输出契约、自适应门控NEVER_GATE机制以及每一条检查项背后的工程原理。数据迁移专家是什么、在哪里数据迁移专家是 gstack/reviewPre-Landing PR Review技能Review Army评审军团中的一名条件激活的专项审查员。它的清单定义在 review/specialists/data-migration.md与 testing.md、security.md、performance.md 等并列每个专家对应一个独立的 Markdown 清单文件。文件头部明确了它的契约激活条件SCOPE_MIGRATIONStrue即 diff 中被检测到数据库迁移文件输出每行一个 JSON 对象的 findings 流category固定为data-migrationspecialist固定为data-migration无发现时只输出NO FINDINGS不输出任何其他内容。它不是独立的 CLI 工具而是被 review/SKILL.md Step 4.5Review Army — Specialist Dispatch按如下规则调度5. **Data Migration** — if SCOPE_MIGRATIONStrue. Read ~/.claude/skills/gstack/review/specialists/data-migration.md也就是说当 scope 信号命中时主代理读取该清单全文把它连同 stack 上下文、历史 learnings 一起塞进子代理 prompt子代理拿到完整 diff 后逐条套用清单输出结构化 findings。触发链路SCOPE_MIGRATIONS 是如何被检测出来的SCOPE_MIGRATIONS由脚本 bin/gstack-diff-scope 产生。/review 的 Step 4.5 会执行source (~/.claude/skills/gstack/bin/gstack-diff-scope base 2/dev/null) || true该脚本对变更文件集合逐文件做 glob 分类其中 migrations 分类的匹配规则为case $f in db/migrate/*|migrations/*|*/migrations/*|alembic/*|prisma/migrations/*) m_migrationstrue ;; db/data/*|data_migrations/*|*/data_migrations/*) m_migrationstrue ;; esac覆盖的布局包括Rails 的db/migrate/、根级或任意层级的migrations/Vercel/serverless 布局、Alembic 的alembic/、Prisma 的prisma/migrations/以及 Rails data_migrate gem 的db/data/与data_migrations/源码注释特别说明data migration 是无人值守运行的任意 Ruby风险严格高于 schema migration所以同样命中 BACKEND 分类。从源码结构看该脚本有三个对可靠性至关重要的设计变更集合是三路并集提交 diff ∪ 工作区改动 ∪ 未跟踪文件。注释引用 #2299/ship在 Step 9 检测 scope 时早于 Step 15 的 commit所以未提交的新迁移文件也必须可见——否则先开工后 ship这一最常见流程会让所有 scope 门控的评审员被静默跳过。退出码契约#2526exit 0 表示没有变更或至少命中一类exit 2 有两种含义——有变更但零命中输出SCOPE_ERRORunmatched并逐行列出未匹配路径让新目录布局大声失败而不是静默禁用评审或 base 引用不可解析SCOPE_ERRORno_base典型场景是 CI 浅克隆此时全 false 且绿会被误读为我们看过且没问题。输出对source安全每行都是合法赋值或注释非 ASCII 路径用 NUL 分隔的git diff -z避免八进制引号击穿扩展名 glob。这些行为有完整的测试佐证见 test/diff-scope.test.ts。其中有几条直接针对迁移检测test(detects migrations via db/migrate/, () { const dir createRepo([db/migrate/20260330_create_users.rb]); expect(runScope(dir).SCOPE_MIGRATIONS).toBe(true); }); test(detects migrations via prisma, () { const dir createRepo([prisma/migrations/20260330/migration.sql]); expect(runScope(dir).SCOPE_MIGRATIONS).toBe(true); });以及表格驱动用例覆盖根级migrations/0001_initial.sql、嵌套app/migrations/、db/data/20260804123456_backfill_x.rb等还有一条专门验证未跟踪的新迁移文件也会置位 SCOPE_MIGRATIONS评审员必须看到它。此外SCOPE_MIGRATIONS与SCOPE_BACKEND等是相互独立的布尔值#2299一个.rb迁移文件会同时点亮 MIGRATIONS 和 BACKEND而非 first-match-wins 的互斥关系。六大检查类别清单全文与逐项解析data-migration.md 的核心是六个类别。以下完整继承原文档检查项并补充其背后的工程考量。1. 可回滚性Reversibility该迁移能否在不丢数据的情况下回滚是否存在对应的 down/rollback 迁移rollback 是真正撤销了变更还是只是 no-op回滚之后当前应用代码会不会坏掉最后一项容易被忽略回滚不只是数据库单边的事情。如果新版应用代码已经依赖新 schemarollback 迁移会把数据库打回旧形态而代码还是新的等于制造一次线上故障。这也是该清单把部署顺序单独拆成一类见第 6 类的原因。2. 数据丢失风险Data Loss Risk删除仍然含数据的列应先加弃用期变更列类型导致数据截断如varchar(255) → varchar(50)删除表之前未验证没有任何代码仍引用它重命名列时没有更新所有引用ORM、裸 SQL、视图对已存在 NULL 值的列追加 NOT NULL 约束需要先回填这几条对应的是迁移事故的经典形态隐式截断、视图/裸 SQL 里的暗引用、约束追加时的存量 NULL。评审时值得让模型或人对每一处rename/remove/change_type追问还有谁在读它。3. 锁时长Lock Duration大表上的ALTER TABLE没有使用CONCURRENTLYPostgreSQL超过 10 万行的表上建索引没用CONCURRENTLY多条本可合并成一次锁获取的ALTER TABLE语句在流量高峰时段获取排他锁的 schema 变更超过 10 万行是清单给出的显式阈值作为是否必须CONCURRENTLY的判断依据多条 ALTER 可合并则针对的是反复进出锁模式的 DDL 序列合并成一次锁获取能显著缩短阻塞窗口。4. 回填策略Backfill Strategy新增 NOT NULL 列但没有 DEFAULT 值需要先回填才能上约束新增带计算默认值的列需要分批填充存量记录缺少回填脚本或 rake task一次性 UPDATE 全部行而非分批会锁表这一类与部署顺序强耦合标准的安全模式是加可空列 → 代码双写 → 分批回填 → 上 NOT NULL/DEFAULT → 清理旧列任何一步缺失都可能被这一类检查捕获。5. 索引创建Index Creation生产表上CREATE INDEX没用CONCURRENTLY重复索引新索引与已有索引覆盖相同列新增外键列缺少索引部分索引与全量索引的选择用错该用全量却建了部分或反之外键列无索引是连接/删除放大风险的常见源头重复索引则是写放大和存储浪费。6. 多阶段部署安全Multi-Phase Safety必须与应用代码按特定顺序部署的迁移会破坏当前运行中代码的 schema 变更应先部署代码后迁移假设了部署边界的迁移旧代码 新 schema 崩溃滚动部署期间新旧代码并存时缺少 feature flag这一类审查的焦点是新旧代码与新旧 schema 的四种组合核心不变量任意时刻运行中的代码无论新旧都必须在数据库处于迁移前或迁移后任一状态时都能正常工作——即 schema 变更必须是代码兼容的超集直到确认所有实例都是新代码后才能做破坏性收尾。输出契约逐行 JSON 与 NO FINDINGS清单头部定义的输出 schema 为{severity:CRITICAL|INFORMATIONAL,confidence:N,path:file,line:N,category:data-migration,summary:...,fix:...,fingerprint:path:line:data-migration,specialist:data-migration}字段约束字段要求必填severityCRITICAL|INFORMATIONAL、confidence0-10、path、category、summary、specialist可选line、fix、fingerprint、evidence、test_stubfingerprint 缺省合并阶段按{path}:{line}:{category}有 line 时或{path}:{category}计算无发现仅输出NO FINDINGS不允许前言、总结或评论其中test_stub是一个值得注意的设计如果某条发现可以用一个测试拦截子代理要按项目检测到的测试框架jest/vitest/rspec/pytest/go-test写出最小测试骨架。这让发现直接可转化为回归防线。调度机制并行子代理、自适应门控与保险策略理解这份清单如何被使用需要看 review/SKILL.md Step 4.5/4.6 的完整流程该段落由 scripts/resolvers/review-army.ts 从模板生成同一份Review Army逻辑也被嵌入/ship的 Step 9见 ship/sections/review-army.md选择规则diff 少于 50 行时跳过所有专家50 行以上Testing 与 Maintainability 常驻其余按 scope 信号条件激活——Data Migration 对应SCOPE_MIGRATIONStrue。自适应门控每次评审前运行 bin/gstack-specialist-stats它汇总项目历史*-reviews.jsonl中各专家的派发次数与发现数NEVER_GATE new Set([security, data-migration]); // ... if (NEVER_GATE.has(name)) tag [NEVER_GATE]; else if (s.dispatched 10 s.findings 0) tag [GATE_CANDIDATE];规则是连续 10 次以上派发且 0 发现的专家会被标记[GATE_CANDIDATE]并自动跳过避免永远沉默的评审员消耗 token但security与data-migration被硬编码为[NEVER_GATE]——源码注释称之为insurance policy specialists保险策略型专家它们存在的全部价值恰恰在于平时沉默、出事时兜底如果按命中率自动关掉它们就本末倒置了。这意味着只要 diff 里有迁移文件该专家一定会跑无论历史命中率如何。强制标志用户 prompt 中若包含--data-migration或--all-specialists则绕过门控强制派发。派发所有选中专家在同一条消息中以多个 Agent 工具调用并行启动每个子代理使用subagent_type: general-purpose并显式传run_in_background: false自 Claude Code v2.1.198 起子代理默认后台运行必须显式关闭。任一子代理失败或超时不阻塞整体——记录失败、继续采用成功结果因为部分结果好过没有结果。合并与置信度门控Step 4.6逐行解析各专家输出跳过非 JSON 行按 fingerprint 去重相同 fingerprint 的发现保留最高 confidence 者打上MULTI-SPECIALIST CONFIRMED (a b)标签置信度 1上限 10——多个专家独立发现同一问题本身就是强信号置信度门控7 正常展示5-6 附带中置信度请确认提示3-4 移入附录1-2 完全抑制计算 PR 质量分quality_score max(0, 10 - (critical_count * 2 informational_count * 0.5))上限 10。数据迁移专家的 findings 与主 CRITICAL 通道的发现一起进入 Step 5 的 Fix-First 流程自动修复 vs 询问用户的分类同样适用并在评审日志中以{dispatched: true, findings: N, critical: N, informational: N}形式记录——这条记录正是gstack-specialist-stats命中率统计的数据来源构成派发 → 记录 → 门控的闭环。实战使用方式在一个包含迁移变更的仓库分支上运行 gstack 的/review技能触发语如 review this PR、pre-landing review即可典型链路是# 1. 查看当前 diff 会点亮哪些 scope 信号以你的 base 分支替换 main bash bin/gstack-diff-scope main # 期望看到 SCOPE_MIGRATIONStrue若 diff 涉及 db/migrate/、migrations/、 # alembic/、prisma/migrations/、db/data/、data_migrations/ 等布局 # 2. 运行 /reviewStep 4.5 会打印类似 # Dispatching N specialists: [testing, maintainability, contenteditable="false">【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
