codebase-recon

代码库侦察

在阅读代码之前，分析 Git 历史，了解代码库。这有助于揭示项目健康状况、风险区域、团队结构和开发势头。

灵感来自 Ally Piechowski 的文章 “The Git Commands I Run Before Reading Any Code”。

阶段 1：探查

运行分析之前，先确定仓库规模，以便校准时间窗口和结果数量。

运行以下单条 shell 命令，收集仓库概况：

echo "COMMITS=$(git rev-list --count HEAD)" && \
echo "FIRST_COMMIT=$(git log --reverse --format='%ad' --date=short | head -1)" && \
echo "LATEST_COMMIT=$(git log --format='%ad' --date=short | head -1)" && \
echo "BRANCHES=$(git branch -a | wc -l | tr -d ' ')"

根据提交数量设置阶段 2 的参数：

仓库规模	提交数	WINDOW（--since）	N（--head）
小型	<500	（省略 --since）	10
中型	500-10k	1 year ago	20
大型	>10k	6 months ago	30

立即打印仓库概况行：

Repo Vitals: Age: [FIRST_COMMIT to LATEST_COMMIT] | Commits: [COMMITS] | Branches: [BRANCHES] | Analysis window: [WINDOW or "all time"]

阶段 2：并行分析

并行运行全部 7 条命令（它们彼此独立）。替换阶段 1 中的 WINDOW 和 N。对于小型仓库，完全省略 --since 标志。

2a. 代码热点

分析时间窗口内变更最多的文件：

git log --format=format: --name-only --since="WINDOW" | sort | uniq -c | sort -nr | head -N

2b. 巴士因子

按提交数量排列的历史贡献者排名：

git shortlog -sn --no-merges

2c. Bug 磁铁

与修复 bug 的提交关联最多的文件：

git log -i -E --grep="fix|bug|broken" --name-only --format='' --since="WINDOW" | sort | uniq -c | sort -nr | head -N

2d. 团队势头

按月统计提交频率（历史全部时间）：

git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c

2e. 救火频率

分析时间窗口内的紧急提交／回滚提交：

git log --oneline --since="WINDOW" | grep -iE 'revert|hotfix|emergency|rollback'

2f. 最近新增的文件

分析时间窗口内新增的文件：

git log --diff-filter=A --since="WINDOW" --name-only --format='' | sort | uniq -c | sort -nr | head -N

2g. 活跃贡献者与贡献者总数

统计过去 3 个月内活跃的贡献者数量（固定时间窗口，用于衡量“现在有哪些人”）：

git shortlog -sn --no-merges --since="3 months ago" | wc -l

将此数量与 2b 中的总数进行比较。

交叉比对

收集完阶段 2 的所有结果后，在提交报告之前进行以下交叉比对：

1. 高风险文件：求代码热点（2a）与 Bug 磁铁（2c）的交集。出现在两个列表中的文件风险最高。
2. 风险归属：对于每个高风险文件，运行 git shortlog -sn -- <file> 以确定主要负责人。
3. 巴士因子风险：如果活跃贡献者（2g）少于贡献者总数（2b）的 30%，则标记为巴士因子隐患。
4. 势头趋势：分析每月提交数量（2d）：
   • 比较最近 3 个月的平均值与此前 3 个月的平均值。
   • 上升：最近 3 个月的平均值比此前 3 个月高 20% 以上
   • 下降：最近 3 个月的平均值比此前 3 个月低 20% 以上
   • 波动：逐月变化幅度超过 50%
   • 稳定：其他情况

报告模板

在终端中按以下结构呈现报告：

═══ Codebase Recon Report ═══

Repo Vitals
  Age: [first commit] to [latest commit] | Commits: N | Branches: N | Analysis window: WINDOW

1. Code Hotspots (most-changed files)
   [ranked list: count  filepath]

2. Bug Magnets (files with fix/bug/broken commits)
   [ranked list: count  filepath]

3. High-Risk Files (appear in BOTH hotspots AND bug magnets)
   [list with: filepath — hotspot rank #X, bug magnet rank #Y, primary owner: NAME]
   If none overlap, state: "No files appear in both lists — good sign."

4. Bus Factor
   [top 10 contributors: count  name]
   Active (last 3 months): X of Y total contributors
   [If active < 30% of total: "Warning: low active contributor ratio — knowledge concentration risk"]

5. Team Momentum
   [monthly commit counts, most recent 12 months or all if fewer]
   Trend: [rising / stable / declining / erratic]

6. Firefighting Frequency
   [list of revert/hotfix/emergency commits, or "None found"]
   Rate: N emergency commits out of M total in window (X%)

7. Recently Added Files
   [ranked list: count  filepath]

8. Recommendations
   - Start reading: [top 3 high-risk files, or top 3 hotspots if no high-risk files]
   - Talk to: [primary owner of the #1 high-risk or hotspot file]
   - Watch out: [any trend warnings — declining momentum, low bus factor, high firefighting rate]

打印报告后，询问：

“要我将此报告保存为 Markdown 文件吗？（例如，docs/codebase-recon-report.md）”

如果用户同意，将相同内容写入 Markdown 文件。不要提交更改——由用户决定。