# Codebase Audit

> Audit and map a codebase to understand structure, dependencies, and risks. Use when the user asks to audit a repo, understand architecture, or assess codebase quality or health.

- Skill: `majiayu000/codebase-audit-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/codebase-audit-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/codebase-audit-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/codebase-audit-3

---


# Codebase Audit

## Overview
Create a fast, evidence-based map of the repo and highlight risk and quality hotspots.

## Inventory
1. List top-level structure (use `ls`, `tree -L 3`, `rg --files`).
2. Identify entry points (search for `main`, CLI, or service starts).
3. Capture dependency manifests (pyproject, package.json, requirements, go.mod).

## Required Tool Pass (must run all tools)
Run every tool below and log its output. If any tool is missing, invoke action-gate to install it and block the audit until the full tool pass is complete.
- Use OS-appropriate installers via action-gate (apt/dnf/yum/pacman/brew/choco/scoop) and retry.
- `rg` for search and inventory.
- `tree -L 3` for structure.
- `tokei` (or `scc` or `cloc`) for LOC; choose one and run it.
- `ctags` or a tree-sitter indexer for symbol maps; choose one and run it.
- `git log --stat` for hotspots (if repo has history).
- `repomap` for a scoped module summary (install if missing).
- `repomix` for a full-repo map with ignores applied (install if missing).
- Jina embeddings tooling for semantic clustering or duplication hints (install/configure if missing). If API key is required, stop and request it.

## Repomap Scope Rules (required)
- Do not run repomap on the full repo if it times out; run it on scoped code folders (`scripts/`, `skills/`, and other non-JS/JSX code dirs).
- If repomap throws tree-sitter query errors for JS/JSX, skip those folders and rely on `ctags` for symbol mapping.
- If a target folder lacks `.gitignore`, create a minimal `.gitignore` in that folder before running repomap.

## Repomix Rules (required)
- Use repomix for the full-repo map and ensure `node_modules/` and large data dirs are ignored.
- Prefer a local `repomix.config.json` or `.repomixignore` if present; otherwise, generate one (`repomix --init`) and add ignore patterns.
- Record the output file path and style used (markdown/json/plain).

## Long-Run Handling
- If a tool is slow, use `timeout` or run under `tmux`/`nohup` to avoid session loss. Do not treat this as a fix for tool errors.

## Risk and Quality Checks
- Large files, high churn areas, and untested modules.
- Security and PII paths, data flow, and external integrations.
- Configuration, environment assumptions, and hidden dependencies.

## Output
- Module map, key flows, and hotspots.
- Findings with severity and suggested next steps.
- Open questions to confirm architecture or intent.
- Note which tools were run vs unavailable.

## Acceptance Criteria
- Full tool pass completed with outputs captured.
- Any missing tool is reported and blocks the audit until resolved.
- Environment-specific install commands are documented when blockers occur.
- Repomap outputs are produced for scoped folders, and repomix output is produced for the full repo.