A principal-engineer-grade repository audit, tuned for Claude's latest models running inside Claude Code.
It maps the repo, fans out parallel subagents (one per audit dimension, plus git-history mining for churn × complexity hotspots), adversarially verifies every Critical/High finding against the actual code before reporting it, runs the repo's own lint/type-check/test commands instead of guessing at health, and writes a single AUDIT.md containing:
Executive Summary — health grade A–F, top 3 risks, top 3 opportunities
Repo Map
Severity-rated findings (file:line cited, facts separated from judgments)
Improvement strategy — the 3–5 themes behind the findings, with measurable "done" signals
A milestone-ordered task plan where each task is a self-contained brief a fresh agent session can execute, with runnable acceptance criteria
Quick wins flagged separately
Read-only: it never modifies your code. The report is the only file it creates.
Install — user-wide (available in every repo)
mkdir -p ~/.claude/commands
curl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o ~/.claude/commands/repo-audit.md
Open a new Claude Code session and run /repo-audit.
Install — single project only
mkdir -p .claude/commands
curl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o .claude/commands/repo-audit.md
Install — manual
Copy the contents of repo-audit.md from this gist into ~/.claude/commands/repo-audit.md. That's it — Claude Code picks up the file automatically.
Usage
/repo-audit
Pass an optional focus: /repo-audit security or /repo-audit src/billing.
Run it in normal mode, not plan mode. The audit is read-only; plan mode inserts an approval stop that costs you nothing but waiting.
For very large repos where you want maximum depth, opt into multi-agent orchestration explicitly: /repo-audit use a workflow (or include the word ultracode).
The audit runs end to end without check-ins — it's read-only and safe to leave running.
Output lands in AUDIT.md at the repo root, written for a reader who didn't watch the run.
Why this version
This is a rework of the viral "Repo Audit & Improvement Plan" prompt, restructured around how current Claude models actually work best:
Purpose over persona — states why the audit exists (the report becomes a work queue for future agent sessions) instead of role-playing a "world-class engineer".
Orchestrated, not single-threaded — parallel subagents per dimension instead of one linear pass.
Verified, not just cited — fresh-context subagents try to refute each Critical/High finding; what doesn't survive gets dropped or downgraded. Claims are checked against actual tool output (including really running the test suite) before they enter the report.
History-aware — mines git history for bug-fix-dense, high-churn files instead of auditing a frozen snapshot.
Agent-executable output — tasks have runnable pass/fail acceptance criteria, so you can hand each one straight to a new Claude Code session.
Principal-level repo audit → evidence-verified findings → agent-executable task plan
argument-hint
optional focus — a subdirectory
dimension
or concern
Repo Audit & Improvement Plan
Context — why this audit exists
I maintain multiple products solo and don't have time to review tech debt by hand. Your audit becomes the work queue for future Claude Code sessions: each task you produce will be handed to a fresh agent with no other context. Audit accordingly — truth over reassurance; a flattering report is worthless to me.
Audit focus for this run, if any: $ARGUMENTS
Ground rules
Every finding cites file:line you actually read this session. If you can't verify a claim, label it unverified — never guess. Before writing the final report, check each claim against a tool result from this session.
Analysis only. Do not modify code, config, or dependencies. The only file you create is the report.
Don't just read claims of health — observe them. Run the repo's own read-only commands (install, lint, type-check, test suite, dependency audit) where practical, and report outcomes faithfully: if the tests fail, say so with the output.
Calibrate to the project's maturity — don't demand enterprise rigor of a prototype. If the repo is large, go deep on the core 20% that does 80% of the work, and say what you skipped.
Prefer 15 high-confidence findings over 50 speculative ones. Separate facts from judgments. If a dimension is healthy, say so in one sentence and move on. List genuine strengths too — they tell me what to protect.
How to work
If you were launched in plan mode, every decision is already made here: your plan is one line ("run this audit as specified") — submit it for approval immediately.
Fan out parallel subagents: Explore agents for discovery first, then one auditor per audit dimension, spawned as a single parallel batch and each handed the repo map so it doesn't re-derive it. Keep synthesizing while they run.
If a repo tool (pnpm, yarn, a linter) is missing from PATH, try corepack or version-manager shims (mise, asdf, nvm) before concluding it's absent.
Plain subagents (the Agent tool) are the right default: you keep synthesizing, steering refuters, and re-verifying citations between waves. Only if my invocation says "use a workflow" or "ultracode" should you script the fan-out with the Workflow tool instead — treat those words as orchestration opt-in, not as an audit focus.
Mine git history, not just the snapshot: high-churn × high-complexity files, bug-fix-dense modules, abandoned directories, the age of TODO/FIXME comments.
Adversarial verification: before any Critical or High finding enters the report, a fresh-context subagent must try to refute it against the actual code. Drop or downgrade findings that don't survive.
Work end to end without checking in — this is read-only and safe. When you have enough information to act, act.
Phase 1 — Discovery (read before judging)
Map: purpose and intended users, stack and runtime targets, entry points, core modules, main data/control flow, build/CI/env config, existing conventions (so recommendations fit the culture, not fight it), maturity level. Output a concise Repo Map, including anything that surprised you.
Each finding: what, where (file:line), why it matters, severity (Critical/High/Medium/Low), confidence, fact-or-judgment.
Phase 3 — Improvement strategy
The 3–5 themes that explain most findings; target state and the principle behind it per theme; what you are NOT fixing and why (effort vs payoff); "done" defined as measurable signals (e.g. "CI fails on lint errors", "core-path coverage ≥ 80%").
Phase 4 — Task plan
Discrete tasks a fresh Claude Code session can execute from the brief alone: title, one context paragraph, files affected, acceptance criteria as runnable checks wherever possible (a command that passes or fails), effort (S <2h, M half-day, L 1–2 days, XL needs breakdown), risk, dependencies. Order into milestones:
M0 — Safety net: tests around critical paths, CI gates
M1 — Critical fixes: security and correctness
M2 — High-leverage: changes that make all future work easier
M3 — Quality & polish
Flag quick wins (high impact, S effort) separately. Include implementation sketches for the top 3 tasks.
Deliverable
Write one file, AUDIT.md, at the repo root. Open it with the audited commit SHA, the date, and a one-paragraph method note ending in the refuter tally (findings refuted outright / downgraded / survived). Then: Executive Summary (health grade A–F, top 3 risks, top 3 opportunities) → Repo Map → Audit Report (worst first) → Improvement Strategy → Task Plan → Open Questions (each naming the decision I need to make).
Write it for a reader who didn't watch you work: lead with the outcome, complete sentences, spell out terms, no working shorthand. Don't pad — be selective about what you include, don't compress the writing.