# Small Diff

> 最小改动模式。线上修复 / 小 bug / 老项目维护 / 跨多人协作的代码区域改动时强制启用：不重构无关代码、不格式化整文件、每处 diff 都解释必要性。

- Skill: `jackwener/small-diff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jackwener/small-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jackwener/small-diff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jackwener (https://skillmd.com/u/jackwener)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jackwener/small-diff

---


# /small-diff · 最小改动模式

## 使用场景

- 修线上 bug（review 成本高，越小越好）
- 在多人协作的核心模块里改代码（不能顺手 rename）
- 在不熟的代码区域改代码（不知道改动的辐射范围）
- 老项目维护（历史代码风格不一致，但改了风格 = 引入风险）

任何时候**用户明确说"最小改动"**也立即启用本 Skill。

## 目标

让每个 diff **小、明确、可解释**。Agent 默认倾向于"既然来了我顺手优化一下"——`/small-diff` 是对抗 scope creep 的工程手段。

## 必须步骤

### 1. 列出"必须改"的最小集合

按"完成任务必须改"的角度筛选：

- 删掉一切"可改可不改"的修饰
- 删掉一切"看起来更好但不解决问题"的重构
- 删掉一切"顺手"的命名 / 顺序调整

### 2. 解释每一处 diff 的必要性

对每一处改动回答：

- 为什么必须改？（任务直接要求 / 修 bug 必经路径 / 其他改动的依赖）
- 为什么不能更小？

如果回答不出，**删掉这处改动**。

### 3. 不允许做的事

| 行为 | 原因 |
|---|---|
| 顺手 rename 变量 | 增加 review 成本 |
| 顺手 format 整个文件 | 把 diff 噪音放大 10 倍 |
| 顺手抽象出 helper 函数 | 任务不需要、引入新决策点 |
| 顺手"现代化"语法（switch → match） | 风险 vs 收益不成比例 |
| 顺手补 type | 除非这处 type 是 bug 的根因 |
| 顺手删 dead code | 留给独立的 cleanup PR |
| 顺手改测试期望值 | **永远不要**——这是 reward hacking 红线 |

### 4. 必须做的事

- **不变的不动**：即便看到丑代码也忍住
- 改动**集中在最少的文件 / 最少的函数**
- 新增导出 / 新增 props 必须在调用方有真实需求
- 改函数签名前先 grep 所有调用方，确认改动可控

### 5. 最终自审

```bash
git diff --stat | wc -l
```

如果改了超过 5 个文件，或者超过 200 行，**停下重新评估**：

- 是不是任务确实需要这么大改？
- 能不能拆成多个 PR？

## 禁止事项

- ❌ 用"顺便"作为加改动的理由
- ❌ 用"现代化"作为重写的理由
- ❌ 用"代码风格不一致"作为格式化整文件的理由
- ❌ 用"为了将来扩展"作为新增抽象的理由（YAGNI 原则）
- ❌ 改测试期望值让红的变绿（除非测试**本身**确认是错的，且解释清楚为什么）

## 输出格式

```markdown
## 改动范围
- 文件 N 个，行数 M
- 涉及：lib/xxx.ts、app/api/yyy/route.ts

## 每处改动 + 必要性
1. `lib/xxx.ts` line 42-45：添加 fooBar() 调用 → 因为... 不加不能完成任务
2. `app/api/yyy/route.ts` line 10：从 body 取 examId → 因为... 路由本身需要

## 主动放弃的"顺手"
- 看到 lib/xxx.ts 里有未用 import，没动（留给独立 cleanup）
- 看到 app/api/yyy/route.ts 的错误处理可以更优雅，没动（不在任务范围）
```

## 与其他 Skill 的关系

- 通常在 [`/think`](../think/SKILL.md) 决定方案后启用
- 完成后用 [`/check`](../check/SKILL.md) 验证 diff 性质
- bug 修复场景结合 [`/hunt`](../hunt/SKILL.md) 找完根因后用 `/small-diff` 实施