Find the mechanical problems
Duplicated knowledge, swallowed errors, hardcoded configuration, missing resources, weak tests, and other patterns a scanner can judge without guessing.
A Pragmatic Programmer tool
Code quality audits for AI-generated code.
AI made writing code cheap. Changing it is still expensive. pragmatic-audit finds the mechanical risks that make a codebase hard to change, then gives your agent a focused review packet for the judgment calls.
$ pragmatic-audit examples/bad-repo Signal 74/100 heuristic, not a grade high 2 medium 6 low 4 Top fixes 1. HIGH PP-CONTRACTS src/orders.py:18 except Exception swallows the error. Fix: Handle the error, add context and re-raise, or fail fast. 2. HIGH PP-CONFIG src/orders.py:27 Environment-specific URL is hardcoded. Fix: Move environment-specific values into configuration or a secret store. Manual review queue Tracer bullets, contracts, orthogonality, test design, reversibility Findings are hypotheses. Read the code before changing it.
Why it matters
The bottleneck moved from writing code to changing it.
Agents produce code faster than humans can review it. They also copy patterns at scale, including the bad ones. A prototype that was meant to be disposable becomes production, and the small compromises compound.
Separate facts from judgment
Every finding names the principle and fix. A manual review queue covers tracer bullets, contracts, orthogonality, reversibility, and test design.
Give the agent evidence
The review packet contains the findings, the questions static analysis cannot answer, and a prompt that requires the agent to read the code before changing it.
20 core checks
Principles, not style rules.
The audit is built around changeability. It asks whether knowledge has one authoritative home, whether boundaries fail loudly, whether resources are owned, and whether behavior is pinned down by tests.
Three opt-in history checks cover commit size, vendor reversibility, and shared mutable state near concurrency.
| Rule | What it catches |
|---|---|
| PP-DRY | Duplicated normalized blocks and duplicate functions |
| PP-CONFIG | Hardcoded secrets, environment URLs, and absolute paths |
| PP-CONTRACTS | Empty catches, swallowed errors, and bare except |
| PP-RESOURCES | Resources without a guaranteed release path |
| PP-COMPLEXITY | Long functions, deep nesting, and too many parameters |
| PP-TESTS | Missing tests, thin coverage, and assertion-free tests |
| PP-VCS | Missing git, missing ignores, and tracked secrets |
| PP-DOCS | Missing or unhelpful README documentation |
Install
One command. No runtime dependencies.
Python 3.11 or newer. The CLI makes no network requests, sends no telemetry, and never executes repository code.
# install the CLI
pip install pragmatic-audit
# audit a repository
pragmatic-audit .
# fail CI on high-severity findings
pragmatic-audit . --ci --fail-on high
# write an agent review packet
pragmatic-audit . --agent-packetFor coding agents
Teach the agent the standard, not just the finding.
The bundled Agent Skill explains the principles, the review checklist, and the suppression rules. It works with Claude Code, Claude Cowork, ChatGPT Work/CoWork, Codex, OpenCode, and compatible hosts.
- Read every file behind a finding before commenting.
- Confirm or dismiss each hypothesis with a reason.
- Report the few changes that most improve changeability.
- Never echo a secret or invent a benchmark.
Start with the report, not a rewrite. Every finding is a hypothesis with a file, line, principle, and smallest fix. The tool is Apache-2.0 licensed and free for commercial use.