AGENT SKILL

codebase-recon

Use when entering an unfamiliar codebase, onboarding to a new project, or wanting to assess codebase health before reading code — analyzes git history to reveal hotspots, risk areas, team structure, and development momentum

适用职业开发工程师
License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
codebase-recon
metadata
{ "author": "yujiachen-y", "version": "1.0", "inspired-by": "https://piechowski.io/post/git-commands-before-reading-code/" }
description
Use when entering an unfamiliar codebase, onboarding to a new project, or wanting to assess codebase health before reading code — analyzes git history to reveal hotspots, risk areas, team structure, and development momentum
compatibility
Requires git. Works in any terminal-based coding agent.

03 SKILL.md 正文

Codebase Recon

Analyze git history to understand a codebase before reading any code. Reveals project health, risk areas, team structure, and development momentum.

Inspired by "The Git Commands I Run Before Reading Any Code" by Ally Piechowski.

Phase 1: Probe

Before running analysis, determine repo scale to calibrate time windows and result counts.

Run this single shell command to collect repo vitals:

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 ' ')"

Use the commit count to set parameters for Phase 2:

Repo Size Commits WINDOW (--since) N (--head)
Small <500 (omit --since) 10
Medium 500-10k 1 year ago 20
Large >10k 6 months ago 30

Print the Repo Vitals line immediately:

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

Phase 2: Parallel Analysis

Run all 7 commands in parallel (they are independent). Substitute WINDOW and N from Phase 1. For small repos, omit --since flags entirely.

2a. Code Hotspots

Most-changed files in the analysis window:

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

2b. Bus Factor

All-time contributor ranking by commit count:

git shortlog -sn --no-merges

2c. Bug Magnets

Files most associated with bug-fix commits:

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

2d. Team Momentum

Commit frequency by month (all time):

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

2e. Firefighting Frequency

Emergency/revert commits in the analysis window:

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

2f. Recently Added Files

New files added in the analysis window:

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

2g. Active vs Total Contributors

Count of contributors active in the last 3 months (fixed window — measures "who's here now"):

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

Compare this count against the total from 2b.

Cross-Referencing

After collecting all Phase 2 results, perform these cross-references before presenting the report:

  1. High-Risk Files: Intersect code hotspots (2a) with bug magnets (2c). Files appearing in both lists are highest-risk.
  2. Risk Ownership: For each high-risk file, run git shortlog -sn -- <file> to identify the primary owner.
  3. Bus Factor Risk: If active contributors (2g) are less than 30% of total contributors (2b), flag this as a bus factor concern.
  4. Momentum Trend: Analyze the monthly commit counts (2d):
    • Compare the average of the last 3 months to the average of the 3 months before that.
    • Rising: last 3 months average > prior 3 months average by 20%+
    • Declining: last 3 months average < prior 3 months average by 20%+
    • Erratic: month-over-month variance exceeds 50%
    • Stable: otherwise

Report Template

Present the report in the terminal using this structure:

═══ 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]

After printing the report, ask:

"Want me to save this report to a markdown file? (e.g., docs/codebase-recon-report.md)"

If yes, write the same content as a markdown file. Do not commit — let the user decide.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k