---
name: git-codebase-diagnosis
description: |
  对 Git 仓库进行快速健康诊断，在阅读代码之前先了解代码库的整体状况。
  当用户提到"代码库诊断"、"代码库体检"、"代码库健康检查"、"codebase diagnosis"、"codebase audit"、
  "分析代码库"、"了解代码库"、"代码库概况"、"仓库分析"、"git 分析"、"git 诊断"、
  "谁写的代码"、"哪些文件改动最多"、"bug 集中在哪里"、"项目是否健康"时使用此 skill。
  也适用于用户刚接手一个新项目、想快速了解代码库现状的场景。
---

# Git 代码库诊断

在阅读任何一个代码库之前，通过 Git 提交历史对代码库进行快速"体检"。这个技能基于 Ally Piechowski 的文章 *The Git Commands I Run Before Reading Any Code* 整理而来，用 5 个维度帮你快速了解一个代码库的健康状况。

## 适用场景

- 刚接手一个新项目，想快速了解代码库全貌
- 对项目进行审计 (audit) 或评估
- 想找出代码库中风险最高的文件
- 想了解团队的协作健康度

## 前置条件

- 当前目录必须是一个 Git 仓库
- 仓库需要有足够的提交历史（至少几个月）才能得出有意义的结论

## 诊断流程

运行 `scripts/diagnose.sh` 脚本收集所有原始数据，然后对结果进行分析和解读。

```bash
bash <skill-path>/scripts/diagnose.sh
```

脚本会依次执行以下 5 项检查，并将结果输出到终端。

### 1. 变更热点 (Churn Hotspots)

找出过去一年中改动最频繁的 20 个文件。

排在前面的文件通常就是团队里大家"都怕碰"的那个。高频变更本身不是问题——活跃开发自然会带来高变更率。真正的风险信号是：一个文件频繁变更，但没人愿意认领它，每次修改都是补丁摞补丁，改动的影响范围难以预测。

分析时重点关注：
- 前 5 名文件是否也出现在 Bug 聚集区（第 3 项）中——同时高变更 + 高 Bug 的文件是最大的单点风险
- 是否有配置文件或锁文件排在前面（这通常是正常的，可以忽略）

### 2. 贡献者分布 (Bus Factor)

按提交数量排名所有贡献者，评估"巴士因子"——如果关键人物突然离开，项目会不会陷入危机。

分析时重点关注：
- 如果一个人占了 60% 以上的提交，巴士因子很低
- 对比总体贡献者和近 6 个月活跃贡献者——如果头号贡献者近期已经不活跃了，这是一个严重的风险信号
- 注意尾部：如果总共有 30 个贡献者但最近一年只有 3 个活跃，说明"写代码的人"和"维护代码的人"已经不是同一批了
- **注意事项**：如果团队使用 squash-merge 工作流，提交作者反映的是谁点了合并按钮，而非谁真正写的代码

### 3. Bug 聚集区 (Bug Clusters)

找出 Bug 相关提交（包含 fix、bug、broken 等关键词）集中的文件。

分析时重点关注：
- 与变更热点交叉对比——同时出现在两个列表中的文件是最高风险：反复出 Bug、反复打补丁，但从未被真正修好
- 这个分析依赖于团队的提交信息规范。如果大家都写"update stuff"之类的信息，结果会不准确。即便如此，一张粗略的 Bug 密度地图也比没有强

### 4. 项目趋势 (Project Momentum)

按月统计提交数量，判断项目是在加速还是衰退。

分析时关注数据的"形状"：
- **稳定节奏**：健康信号
- **某个月骤降一半**：通常意味着有人离开了
- **持续 6-12 个月下滑**：团队正在失去动力
- **周期性尖峰 + 沉寂**：团队在攒一批功能集中发版，而非持续交付

这是团队数据，不是代码数据——代码本身不会告诉你这些。

### 5. 救火频率 (Crisis Patterns)

统计过去一年中 revert、hotfix、emergency、rollback 相关的提交。

解读方式：
- **一年几次**：正常
- **每隔几周就有一次**：团队不信任自己的部署流程，背后可能是测试不可靠、缺少预发环境、或部署流水线让回滚变得太难
- **零结果**：要么团队确实很稳定，要么没人在提交信息里写描述性关键词

危机模式一目了然——有就是有，没有就是没有。

## 输出格式

完成所有 5 项检查后，输出一份结构化的诊断报告：

```markdown
# 代码库诊断报告

## 概览
- 仓库名称：...
- 诊断时间：...
- 总提交数：...
- 总贡献者数：...
- 仓库历史跨度：...

## 1. 变更热点
[列出前 10 名文件及变更次数，标注哪些同时出现在 Bug 聚集区]

## 2. 贡献者分布
[列出主要贡献者，标注巴士因子风险等级]

## 3. Bug 聚集区
[列出前 10 名文件，标注与变更热点的交叉]

## 4. 项目趋势
[描述提交频率的变化趋势，给出判断]

## 5. 救火频率
[统计数量，给出评估]

## 综合评估
[基于以上 5 个维度的综合判断，指出最需要关注的 2-3 个风险点，
以及建议优先阅读的文件列表]
```

## 注意事项

- 这 5 个命令只需要几分钟，不会告诉你一切，但能帮你知道该先读哪些代码、读的时候该找什么
- 诊断结果是"体检报告"而非"确诊书"——它指出可能的问题区域，具体判断仍需结合代码本身
- 对于历史很短（< 3 个月）的仓库，部分指标可能不够有意义