从混沌到秩序：Git Diff 结构化报告的 Claude Code Skill 实践

“最痛苦的代码审查，不是逻辑复杂的代码，而是滚屏如瀑布的 git diff 输出。”

你有没有经历过这样的场景：

准备做代码审查，执行 git diff main...feature-branch，然后——屏幕开始疯狂滚动。修改了 47 个文件，2000 多行变更。你盯着黑底绿字的终端输出，试图在脑海中拼凑出"这次改动到底干了什么"。

这就像收到一箱未分类的邮件，全部倒在桌上，然后被告知"请在 30 分钟内审阅完毕"。

问题不在于变更太多，而在于 Git 的原生输出缺乏结构。它忠实地展示了"哪些行变了"，却没有回答"这些变更的组织逻辑是什么"。

今天，我将深入剖析一个 Claude Code Skill——git-diff-report。它不是一个独立的 CLI 工具，而是 Claude Code 生态中的领域专用知识包，将 Git diff 的专家级操作封装成 AI Agent 可调用的结构化能力。

---

一、问题域：Git 原生输出的三重困境

在深入解决方案之前，让我们先明确问题的本质。

1.1 信息过载

一次典型的功能开发可能涉及：

• 3 个组件文件（UI 层）
• 2 个服务文件（业务逻辑）
• 1 个路由文件
• 5 个工具函数
• 若干配置和类型定义

git diff 会将这 10+ 个文件的变更线性平铺，没有层次，没有分组。reviewer 必须在脑中重建"这些文件属于哪个模块"的映射关系。

1.2 上下文丢失

当你在终端执行 git diff，输出转瞬即逝。想回头看看刚才那个文件？要么重新执行命令，要么在终端缓冲区里艰难翻找。

更糟糕的是，如果你同时需要审查多个 PR，每个 PR 的 diff 信息完全混杂在终端历史中。

1.3 无法追溯

三个月后，有人问：“当时 v2.0 发布前，我们改了哪些文件？”

你的回答大概率是：“让我查查 git log… 然后 git diff… 呃，我需要一些时间。”

git-diff-report Skill 的核心价值，就是把这三个问题转化为 Claude Code 可复用的领域能力。

---

二、什么是 Claude Code Skill？

在深入 git-diff-report 的实现之前，让我们先理解 Skill 在 Claude Code 生态中的定位。

2.1 Skill 的本质：领域专用知识包

Claude Code Skill 不是普通的脚本或插件，它是一种将专家知识编码为 AI 可调用能力的封装方式。

一个完整的 Skill 包含三个层次：

┌─────────────────────────────────────────────────────────┐
│  SKILL.md  - 工作流定义                                  │
│  (AI 读取的指令：何时调用、如何调用、输出什么)            │
├─────────────────────────────────────────────────────────┤
│  scripts/  - 可执行脚本                                  │
│  (实际执行的代码逻辑)                                    │
├─────────────────────────────────────────────────────────┤
│  references/  - 参考文档                                 │
│  (配置说明、使用示例、领域知识)                          │
└─────────────────────────────────────────────────────────┘

2.2 git-diff-report 的 Skill 结构

~/.claude/skills/git-diff-report/
├── SKILL.md                    # 技能定义文档
├── CLAUDE.md                   # 活动日志
├── scripts/
│   └── git-diff-report.js      # 核心脚本（798 行）
└── references/
    └── config-options.md       # 配置选项参考

SKILL.md 的关键作用：它告诉 Claude 这个 Skill “是什么”、“能做什么”、“怎么用”。当用户说"帮我生成一份代码变更报告"时，Claude 会读取 SKILL.md，理解应该调用 git-diff-report.js 脚本，并传入正确的参数。

2.3 Skill vs 普通脚本

维度	普通脚本	Claude Code Skill
调用方式	手动执行命令	AI 自动识别场景并调用
知识载体	代码注释	SKILL.md + references/
参数传递	用户记忆	AI 根据上下文推断
输出处理	终端显示	AI 解析并整合到对话
可组合性	需手动串联	AI 自动编排多个 Skill

Skill 的核心价值：把"人需要记住的操作步骤"变成"AI 可以自动执行的能力"。

---

三、6 种 Git 模式：一个接口，多种场景

git-diff-report 支持 6 种 Git 模式，覆盖了日常开发中几乎所有的 diff 场景：

模式	命令示例	适用场景	Git 等效命令
diff	--mode diff	查看工作区未暂存变更	git diff
staged	--mode staged	查看已暂存待提交变更	git diff --cached
show:<hash>	--mode show:abc123	分析单个历史提交	git show <hash>
diff:<c1>..<c2>	--mode diff:v1.0..v2.0	两个提交/标签对比	git diff c1..c2
branch:<name>	--mode branch:main	当前分支 vs 目标分支	git diff main...HEAD
last:<N>	--mode last:5	最近 N 次提交累积变更	无直接等效

设计亮点：统一抽象

这 6 种模式在用户界面上是统一的 --mode 参数，但在底层实现中，每种模式对应不同的 git 命令组合。这是 策略模式（Strategy Pattern） 的典型应用：

用户输入: --mode branch:main
    ↓
模式解析器 (parseGitMode)
    ↓
策略分发: { type: "branch", branchName: "main" }
    ↓
命令构建器 (buildDiffArgs)
    ↓
Git 命令: ["diff", "main...HEAD"]

为什么 last:<N> 模式特别有价值？

Git 原生没有"查看最近 N 次提交的累积 diff"这个功能。你需要手动执行：

1. git log -5 --format=%H 获取最近 5 个 commit hash
2. 找到最老的那个 commit 的父提交
3. git diff <parent>..HEAD

git-diff-report Skill 将这个三步操作封装成了 --mode last:5。这正是 Skill 的价值——把专家知识编码为 AI 可执行的命令。

当用户对 Claude 说"帮我看看最近 5 次提交改了什么"，Claude 不需要用户记住复杂的 Git 命令组合，而是直接调用这个 Skill。

---

四、架构剖析：7 层函数的职责分离

整个脚本约 800 行代码，被精心组织成 7 个功能层，共 18 个核心函数：

┌─────────────────────────────────────────────────────────┐
│ Layer 7: 主程序协调 (main)                               │
├─────────────────────────────────────────────────────────┤
│ Layer 6: 参数处理 (parseArgs, parseStatusFilter)         │
├─────────────────────────────────────────────────────────┤
│ Layer 5: 报告生成 (generateIndexReport, generateReport)  │
├─────────────────────────────────────────────────────────┤
│ Layer 4: 文件处理 (filterFiles, groupFilesByDirectory)   │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Diff 获取 (getDiffContent, buildDiffArgs)       │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Git 模式解析 (parseGitMode, getChangedFiles)    │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Git 基础操作 (getGitRoot, execGit)              │
└─────────────────────────────────────────────────────────┘

这种分层设计遵循了单一职责原则：每一层只关心自己的事情。

• Layer 1 不关心"用户想要什么模式"，它只负责"安全地执行 git 命令"
• Layer 5 不关心"diff 从哪来"，它只负责"把数据渲染成 Markdown"

这种解耦带来的好处是：如果未来需要支持新的 Git 模式（比如 stash 对比），只需要修改 Layer 2，其他层完全不受影响。

核心数据结构

文件对象——流经整个系统的基本单元：

{
  status: "M",           // A=新增, M=修改, D=删除, R=重命名
  path: "src/utils.ts",  // 文件当前路径
  oldPath: null          // 重命名时的原路径
}

目录分组映射——13 层优先级的分类规则：

const DIR_GROUPS = {
  "src/components": "src-components",
  "src/views": "src-views",
  "src/hooks": "src-hooks",
  "src/services": "src-services",
  "src/store": "src-store",
  "src/utils": "src-utils",
  "src": "src-others",
  "": "root"
};

注意这个映射的顺序：更具体的路径（如 src/components）排在前面，更通用的路径（如 src）排在后面。这确保了文件会被分配到最精确的分组。

---

五、关键算法：贪心匹配与边界处理

5.1 目录分组的贪心匹配

当一个文件路径 src/components/Button.tsx 需要被分组时，算法遍历 DIR_GROUPS 的每个规则：

检查: "src/components" → 匹配! 返回 "src-components"

这是一个贪心算法：一旦找到匹配，立即返回，不再检查后续规则。

时间复杂度: O(n × m)，其中 n = 文件数，m = 分组规则数

由于规则数是固定常量，实际复杂度接近 O(n)，非常高效。

5.2 last 模式的边界处理

last:<N> 模式需要计算"最近 N 个提交的累积变更"。核心逻辑是：

1. 获取最近 N 个 commit hash
2. 找到最老 commit 的父提交作为基准点
3. 执行 git diff <基准点>..HEAD

但这里有一个边界情况：如果最老的 commit 就是仓库的第一个提交呢？

它没有父提交，git rev-parse <hash>~1 会失败。

脚本的处理方式：

const baseRef = `${oldestCommit}~1`;
const baseCheck = execGit(["rev-parse", "--verify", baseRef], cwd);

if (baseCheck.success) {
  // 正常情况：存在父提交
  args = ["diff", "--name-status", `${baseRef}..HEAD`];
} else {
  // 边界情况：首次提交，使用 --root 参数
  args = ["diff", "--name-status", "--root", oldestCommit, "HEAD"];
}

这种显式的边界处理，是工程化代码与"能跑就行"代码的关键区别。

5.3 分批处理：避免命令行溢出

当变更文件超过 100 个时，直接把所有路径拼接到一条 git 命令中可能导致：

• 命令行参数超长
• 输出缓冲区溢出

git-diff-report 采用分批处理策略：

const batchSize = 50;  // 每批 50 个文件

for (let i = 0; i < files.length; i += batchSize) {
  const batch = files.slice(i, i + batchSize);
  const result = execGit(["diff", ...batch.map(f => f.path)], cwd);
  // 合并结果...
}

配合 50MB 的输出缓冲区配置，这套方案可以稳定处理数千个文件的大型仓库。

---

六、输出结构：从平铺到导航

传统 git diff 的输出是线性的：

diff --git a/file1.ts b/file1.ts
...
diff --git a/file2.ts b/file2.ts
...
（继续滚动 200 行）

git-diff-report 的输出是结构化的：

/docs/diffs/2026-01-15/
├── index.md                 # 汇总入口（统计 + 链接表）
├── src-components.md        # UI 组件变更
├── src-services.md          # 服务层变更
├── src-hooks.md             # Hooks 变更
├── src-utils.md             # 工具函数变更
└── root.md                  # 根目录文件

index.md 示例：

# Git Diff 变更报告

**Git 模式**: branch:main
**生成时间**: 2026-01-15 14:30:45

## 统计概览

| 类型 | 数量 |
|------|------|
| 新增文件 (A) | 5 |
| 修改文件 (M) | 12 |
| 删除文件 (D) | 2 |
| **总计** | **19** |

## 分类报告

| 目录 | 文件数 | 链接 |
|------|--------|------|
| src/components | 8 | [查看](./src-components.md) |
| src/services | 5 | [查看](./src-services.md) |

日期目录：自动积累历史

默认情况下，报告会输出到带日期的子目录：

/docs/diffs/2026-01-15/index.md
/docs/diffs/2026-01-16/index.md
/docs/diffs/2026-01-17/index.md

这样，你不仅有了当前的代码审查报告，还有了项目演变的时间线。三个月后再问"v2.0 发布前改了什么"，答案就在 2026-01-15/ 目录里。

---

七、适用边界与对比分析

7.1 适用场景

场景	推荐度	理由
PR 代码审查	高	结构化输出便于逐模块审查
发布前检查	高	last:10 快速汇总近期变更
版本对比	高	diff:v1.0..v2.0 生成完整报告
项目历史追溯	中	日期目录提供时间线
简单 diff 查看	低	原生 git diff 更快
实时 Git 操作	不适用	工具定位是报告生成

7.2 与其他方案的对比

维度	git diff	GitHub PR	git-diff-report
输出格式	终端文本	Web UI	Markdown 文件
结构化	无	按文件列表	按目录分组
持久化	无	云端存储	本地文件
离线使用	是	否	是
定制性	低	低	高（可改分组规则）
历史追溯	需手动操作	仓库存档	日期目录

7.3 与 IDE 可视化 Git 工具的对比

你可能会问：VSCode 自带的 Source Control 和 GitLens 插件不是已经能看 diff 了吗？

是的，IDE 可视化工具在交互式探索上无可比拟：

• 点击文件即可查看变更
• 行内标注显示 blame 信息
• 实时预览暂存区状态

但这些工具有一个根本性的局限：它们是瞬态的。

维度	VSCode/GitLens	git-diff-report Skill
输出形式	屏幕展示（看完即消失）	Markdown 文件（持久保存）
AI 可读性	无法被 AI 读取	Claude 可直接读取分析
跨会话上下文	每次打开重新加载	历史报告随时可查
自然语言调用	需手动点击操作	“帮我看看改了什么”
批量报告	不支持	支持按目录分组汇总
离线归档	不支持	日期目录自动积累

关键区别：AI 协作场景

当你使用 VSCode GitLens 查看 diff 时，信息只停留在你的屏幕上。但当你对 Claude 说"帮我生成一份变更报告"，git-diff-report Skill 会：

1. 自动识别你的意图（SKILL.md 定义的触发场景）
2. 执行 Git 命令并生成结构化报告
3. 将报告保存到文件，成为 AI 可读的上下文

下一次你问"上周的重构改了哪些服务？"，Claude 可以直接读取 2026-01-08/ 目录下的报告来回答——而不是你重新在 IDE 里一个个文件点开查看。

这就是 Skill 的核心价值：把人类的视觉操作，转化为 AI 可持续利用的结构化知识。

7.4 与其他开源工具的定位差异

• git-cliff / conventional-changelog：侧重于从 commit 消息生成 Changelog，不处理代码 diff
• git-diff-report：侧重于从代码变更生成结构化审查报告

两者是互补关系，不是竞争关系。

---

八、Skill 的工程洞察：从脚本到 AI 能力

回顾整个设计，有几个值得提炼的 Skill 设计思想：

8.1 SKILL.md 的设计原则

一个好的 SKILL.md 应该回答三个问题：

1. When：什么场景下应该调用这个 Skill？
2. What：Skill 能做什么，不能做什么？
3. How：具体的调用方式和参数说明

git-diff-report 的 SKILL.md 明确定义了：

• 触发场景：“生成变更报告”、“代码审查”、“版本对比”
• 6 种 Git 模式的适用场景
• 参数表格和使用示例

这让 Claude 能够自动判断何时应该调用这个 Skill，而不需要用户显式指定。

8.2 references/ 的价值

references/config-options.md 不仅是给人看的文档，更是 Claude 的扩展知识库。

当用户问"我想只看新增文件的变更"时，Claude 会：

1. 读取 SKILL.md 了解基本用法
2. 读取 config-options.md 找到 --status added 参数
3. 构建正确的命令

这就是"领域专用知识包"的含义——把专家知识结构化地提供给 AI。

8.3 策略模式在 Skill 中的价值

6 种 Git 模式通过 parseGitMode() 统一解析，通过 buildDiffArgs() 分发构建。这意味着：

• 新增模式只需添加解析规则，不影响主流程
• 每种模式的 Git 命令逻辑封装在独立的 case 中
• 用户界面保持简单统一（都是 --mode xxx）

对于 AI 来说，这种设计意味着更少的参数组合和更清晰的调用逻辑，降低了 AI 出错的概率。

8.4 边界处理的重要性

last 模式对首次提交的特殊处理、分批获取 diff、50MB 缓冲区配置——这些"边界情况"的处理，往往占据了代码量的 30% 以上。

但正是这些处理，让 Skill 从"在我机器上能跑"变成"在任何用户的仓库都能跑"——这对于 AI 自动调用的场景尤为重要。

8.5 结构化输出的长期价值

Markdown 文件不仅是"给人看的报告"，它们本身也是可版本控制的资产。

你可以：

• 把 /docs/diffs/ 纳入 Git 管理
• 在 PR 描述中引用特定日期的报告
• 对比不同时期的报告，追溯项目演变
• 让 Claude 读取历史报告，理解项目的演变脉络

---

结语

技术圈有句老话：“不要重复发明轮子。”

但有时候，轮子本身没问题，问题是缺少一个好的车架。

git diff 是一个完美的轮子——它精确、可靠、久经考验。git-diff-report Skill 不是要替代它，而是在它之上构建了一个结构化的车架，让轮子的输出能够被更好地组织、保存和复用。

更重要的是，这个车架是为 AI 设计的。通过 SKILL.md 定义触发条件，通过 references/ 提供领域知识，通过 scripts/ 执行具体操作——这三层结构让 Claude 能够像一个熟练的 Git 专家一样，根据用户的自然语言需求，自动选择正确的模式、传入正确的参数、生成正确的报告。

这就是 Claude Code Skill 的本质：不是创造新能力，而是把专家知识编码为 AI 可调用的领域能力包。

当你下一次对 Claude 说"帮我生成一份代码变更报告"时，背后运行的就是这样一套精心设计的系统。从混沌到秩序的距离，可能只是一句自然语言。

---

参考资料

1. git-diff-report Skill 源码：~/.claude/skills/git-diff-report/
2. Claude Code Skill 开发指南
3. Gang of Four. (1994). Design Patterns: Elements of Reusable Object-Oriented Software
4. Git 官方文档：git-diff, git-show, git-log