arch-audit

name

arch-audit

description

Run an architectural audit of a codebase and write a planning-ready report. Discovers the repo's shape (no hardcoded paths), maps the dependency/layering graph and checks for cycles, assesses how easy the code is to reason about — separately for humans and for Claude Code — and emits a prioritized, file-anchored report to ./arch-audit/audit-<timestamp>.md plus a short chat summary. Use when the user says "architectural audit", "audit the architecture", "audit this codebase", "produce an architecture report for planning", or "/arch-audit".

Architecture Audit

Produce a planning-ready architecture report: a structured, prioritized, file-anchored assessment whose explicit goal is to make the codebase easier to reason about for both humans and Claude Code. The report is meant to be handed to a planning agent, so findings must be ranked and actionable — not an exhaustive lint dump.

This skill is read-only with respect to the codebase. The only things it writes are the report file and the arch-audit/ directory that holds it. Never refactor, reformat, or "fix" anything during an audit — observe and report.

Trigger

Phrases like:

• "/arch-audit", "/arch-audit "
• "architectural audit", "audit the architecture", "audit this codebase"
• "produce an architecture report for planning"
• "what's hard to reason about in this codebase"

Inputs

• path (optional positional): the repo or subtree to audit. Default: the current working directory / repo root.
• --focus (optional): narrow the audit to one package/subtree (e.g. --focus packages/core). The system map still shows the whole repo for context, but findings concentrate on the focus area.
• --save-only (optional): skip the chat summary; just print the report path. Use for large audits.

Steps

1. Discover the shape — don't assume

Use Glob, Grep, and Read to learn the structure. Hardcode nothing.

• Read any existing orientation docs first, and treat them as claims to verify, not ground truth: CLAUDE.md, AGENTS.md, README*, documentation/, docs/, ARCHITECTURE*. Note where they disagree with the code (this becomes doc-vs-code drift).
• Detect language(s), package/module manager, and workspace layout: look for package.json (+ pnpm-workspace.yaml / workspaces), pyproject.toml / setup.py, go.mod, Cargo.toml, pom.xml / build.gradle, etc.
• Detect build & test tooling (tsconfig, esbuild/webpack/vite, vitest/jest, pytest, etc.) and the entry points (bin, main, exports, server mains).
• Get a size sense: count source files per module and find the largest files.

For anything but a small repo, fan out with Explore agents in parallel (one per area or per question) for breadth, then synthesize. Scale effort to repo size — sample rather than reading everything in large repos, and say so in the appendix.

2. Map the dependency / layering graph

• Derive inter-module dependencies from manifests (workspace deps) and from actual imports (Grep for import/require statements crossing module boundaries).
• Identify the intended layering (e.g. foundational lib → mid layer → apps/entry points).
• Check for cycles between modules and layering violations (a lower / more-foundational layer importing a higher one). These are high-signal findings — call them out explicitly even if none are found ("no cycles detected" is a useful result).

3. Assess "reason-about-ability" per axis

For each axis below, form a judgment backed by concrete evidence (path:line). Don't pad — only raise an axis as a finding if there's something real to say.

• Module boundaries & cohesion — do modules have a single clear responsibility, or are concerns smeared across files?
• Naming & consistency — predictable names/conventions vs. ambiguous or conflicting ones.
• Size hotspots — the largest files and functions; flag anything that's a monolith or a likely context-window problem.
• Duplication — copy-pasted logic that should be shared.
• Public API / export surface — is the intended-public surface clear and minimal, or does internal sprawl leak out?
• Error handling & safety seams — where failures are handled vs. swallowed; validation/trust boundaries.
• Config & secret handling — where config and secrets come from; any secrets in source/committed files.
• Test coverage shape — which subsystems have tests and which have none (shape, not a coverage percentage).
• Doc-vs-code drift — places where the docs from step 1 no longer match reality.
• Build / tooling friction — fragile build steps, known gotchas, native rebuild dances, environment coupling.
• Dead / unreferenced code — modules or exports nothing imports.

4. Separate "hard for humans" from "hard for Claude"

This is a first-class section — it is the stated goal of the audit. Call out things that specifically impede an LLM coding agent, which differ from what slows a human:

• Missing or thin CLAUDE.md / agent-orientation docs.
• Non-obvious invariants not written down anywhere (the "you must do X or Y silently breaks" rules a newcomer agent can't infer).
• Magic constants / strings with no explanation.
• Implicit cross-file contracts (two files that must change together with nothing linking them).
• Generated or reference-only files that look hand-editable.
• Files large enough to blow the context window.
• Ambiguous naming that misleads pattern-matching.

For each, note whether it hurts humans, Claude, or both — many findings hurt both, but the agent-specific ones are easy to miss and worth their own attention.

5. Write the report file

• Compute a timestamp <YYYYMMDD-HHMMSS> (use a shell command for the real current time; don't guess).
• Write the report to <repo>/arch-audit/audit-<YYYYMMDD-HHMMSS>.md, creating the arch-audit/ directory if needed. Use the template below verbatim so output is consistent across runs.
• Unless --save-only, print a short chat summary: the overall rating, the top 3-5 findings (one line each), and the report path. With --save-only, print only the path.
• Finally, confirm no source files were modified — only arch-audit/ was written.

Report template

# Architectural Audit — <repo name> (<YYYYMMDD-HHMMSS>)

## Summary

<3-5 sentences orienting a reader who has never seen this codebase: what it is,
how it's organized, and the headline architectural concerns.>

**Overall reason-about-ability:** <Good | Fair | Poor> — <one-line justification.>

## System map

| Module / package | Path | Role | Size | Depends on |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |

Dependency graph:

```
<ASCII or mermaid graph of module dependencies>
```

**Cycles:** <list, or "none detected">
**Layering violations:** <list, or "none detected">

## Findings

> Ranked by severity. Each cites concrete evidence. ~10-15 max; the rest go to
> Quick wins or Appendix.

### F1: <short title>
- **Severity:** <high | medium | low>
- **Axis:** <boundaries | naming | size | duplication | api-surface | error-handling | config-secrets | tests | doc-drift |  |  | >
   (+ more as needed)
   — 
  


(repeat)



 



 



  
  
  

Guardrails

• Read-only on the codebase. The only writes are the report file and the arch-audit/ directory. Never edit, refactor, or run formatters.
• Evidence or it didn't happen. Every finding cites a concrete path:line. No vibes-only claims.
• Prioritize ruthlessly. A planning agent needs ranked, actionable findings, not everything. Cap at ~10-15 findings; demote the rest to Quick wins or the Appendix.
• Be honest about uncertainty. Genuine unknowns belong in "Open questions," not dressed up as findings.
• Scale to repo size. Fan out with Explore agents and sample for large repos; read directly for small ones. Record what you sampled in the appendix.