# Code Audit > Comprehensive codebase quality audit using parallel agents. Checks DRY, SRP, anti-slop, naming, file organization, type safety, error handling, patterns, dead code, architecture, and reusability. Produces findings report + fix plan for multi-agent execution. Use when the user wants to audit code quality, review architecture, check for smells, or says "code audit", "quality check", "review codebase". NOT for a slop-only pass on named files (anti-slop) and not when the user is unsure which audit fits (audit-toolkit routes). - Skill: `b4r7x/code-audit` (Agent Skill) - Install (CLI): `npx skillmds@latest add b4r7x/code-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/code-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: b4r7x (https://skillmd.com/u/b4r7x) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/b4r7x/code-audit --- # Code Audit Comprehensive codebase quality audit using parallel explore agents. Always checks everything. Agent count and scope are user-controlled. ## Arguments Parse the user's input for: - **Agent count** (required) -- how many parallel explore agents to launch. The user provides this number. - **Scope** (optional) -- one of: - `full` (default) -- entire codebase - `changed` -- only files changed since last commit (`git diff --name-only HEAD`) - `staged` -- only staged files (`git diff --cached --name-only`) - `branch` -- files changed on current branch vs main (`git diff --name-only main...HEAD`) - `` -- specific directory or glob pattern (e.g. `src/engine/`) If the user provides just a number, use `full` scope. If they provide a path, use that as scope. Examples: - `/code-audit 10` -- 10 agents, full codebase - `/code-audit 5 changed` -- 5 agents, only changed files - `/code-audit 15 src/engine/` -- 15 agents, only engine directory - `/code-audit 3 branch` -- 3 agents, files changed on current branch ## Workflow Execute all phases in strict order. Do not skip phases. ### Phase 1 -- Understand the Project Before launching agents, gather project context: 1. Read `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or equivalent project instruction files 2. Read `package.json` (or equivalent manifest) for tech stack 3. Run `find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git | head -30` for structure overview 4. Check `git log --oneline -5` for recent activity Extract: - **Tech stack** (language, framework, test runner, linter) - **Project conventions** (from CLAUDE.md -- e.g. "zero classes", "ESM imports", "zero memoization", "colocated tests") - **Architecture pattern** (monorepo, feature-based, layer-based, etc.) This context is passed to every agent in Phase 2. ### Phase 2 -- Resolve Scope Based on the scope argument, produce a concrete file list: ``` full -> all source files (exclude node_modules, dist, .git, lockfiles, generated) changed -> git diff --name-only HEAD staged -> git diff --cached --name-only branch -> git diff --name-only main...HEAD (or master) -> glob expand the path ``` Count the files. This determines how to distribute work across agents. ### Phase 3 -- Distribute and Launch Explore Agents Split the work across N agents (the user's requested count). Each agent gets: 1. **A subset of files or a focus area** -- distribute evenly by file count or by logical grouping (directory, feature area) 2. **The full project context** from Phase 1 (tech stack, conventions, architecture) 3. **The complete audit checklist** (below) **Agent distribution strategy:** - If N <= 5: assign each agent a broad area (e.g. "core/", "engine/", "components/", "hooks+stores", "utils+ui") - If N <= 15: assign by feature/module (e.g. "orchestrator", "implementers", "planners", "config", "pickers", etc.) - If N > 15: assign by individual file groups (3-8 files per agent) plus dedicated cross-cutting agents **Always reserve at least 2 agents for cross-cutting analysis** (regardless of N): - 1 agent for **DRY analysis** -- search for duplicate patterns across the ENTIRE scope, not just its assigned files - 1 agent for **Architecture/SRP analysis** -- check module boundaries, import graph, file placement, naming consistency **Agent prompt template:** Each explore agent receives this prompt structure: ``` You are auditing code quality in [project name] at [project path]. Project context: - Tech stack: [from Phase 1] - Conventions: [from Phase 1] - Architecture: [from Phase 1] Your assigned files: [file list] Read each file and evaluate against the FULL audit checklist below. Report findings with specific file:line references and severity (critical/high/medium/low). Group findings by category. Be thorough but only flag real issues -- no false positives. [Full audit checklist -- see below] ``` Before launching, print one line the user can sanity-check: `N agents × M files (scope: X) — launching`. Then launch ALL agents in a single message (parallel). Use `subagent_type: "Explore"` with the strongest model available on the platform (never hardcode a model id — resolve it at run time). ### Phase 4 -- Synthesize Findings After ALL agents complete: 1. Collect all findings from all agents 2. Deduplicate (different agents may flag the same issue) 3. Sort by severity: critical > high > medium > low 4. Group by category (DRY, SRP, anti-slop, naming, etc.) 5. For each finding, include: - **Category** (DRY, SRP, naming, etc.) - **Severity** (critical/high/medium/low) - **Location** (file:line) - **Description** (what's wrong) - **Suggested fix** (brief, actionable) **Do NOT bloat the main context with raw agent output.** Synthesize into a concise findings report. Present the findings to the user. Ask: - "Do you want me to create an execution plan for fixing these?" (default: yes) - If the user has specific comments or disagreements, incorporate them ### Phase 5 -- Generate Fix Plan If the user approves, create a structured fix plan: 1. **Group fixes into independent batches** -- fixes that touch non-overlapping files can run in parallel 2. **Order batches by dependency** -- moves/renames before DRY extractions before component refactoring 3. **For each batch, define agent instructions** -- what files to modify, what specifically to change 4. **Include verification step** -- run tests + typecheck + lint after each batch Write the plan to the plan file (if in plan mode) or present inline. **Plan structure:** ```markdown # Code Audit Fix Plan ## Context [Why this audit was run, scope, findings summary] ## Phase N: [Batch Name] (X parallel agents) **Agent 1 -- [focus]:** - [file:line] -- [specific change] - [file:line] -- [specific change] **Agent 2 -- [focus]:** - ... ### Verification npm test && npm run typecheck && npm run lint ``` ### Phase 6 -- Execute (if approved) If the user approves the plan, execute it: 1. Launch agents for each phase/batch in parallel (using the plan's agent instructions) 2. After each batch, verify: tests + typecheck + lint 3. If verification fails, fix before proceeding 4. Report results after each batch 5. Final comprehensive verification after all batches complete --- ## Audit Checklist Every agent checks ALL of these against its assigned files. Cross-cutting agents check items marked with [cross-cutting] across the full scope. ### 1. DRY -- Don't Repeat Yourself [cross-cutting] - [ ] Duplicate or near-duplicate functions across files - [ ] Copy-pasted logic between similar modules - [ ] Repeated type definitions or interfaces - [ ] Similar error handling patterns that could be unified - [ ] Duplicate string constants or magic values - [ ] Same validation/guard pattern repeated 3+ times - [ ] Re-export chains that add unnecessary indirection (consumers should import from source) ### 2. SRP -- Single Responsibility [cross-cutting] - [ ] Files doing too many things (>200 lines is a smell, not a rule) - [ ] Functions with "and" in their description - [ ] Modules mixing concerns (e.g. I/O + validation + transformation in one file) - [ ] God components that wire too many things together - [ ] Grab-bag utility files with unrelated functions ### 3. KISS -- Keep It Simple - [ ] Clever code that a junior dev can't understand in 30 seconds - [ ] Nested ternaries (>2 levels) where early returns or helpers would be clearer - [ ] Complex generic types where a simpler type would suffice - [ ] Abstractions that obscure rather than clarify - [ ] Multiple indirection layers (A re-exports B which re-exports C) - [ ] Overly generic APIs when only one use case exists - [ ] Conditional logic that could be replaced by a lookup table or map ### 4. YAGNI -- You Aren't Gonna Need It - [ ] Configuration options for hardcoded values that will never change - [ ] Feature flags or extensibility hooks with zero consumers - [ ] Helper functions used in exactly one place that could be inlined - [ ] Wrapper functions that just pass arguments through - [ ] Abstract base classes/factories for a single implementation - [ ] "Pluggable" architecture with only one plugin - [ ] Parameters that are always passed the same value ### 5. Over-Engineering & Premature Abstraction - [ ] Factory pattern for 1-2 variants (just use if/switch) - [ ] Generic utility extracted for 1-2 call sites (inline until 3rd) - [ ] Abstraction layers that add indirection without value - [ ] Config-driven behavior that could be direct code - [ ] Separate interface + implementation for internal-only code - [ ] Builder/strategy/visitor patterns where a function would do - [ ] Wrapper hooks around `store.use()` that add no logic - [ ] "Future-proofing" code for requirements that don't exist yet - [ ] Prop-drilling through N components when the child could read the store directly ### 6. Anti-Slop -- AI-Generated Patterns - [ ] Comments restating what code does ("// Create X" before create call) - [ ] Section dividers ("// --- section ---") - [ ] JSDoc on internal/obvious functions - [ ] Over-descriptive variable names - [ ] Unnecessary type annotations where TypeScript infers - [ ] "robust", "seamless", "leverage", "ensure" in comments (AI voice) - [ ] Defensive checks on values that can't be null/undefined - [ ] Try-catch blocks catching impossible errors - [ ] Fallback values that never trigger ### 7. Naming & Conventions - [ ] File name doesn't match primary export (e.g. `use-terminal-size.ts` exporting `useResponsiveLayout`) - [ ] Stuttered paths (e.g. `commands/commands.ts`) - [ ] Inconsistent naming across similar modules - [ ] Names that mislead about content (e.g. "types/" containing runtime logic) - [ ] Project convention violations (from CLAUDE.md) ### 8. File Organization [cross-cutting] - [ ] Files in wrong directory based on content/consumers - [ ] Domain logic in `utils/` that belongs in `core/` or feature module - [ ] Pure logic in UI directories - [ ] Test importing across architectural boundaries - [ ] Re-exports that should be direct imports ### 9. Type Safety - [ ] `as` type assertions that bypass validation - [ ] `any` types that could be narrowed - [ ] Missing discriminated union exhaustiveness checks - [ ] Type aliases that add no semantic value - [ ] Branded types without constructors ### 10. Error Handling - [ ] Inconsistent error patterns (some throw, some return, some log) - [ ] Raw `throw new Error()` where structured errors exist - [ ] Empty catch blocks without justification - [ ] Error messages that don't help debugging - [ ] Missing error handling at system boundaries ### 11. Dead Code & Redundancy - [ ] Unused exports (exported but never imported) - [ ] Dead re-exports (re-exported but nobody imports from that path) - [ ] Unused imports - [ ] Commented-out code - [ ] Variables assigned but never read - [ ] Redundant overrides that duplicate base behavior ### 12. Patterns & Best Practices - [ ] React: hook rules violations, stale closures, unnecessary refs - [ ] React: convention violations (useMemo/useCallback/memo when project bans them) - [ ] React: forwardRef/useImperativeHandle when project bans them - [ ] React: Context for state when project uses external stores - [ ] Class usage when project is zero-class (Error subclasses are OK) - [ ] Mutable state where immutable patterns are expected - [ ] Callback naming inconsistency across similar interfaces ### 13. Architecture [cross-cutting] - [ ] Circular dependencies - [ ] Wrong-direction imports (e.g. core importing from UI) - [ ] Tight coupling between modules that should be independent - [ ] Missing abstraction boundaries - [ ] Factory patterns that could be simplified - [ ] Configuration objects being built with fake/dummy data just to satisfy types ### 14. Reusability [cross-cutting] - [ ] Patterns appearing 3+ times that should be extracted - [ ] Similar helper functions in different modules doing the same thing - [ ] Shared business logic duplicated between test and source - [ ] Constants defined in multiple places instead of one source of truth ### 15. Performance (flag only clear issues) - [ ] Synchronous I/O in hot paths - [ ] Unnecessary re-computation on every render (when framework provides alternatives) - [ ] N+1 patterns in data fetching - [ ] Missing early returns causing unnecessary work --- ## Scoring System After collecting all findings, score each category 1-5: | Score | Meaning | |-------|---------| | 5/5 | No issues found. Exemplary. | | 4/5 | Minor issues only (low severity). No action strictly required. | | 3/5 | Some medium issues. Should fix for quality. | | 2/5 | Multiple high-severity issues. Needs attention. | | 1/5 | Critical issues or pervasive problems. Urgent fix needed. | **Present the scorecard to the user in this format:** ``` ## Scorecard | Category | Score | Issues | |-----------------------------|-------|--------| | DRY | 4/5 | 2 medium | | SRP | 5/5 | -- | | KISS | 4/5 | 1 low | | YAGNI | 5/5 | -- | | Over-Engineering | 3/5 | 1 high, 2 medium | | Anti-Slop | 5/5 | -- | | Naming & Conventions | 4/5 | 3 low | | File Organization | 3/5 | 2 high | | Type Safety | 4/5 | 1 medium | | Error Handling | 4/5 | 2 medium | | Dead Code & Redundancy | 3/5 | 1 high, 3 medium | | Patterns & Best Practices | 5/5 | -- | | Architecture | 4/5 | 1 medium | | Reusability | 3/5 | 2 high | | Performance | 5/5 | -- | | **Overall** | **4.1/5** | | ``` **The goal is 5/5 on every category.** For each category below 5/5, list exactly what needs to change to reach 5/5. The fix plan in Phase 5 must address ALL findings -- not just critical/high, but medium and low too. After executing the plan, every category should score 5/5. If any category can't reach 5/5 (e.g. a fundamental architectural constraint), explain why and what the maximum achievable score is. ## Severity Guide | Severity | Definition | Example | |----------|-----------|---------| | Critical | Bugs, security issues, boundary violations, wrong behavior | Core module importing from UI layer | | High | Real code smells that will cause maintenance pain | 5x copy-pasted logic, files in wrong directory | | Medium | Improvements that make code cleaner | Unnecessary comments, naming mismatches, redundant re-exports | | Low | Nitpicks and style preferences | Could rename for clarity, minor ternary simplification |