从零构建依赖升级侦察 Skill：Claude Code 自定义 Skill 开发实战

flowchart LR
    A[会话启动] -->|扫描所有 skill| B[第一层:索引\n约100 tokens/skill]
    B --> C{用户 prompt\n是否匹配 description?}
    C -->|否| D[不加载, 零成本]
    C -->|是| E[第二层:加载 SKILL.md 正文]
    E --> F{正文是否引用\nscripts/references?}
    F -->|需要| G[第三层:按需读取支撑文件]
    F -->|不需要| H[直接执行]
    G --> H

mkdir -p ~/.claude/skills/bump-scout/{scripts,references,templates}
cd ~/.claude/skills/bump-scout

---
name: bump-scout
description: Assesses the impact of upgrading a dependency and produces a risk-rated upgrade plan. Use when the user wants to bump/upgrade/update a package version, asks "is it safe to upgrade X", or plans a major version migration. Scans affected files, classifies SemVer breaking-change risk, and outputs a rollback-ready plan. Does NOT run installers or write migration code.
argument-hint: [package] [from-version] [to-version]
arguments: package from_version to_version
allowed-tools: Read Grep Glob Bash
---

## What this skill does

You are a dependency-upgrade impact assessor. Given a package and its target version,
produce a concise, risk-rated upgrade plan WITHOUT running any installer.

## Inputs

- Package: $package (from-version: $from_version -> to-version: $to_version)
- If versions are omitted, infer the current version from the lockfile/manifest below.

## Procedure

1. **Read the current dependency state** (already inlined in "Current state" below).
2. **Scan affected files** by running `scripts/affected.sh $package` — count and list
   import sites grouped by directory.
3. **Classify risk** using `references/risk-matrix.md`. A major-version bump is HIGH
   risk until proven otherwise.
4. **Fetch breaking changes**: read the package's CHANGELOG/release notes for the
   target major version; summarize the top 3 breaking changes. If offline, say so
   and mark risk conservatively.
5. **Produce the plan** by filling in `templates/upgrade-plan.md`.

## Output

Fill the template. Lead with a one-line risk verdict (LOW / MEDIUM / HIGH / BLOCKER).
Keep prose minimal — tables and bullet points over paragraphs.

#!/usr/bin/env bash
# 扫描某依赖的所有引用点，按目录分组统计。
# 用法: affected.sh <package-name>
set -euo pipefail

pkg="${1:?usage: affected.sh <package-name>}"
# 取包名最后一段做宽匹配：@scope/react -> react
short="${pkg##*/}"

echo "## Affected files for \`$pkg\`"
echo

# 1. 源码 import/require/from
mapfile -t files < <(grep -rIlE \
  "(from|import|require)\s+['\"][^'\"]*${short}(@|/|['\"])" \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
  --include='*.py' --include='*.go' -- . 2>/dev/null || true)

if [ "${#files[@]}" -eq 0 ]; then
  echo "- No direct imports found."
  exit 0
fi

# 2. 按顶层目录分组计数
echo "| Directory | Files |"
echo "|-----------|-------|"
printf '%s\n' "${files[@]}" | \
  awk -F/ '{print $2}' | sort | uniq -c | \
  awk '{printf "| %s | %d |\n", $2, $1}'

echo
echo "Total: ${#files[@]} files"

chmod +x ~/.claude/skills/bump-scout/scripts/affected.sh

# Upgrade Risk Matrix

Classify the bump, then adjust based on findings.

| Version delta | Base risk | What to check |
|---------------|-----------|---------------|
| patch (x.y.**Z**) | LOW | Bug fixes; run test suite |
| minor (x.**Y**.z) | LOW–MED | New APIs/deprecations; check removed deprecations |
| major (**X**.y.z) | **HIGH** | Breaking API/behavior; peer-dep range; migration guide |
| cross-major (e.g. 17→19) | **HIGH+** | Multiple breaking layers; treat as BLOCKER until reviewed |

## Downgrade triggers (move risk one level UP)
- Package is a framework (react, next, vue, express) — ripples through app
- Used in > 50 files OR in critical path (auth, payment, routing)
- Current version is > 2 majors behind (accumulated breaking changes)
- No tests cover the package's usage

## Upgrade triggers (move risk one level DOWN)
- Patch-only with a published security advisory (upgrade is safer than waiting)
- Used in 1–2 trivial files with full test coverage

## Verdict mapping
- LOW: ship directly after tests pass
- MEDIUM: ship behind a feature flag or in a staging canary
- HIGH: staged rollout + rollback plan required (template section 5)
- BLOCKER: do not upgrade without a migration spike first

# Upgrade Plan: {{package}} {{from_version}} → {{to_version}}

**Risk verdict:** [LOW / MEDIUM / HIGH / BLOCKER]

## 1. Summary
- One line: what changes and why it matters.

## 2. Affected surface
| Directory | Files | Notes |
|-----------|-------|-------|

## 3. Top breaking changes (from CHANGELOG)
1. ...
2. ...
3. ...

## 4. Required code changes
- [ ] ...

## 5. Rollback plan
- Commit hash before upgrade: `<fill>`
- Rollback command: `git revert <hash>` or lockfile restore command
- Verify-rollback check: <which test/command proves rollback worked>

## 6. Verification
- [ ] `npm test` (or equivalent) green
- [ ] Manual smoke: <critical path>

~/.claude/skills/bump-scout/
├── SKILL.md                      # 第二层：主指令（短）
├── scripts/
│   └── affected.sh               # 第三层：机械劳动
├── references/
│   └── risk-matrix.md            # 第三层：查表知识
└── templates/
    └── upgrade-plan.md           # 第三层：输出骨架

## Current state

### Installed version & manifest
!`cat package.json 2>/dev/null | grep -A2 -B2 "$package" || grep -rI "$package" go.mod requirements.txt pyproject.toml Cargo.toml 2>/dev/null | head -20`

### Recent commits touching this dependency
!`git log --oneline -10 -- '*package.json' '*go.mod' '*requirements.txt' 2>/dev/null | head -10`

/bump-scout react 18.2.0 19.0.0

context: fork

/bump-scout react 18.3.1 19.0.0

# Upgrade Plan: react 18.3.1 → 19.0.0
**Risk verdict: HIGH**

## 1. Summary
跨主版本升级，60 个文件受影响，需迁移已弃用 API；建议分阶段灰度。

## 2. Affected surface
| Directory | Files | Notes |
|-----------|-------|-------|
| src/components | 42 | 大量使用 defaultProps |
| src/pages | 18 | 普遍用 ReactDOM.render |

## 3. Top breaking changes
1. `ReactDOM.render` 被移除 → 须改用 `createRoot`
2. 函数组件 `defaultProps` 弃用 → 改默认参数
3. `ref` 作为普通 prop 传递 → 移除 `forwardRef` 的多数用法

## 4. Required code changes
- [ ] 全局替换 `ReactDOM.render` → `createRoot(...).render(...)`
- [ ] 扫描并迁移所有 `defaultProps` 为参数默认值
- [ ] 审查 `forwardRef` 使用，能简化则简化

## 5. Rollback plan
- Commit hash before upgrade: `<在本步骤前先提交>`
- Rollback command: `git revert <hash>` 并 `npm ci` 恢复锁文件
- Verify-rollback: `npm test` 全绿 + 首页冒烟

## 6. Verification
- [ ] `npm test` green
- [ ] 冒烟：首页渲染、路由跳转、表单提交

flowchart TD
    U[用户: 我想升级 react 到 19] --> M{description 匹配?}
    M -->|是| L[加载 bump-scout 第二层]
    L --> INJ[动态注入: 读 package.json + git log]
    INJ --> S1[运行 scripts/affected.sh\n扫描受影响文件]
    S1 --> S2[读 references/risk-matrix.md\n判定风险等级]
    S2 --> S3[读 CHANGELOG\n提炼破坏性变更]
    S3 --> S4[填 templates/upgrade-plan.md]
    S4 --> OUT[输出风险评级 + 升级计划]
    M -->|否| X[不加载, 零成本]
    style L fill:#fef3c7
    style OUT fill:#dcfce7
    style X fill:#fee2e2