fan-out-audit

A Claude Code slash command that spins up parallel agents to audit your codebase with thoroughness a single agent can't achieve.

Install

cp fan-out-audit.md your-repo/.claude/commands/

This is a Claude Code slash command. After copying, invoke it with /fan-out-audit [your task].

The problem

When you ask an AI coding agent to audit a large codebase, it skims. It can't fit everything in context, so it reads some files, gives surface-level answers, and misses things you'd catch yourself. You've probably felt this: you ask for refactoring opportunities and get a few decent suggestions, but you know there's more it didn't find.

Fan-out auditing fixes this by splitting the work into tiny batches. Instead of one agent skimming 500 files, you get 200 agents each reading 5-8 files. AI gets worse at larger batches. An agent reading 5 files will catch things an agent reading 500 won't.

How it works

Three phases:

Phase 1: Pre-filter and fan out. One grep finds relevant files. Files are grouped into slices of 5-8 (keeping same-directory files together). One agent per slice reads every file and writes structured findings to its own .md file. You watch the files appear in your editor in real time.

Phase 2: Cross-cutting pattern detection. After all Phase 1 agents complete, a second wave of agents each reads ~12 Phase 1 output files and identifies patterns that span multiple slices. This is where findings like "this same function is reimplemented in 8 modules" emerge, which no individual Phase 1 agent could see.

Phase 3: Synthesis. A final pass reads the Phase 2 files and produces a ranked summary: top 10 highest-impact opportunities, deduplicated cross-cutting patterns, and a list of clean zones.

Usage

# Check copy against a style guide or tropes list
/fan-out-audit check all user-facing text against ~/Downloads/tropes.md

# Find refactoring opportunities
/fan-out-audit find duplicated logic, consolidation candidates, dead code, library alternatives

# Audit error handling
/fan-out-audit find services that throw exceptions instead of returning Result types

# Check type safety
/fan-out-audit find uses of 'any', missing return types, loose equality, unsafe type assertions

# Architecture review
/fan-out-audit find layer violations, circular dependencies, modules importing from wrong layers

# Target specific directories
/fan-out-audit TARGET=src/app,src/api find components over 200 lines

The command asks you to name the output directory (e.g., tropes-violations) and shows the full slice plan before launching. You confirm, and agents start running.

Example output

Two real audits are included in examples/.

Type-safety improvements (249 slices, 1,834 files)

A code quality audit that started as a short bullet list and expanded into a full codebase-wide type-safety remediation plan.

Original prompt:

/fan-out-audit help me find opportunities for type-safety improvements in my codebase, such as
- leveraging client sdk types instead of defining our own custom types (e.g. for linear/sdk, googleapis, slack/web-api, etc)
- avoiding type-casting
- finding eslint rules and tsconfig changes that enforce a higher standard for typescript
- avoiding "any" or "unknown" types
- avoiding weakening to Record<string,...> types instead of keeping objects as constants, or keying by a stricter type
- de-duping types

Key files:

• TASK.md - Original prompt + expanded agent brief
• SYNTHESIS.md - Top 10 findings ranked by impact × prevalence (e.g. 30 untyped Drizzle JSONB columns causing 100+ downstream casts; single BaseSyncService generic eliminates 30–45 casts across 15 integration files)
• phase1/apps-api-src-integrations-6.md - Example slice with specific line-number findings
• phase2/group-6.md - Cross-cutting patterns across the integrations layer
• orchestration/ - 9-PR remediation plan generated from the synthesis (what to do next)

Tropes violations (201 slices, 809 files)

A copy/tone audit checking all user-facing text against an AI writing tropes reference.

Key files:

• SYNTHESIS.md - Final ranked summary
• phase1/apps-app-src-components-billing-3.md - Example slice with detailed findings (stock SaaS billing copy)
• phase1/apps-marketing-src-app.md - Example clean slice (no findings, agent explains what it checked)
• phase2/group-6.md - Cross-cutting patterns ("learning your patterns" used 9 times across 7 slices)

Configuration

These defaults work well for most codebases. Adjust in the prompt if needed:

Lessons learned (from building this)

Use general-purpose agents, not Explore. Explore agents in Claude Code don't have Write access. They silently fail to create output files. The first version of this tool produced zero output files because of this. general-purpose agents have Write access and work correctly.

Small batches matter more than you'd think. An agent given 50 files will pattern-match on file names, skip files that "look fine," and produce vague observations. An agent given 5 files reads every line and produces findings with line numbers. The quality difference is dramatic.

Write to files, not memory. The first version had agents return findings in their response, and the orchestrator summarized them. An agent finds 8 specific issues with line numbers. The orchestrator compresses them to "several type safety issues found." Detail gone. When every agent writes to its own file, nothing is lost.

The orchestrator will try to optimize. Without strong guardrails, the orchestrating Claude instance will second-guess the slice count, re-filter files multiple times, skip Phase 2 "to save time," and synthesize from memory instead of files. The prompt has extensive anti-shortcut language for this reason. If you modify the prompt, keep that language.

Phase 2 catches what Phase 1 can't. If 9 different slices all report "custom date formatting," no Phase 1 agent knows that. Phase 2 agents read 12 reports each and surface these cross-cutting patterns. This is where the highest-value consolidation opportunities emerge.

How it scales

The same prompt works on any size codebase. A repo with 10,000 files produces more slices and takes longer, but the mechanics are identical. The pre-filter step keeps agent count proportional to relevant files, not total files.

Requirements

• Claude Code (CLI or IDE extension)
• Claude Max, Teams, or API access (the agents consume tokens)

License

MIT