Claude Code Skills 开发实战：从零构建「数据库迁移安全守卫」

第一层：frontmatter 的 description      ← 永远在上下文里（要短、要准）
第二层：SKILL.md 正文                   ← 命中后才加载（决策流程、关键规则）
第三层：同目录的参考文件（references/）  ← 用到才读取（完整清单、模板、样例）

mkdir -p .claude/skills/migration-guardian/references
cd .claude/skills/migration-guardian

.claude/skills/migration-guardian/
├── SKILL.md                      # 第二层：决策流程 + 关键规则
└── references/
    ├── destructive-patterns.md   # 第三层：完整破坏性模式清单
    ├── lock-risk-matrix.md       # 第三层：锁表风险矩阵
    └── rollback-template.md      # 第三层：回滚脚本模板

---
name: migration-guardian
description: Reviews database migration files for destructive or lock-heavy DDL before they are applied. Use when the user edits, stages, or asks about migration files (*.sql, Alembic, Rails migrations, Flyway, Liquibase, Prisma migrate, Knex) — especially operations like DROP TABLE/COLUMN, ALTER TABLE, TRUNCATE, renaming columns, NOT NULL without default, large backfills, or creating indexes without CONCURRENTLY. Do NOT use for seed data, fixture generation, or application-level SQL queries in code.
allowed-tools: Read, Grep, Glob, Bash
---

# 数据库迁移安全守卫

你是一个数据库迁移审查助手。目标是：在迁移被应用到生产前，识别破坏性操作和高锁表风险，并给出可执行的缓解建议。

## 工作流程

1. **定位迁移文件**
   - 优先审查用户当前正在编辑 / 已 `git add` 的迁移文件。
   - 若用户未指定，用 Glob 找到最近的迁移目录（`db/migrate/`、`alembic/versions/`、`prisma/migrations/`、`migrations/`、`src/main/resources/db/changelog/` 等）。

2. **识别 DDL 类型**（用 Grep 扫描关键字，忽略大小写）：
   `DROP`, `TRUNCATE`, `ALTER`, `RENAME`, `MODIFY`, `ADD COLUMN`, `CREATE INDEX`, `NOT NULL`

3. **按破坏性等级分类**，参考 `references/destructive-patterns.md` 获取完整清单：
   - 🟥 **高危**：DROP TABLE/COLUMN、TRUNCATE、重命名列/表、删约束
   - 🟧 **中危**：NOT NULL 无默认值、加唯一索引、改列类型
   - 🟨 **低危但有锁风险**：普通 CREATE INDEX（无 CONCURRENTLY）、大表 ADD COLUMN + 回填

4. **评估锁表风险**
   - 读取 `references/lock-risk-matrix.md`，结合表行数（如能从代码/文档推断）给出 `低/中/高` 评级。

5. **输出审查报告**，格式固定：
   - 风险摘要表（文件、行号、等级、一句话原因）
   - 每个高危/中危项的**缓解建议**（如：先加可空列 → 分批回填 → 后续再设 NOT NULL）
   - 是否需要**停机窗口**的明确结论

6. **回滚预案**：对每个高危变更，参考 `references/rollback-template.md` 生成对应的正向 + 回滚 SQL。

## 关键规则（不可违反）

- **永不自动修改迁移文件**。只读、只建议。`allowed-tools` 已限定为只读工具。
- **不确定时按更严重的等级判定**，并标注「需人工确认」。
- **Postgres / MySQL / SQLite 差异**要识别：例如 `CREATE INDEX CONCURRENTLY` 仅 Postgres 支持，不要给 MySQL 项目提这个建议。
- 若迁移文件用了 ORM DSL（如 Rails 的 `remove_column`、Alembic 的 `op.drop_column`），按等价 DDL 判定。

## 何时停止

- 报告交付后，等待用户决定是否按建议修改。不要主动重写迁移。

# 破坏性 DDL 模式完整清单

## 🟥 高危（需停机或灰度）
| 模式 | 原因 | 典型缓解 |
|------|------|---------|
| DROP TABLE | 数据丢失，不可逆 | 先重命名（`_archived`）→ 观察期 → 真删 |
| DROP COLUMN | 旧代码可能仍读该列 | 先停写引用 → 再删 |
| TRUNCATE | 清空数据 | 同 DROP TABLE |
| RENAME COLUMN/TABLE | 旧代码/查询断裂 | 视图别名过渡 / 双写期 |
| 删除索引/约束 | 查询计划突变、写入报错 | 评估查询依赖后再删 |

## 🟧 中危（需灰度或分批）
| 模式 | 原因 | 缓解 |
|------|------|------|
| ADD COLUMN ... NOT NULL 无 default | 锁全表回填 | 先加可空列 → 回填 → 改 NOT NULL |
| ADD UNIQUE INDEX | 大表长锁 + 冲突失败 | 用 `CREATE UNIQUE INDEX CONCURRENTLY`（PG）|
| MODIFY 列类型 | 重写表、长锁 | 新列 + 双写 + 切换 |
| 收紧 CHECK 约束 | 已有数据可能违规 | 先扫描存量数据 |

## 🟨 低危但需注意
| 模式 | 注意点 |
|------|--------|
| CREATE INDEX（无 CONCURRENTLY）| 大表写锁，建议 `CONCURRENTLY` |
| ADD COLUMN（nullable，有 default）| PG 11+ 不重写表，MySQL 视版本而定 |
| ADD 默认值为非常量（如函数）| 部分方言行为不一致 |

# 锁表风险矩阵

风险 = f(操作类型, 表行数量级)。结合项目实际行数评级。

| 操作 | < 10万行 | 10万–1千万 | > 1千万 |
|------|---------|-----------|---------|
| DROP TABLE | 低（瞬时元数据锁）| 低 | 低 |
| ALTER ADD COLUMN（PG 11+）| 低 | 低 | 低 |
| ALTER ADD COLUMN w/ default 重写 | 低 | 🟧 中 | 🟥 高 |
| CREATE INDEX 普通 | 低 | 🟧 中 | 🟥 高 |
| CREATE INDEX CONCURRENTLY | 低 | 低 | 低（注意失败遗留 invalid index）|
| ADD UNIQUE INDEX | 🟧 中（冲突检查）| 🟥 高 | 🟥 高 |
| NOT NULL + 回填 | 低 | 🟧 中 | 🟥 高 |
| MODIFY 列类型 | 🟧 中 | 🟥 高 | 🟥 高（重写表）|

> 行数无法确定时：默认按「> 1千万」保守评级，并提示用户确认。

# 回滚脚本模板

每个迁移应提供 forward（上卷）与 rollback（回滚）两段。

## 加列（安全模式）
```sql
-- forward
ALTER TABLE orders ADD COLUMN status_new VARCHAR(20);

-- rollback
ALTER TABLE orders DROP COLUMN status_new;

-- Step 1 forward: 加可空列
ALTER TABLE orders ADD COLUMN email_verified BOOLEAN;
-- Step 1 rollback
ALTER TABLE orders DROP COLUMN email_verified;

-- Step 2 forward: 回填 + 收紧（必须在 Step 1 全量上线后）
UPDATE orders SET email_verified = false WHERE email_verified IS NULL;
ALTER TABLE orders ALTER COLUMN email_verified SET NOT NULL;
-- Step 2 rollback
ALTER TABLE orders ALTER COLUMN email_verified DROP NOT NULL;

到这一步，三层结构全部就位：**frontmatter 永驻、正文按需、references 深挖**。

---

## 六、验证：手动触发与自动触发

### 手动触发（最直接）

在项目里运行 Claude Code，输入：

应看到 Claude 开始按正文流程执行：先用 Glob 找迁移文件、再 Grep 关键字、再调取 references 分类。

### 自动触发（才是 Skill 的价值）

新建一个故意带坑的迁移文件 `db/migrate/20260622_drop_users_avatar.sql`：

```sql
-- 删掉头像列，反正没人用了
ALTER TABLE users DROP COLUMN avatar_url;
TRUNCATE TABLE user_avatar_history;
CREATE INDEX idx_users_email ON users(email);  -- 大表无 CONCURRENTLY

我准备把这周的迁移上生产，帮我看一眼有没有问题。

🟥 高危
- db/migrate/20260622_drop_users_avatar.sql:3  DROP COLUMN avatar_url
  → 旧代码可能仍在读取，建议先双写/停引用，本轮不要删
- db/migrate/...:4  TRUNCATE user_avatar_history
  → 数据不可逆，建议先 RENAME 为 _archived 观察

🟨 低危但锁风险
- db/migrate/...:5  CREATE INDEX 无 CONCURRENTLY
  → users 为大表时写锁显著，建议改 CREATE INDEX CONCURRENTLY

结论：本批次不建议直接上线，需停机窗口或拆分为多步灰度迁移。
回滚预案见已生成的 forward/rollback 脚本。

# evals 用例示例
should_activate:
  - input: "帮我看看 alembic/versions/ 下新加的迁移安不安全"
    expect: migration-guardian 被加载，输出风险报告
  - input: "prisma migrate 这次的 down 迁移会不会锁库"
    expect: 加载并评估锁表风险

should_not_activate:
  - input: "帮我写一个查最近订单的 SQL 查询"
    expect: 不加载（这是应用层查询，非迁移）
  - input: "生成一批测试用的 seed 数据"
    expect: 不加载（属 seed，已在 description 排除）

flowchart TD
    A[用户发消息] --> B{Claude 扫描所有 Skill 的 frontmatter}
    B -->|描述命中意图| C[加载该 Skill 正文<br/>第二层]
    B -->|未命中| Z[按普通对话处理]
    C --> D[正文流程引用 references?]
    D -->|是| E[按需读取参考文件<br/>第三层]
    D -->|否| F[直接执行正文步骤]
    E --> F
    F --> G{是否破坏性/锁风险?}
    G -->|有| H[输出分级报告+缓解建议+回滚]
    G -->|无| I[给出低风险确认]
    H --> J[用户决定是否修改]
    I --> J
    J --> K[结束<br/>不自动改文件]

    style B fill:#e8f0fe,stroke:#1a73e8
    style C fill:#fef7e0,stroke:#f9ab00
    style E fill:#e6f4ea,stroke:#34a853

# 在 CI 的迁移文件变更时调用
changed_migrations=$(git diff --name-only origin/main...HEAD -- \
  'db/migrate/*.sql' 'alembic/versions/*.py' 'prisma/migrations/**/migration.sql')

if [ -n "$changed_migrations" ]; then
  claude -p "审查以下迁移变更的安全性与锁表风险，只输出 JSON：{risk: high|medium|low, items:[...], block: bool}：$changed_migrations" \
    --allowed-tools "Read,Grep,Glob"
fi