codebase-recon

コードベースの調査

コードを読む前に、Git の履歴を分析してコードベースを理解します。プロジェクトの健全性、リスクの高い領域、チーム構成、開発の勢いを明らかにします。

Ally Piechowski による「コードを読む前に実行する Git コマンド」に着想を得ています。

フェーズ 1：調査

分析を実行する前に、リポジトリの規模を確認し、対象期間と結果件数を調整します。

次のシェルコマンドを 1 つ実行して、リポジトリの基本情報を収集します。

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. バグを引き寄せるファイル

バグ修正コミットと最も関連しているファイル：

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）とバグを引き寄せるファイル（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 ファイルとして書き込みます。コミットはしないでください。判断はユーザーに委ねます。