# Codebase Audit

> Use when asked to investigate, deep-dive, audit, review, or assess a codebase/repo/project for bugs, issues, security gaps, infrastructure risks, optimization opportunities, or unwired/dead/partially-implemented code. Triggers on "investigate the X codebase", "audit/review the repo", "find bugs/security issues", "what's broken/risky in X", "dead code", "infra risks", "deep-dive the code". READ-ONLY: produces a structured report, makes NO edits. This is the code/security/infra analog of frontend-audit (which is visual-only).

- Skill: `oimiragieo/codebase-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/codebase-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/codebase-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/codebase-audit

---


# Codebase Audit Skill

Run a **read-only**, token-disciplined deep-dive of a codebase and produce ONE structured
report — bugs, security gaps, infrastructure risks, unwired/dead/partial code, and
optimizations — each finding ranked by severity and cited to `file:line` or the grep
pattern that surfaced it. **Security and infrastructure are the highest-priority areas
unless the caller says otherwise.**

The goal is **maximum insight per token**, not a file-by-file recital. The efficiency rules
below are load-bearing — applied ruthlessly, they let one pass cover a large repo without
blowing the budget. (Phase-2 claude-code hooks enforce rules 1 & 3 mechanically; until then
they are a hard discipline you self-enforce.)

## When to use
- "investigate / deep-dive / audit / review the <project> codebase"
- "find bugs / security issues / infra risks / dead code in <repo>"
- "what's broken, risky, or half-finished here?"
- Pre-merge or pre-handoff assessment of an unfamiliar repo.

## When NOT to use
- **Making the fixes** — this skill only REPORTS. Hand findings to an implement loop after.
- **Visual/UX/CRO review** — use `frontend-audit`.
- **A single known bug** — just debug it; don't audit the whole repo.

## Inputs / parameters
- **repo** (required): the working directory to audit (the agent runs IN this cwd).
- **focus** (optional): risk areas to emphasize (default: all five categories).
- **priority** (optional): which categories rank highest (default: Security, Infrastructure).
- Always **read-only**. Never edit, never run mutating commands.

## RULE 1 — Token discipline (HIGHEST priority)
- **Never read the same file twice.** Track what you've read; if you feel the urge to
  re-open a file, STOP and synthesize from what you already have.
- **Never read build/generated dirs:** node_modules, .next, dist, build, __pycache__,
  .pytest_cache, .venv, vendor, target, coverage, lockfile internals.
- **Prefer Grep (with head_limit) and Glob over listing a directory + reading files.**
- When you do read a file, use offset + limit — read the relevant span, not the whole file,
  unless it is genuinely small or you genuinely need all of it.
- **Read CLAUDE.md / SKILLS-INDEX.md / README.md for a directory FIRST** — they often
  replace opening a dozen source files.

## RULE 2 — Strategy (follow this order)
1. **Root config + governance only, first:** the deploy/runtime/dependency manifests for the
   stack (Dockerfile, docker-compose.yml, fly.toml, vercel.json, requirements.txt /
   pyproject.toml, package.json, CI workflows) + every CLAUDE.md. These define the attack
   surface, the infra, and the conventions in a handful of reads.
2. **Broad Grep sweeps for the risk areas** (see RULE 4's pattern bank) — security, infra,
   TODO/FIXME/HACK, unwired features, silent-failure patterns, auth/rate-limit/webhook gaps.
   Let the grep hits point you to high-signal files.
3. **Drill into a specific file ONLY when grep or a CLAUDE.md flags it** as high-signal.
4. **Any directory with >20 files -> Grep/Glob first.** Never list-and-read-everything.

## RULE 3 — Anti-waste hard constraints
- Do **not** list or walk generated/build dirs (RULE 1's list).
- Do **not** re-read a file you have already read, even when a "different" angle tempts you.
- Do **not** run the full test suite, builds, installs, or anything mutating — read-only.
- If grep already answered the question, do **not** open the file to "confirm."

## RULE 4 — Risk pattern bank (grep starting points; adapt to the stack)
- **Security:** code-eval / dynamic-exec calls, pickle/deserialization, subprocess or
  child_process with shell enabled, dangerouslySetInnerHTML, raw SQL string concatenation,
  TLS verification disabled, hardcoded secret|token|api[_-]?key|password, non-constant-time
  token compares, permissive CORS `*`, routes missing auth/middleware, JWT alg:none.
- **Infrastructure:** unpinned deps / `latest` tags, 0.0.0.0 binds, missing healthchecks, no
  resource limits, secrets committed in env files, single-replica stateful services, missing
  retries/timeouts on outbound calls, unbounded queues/caches (OOM), missing rate limits.
- **Unwired / dead / partial:** TODO|FIXME|HACK|XXX|WIP|"not implemented"|stub|placeholder,
  exported symbols with zero importers, routes defined but never registered, feature flags
  that gate nothing, env vars read-but-never-set (or set-but-never-read).
- **Silent failures:** bare except / except Exception: pass, empty catch blocks, swallowed
  promise rejections, ignored return codes, blanket lint-disable, error logged-not-raised.
- **Bugs:** off-by-one, missing await, mutable default args, races on shared state,
  unhandled None/undefined, resource leaks (unclosed files/connections).

## RULE 5 — Output contract
Produce **ONE final structured report** at the end. **No running commentary, no file-by-file
narration, no "reading X..." play-by-play.** Organize by category, severity-ranked within:

    # Codebase Audit — <repo>   (read-only; no edits made)

    ## Security            [highest priority]
    - [CRITICAL] <finding> — path/file.py:120-134   (or: surfaced by grep <pattern>)
    - [HIGH] ...
    ## Infrastructure      [highest priority]
    ## Bugs & Issues
    ## Unwired / Dead / Partial Code
    ## Optimizations

    ## Summary
    - N findings: X critical, Y high, Z medium. Top 3 to fix first: ...
    - Coverage note: what was sampled vs exhaustively read (be honest about gaps).

Severities: **CRITICAL** (exploitable / data-loss / outage), **HIGH**, **MEDIUM**, **LOW**.
Every finding MUST cite file:line-range OR the grep pattern that surfaced it. No finding
without evidence — if you cannot cite it, you did not verify it; drop it or mark it
UNVERIFIED and say which read would confirm it.

## Ultrathink, but ruthlessly efficient
Think hard about systemic risk and what the code is *not* doing — but obey RULES 1 & 3
without exception. A re-read or a node_modules walk is a budget leak; the discipline IS the
skill. Maximum insight per token.