pragmatic-audit

Code-quality audits for AI-generated code. A zero-dependency CLI and agent skill that check a repository against The Pragmatic Programmer.

AI made writing code cheap. Changing it is still expensive.

pragmatic-audit checks a repository against the durable principles from The Pragmatic Programmer — DRY, orthogonality, contracts, resource ownership, external configuration, tests, and more — then hands the judgment calls to your agent with a focused review packet. Read the project site for the AI code audit workflow and the Pragmatic Programmer checklist.

It is for humans reviewing agent output, and for agents that need to write code worth keeping.

Why this matters in the agentic era

Agents can produce code faster than humans can review it. They also copy patterns — including bad ones — at scale. Prototypes that were meant to be thrown away become production systems, and the small compromises compound.

The bottleneck has moved. It is no longer how fast a team can type. It is how cheaply the code can change next week.

Principles are portable guardrails. They survive model upgrades, framework churn, and team changes. A deterministic audit gives humans and agents the same vocabulary for a review:

• DRY asks whether one piece of knowledge has one authoritative home.
• Orthogonality asks whether a change stays local.
• Contracts ask whether a boundary fails loudly or lies quietly.
• Resource ownership asks who closes what they opened.
• Tests ask whether behavior is pinned down or merely exercised.

pragmatic-audit finds the mechanical violations. The bundled skill teaches an agent how to reason about the rest.

What you get

No network. No telemetry. No LLM calls inside the CLI. No dependencies outside the Python standard library.

Quick start

Run it against any repository without installing anything:

git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git /tmp/pragmatic-audit
cd /tmp/pragmatic-audit && python3 -m pragmatic_audit /path/to/repo

Or install the CLI from PyPI:

pip install pragmatic-audit
pragmatic-audit .

With pipx:

pipx install pragmatic-audit
pragmatic-audit .

Common modes:

# Human-readable report
pragmatic-audit .

# Stable JSON for CI and agents
pragmatic-audit . --format json

# Findings plus a review packet for your coding agent
pragmatic-audit . --agent-packet

# Fail the build on high-severity findings
pragmatic-audit . --ci --fail-on high

Python 3.11 or newer. Nothing else.

Install the agent skill

The skill lives in skills/pragmatic-programmer. Every command below is repeatable and self-cleaning.

Claude Code

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && mkdir -p ~/.claude/skills && cp -R ~/.cache/pragmatic-audit/skills/pragmatic-programmer ~/.claude/skills/

Claude Cowork / claude.ai

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && cd ~/.cache/pragmatic-audit/skills && zip -r ~/Downloads/pragmatic-programmer.zip pragmatic-programmer

Then open Customize → Skills → Upload and select pragmatic-programmer.zip.

ChatGPT Work / CoWork

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && cd ~/.cache/pragmatic-audit/skills && zip -r ~/Downloads/pragmatic-programmer.zip pragmatic-programmer

Then open Plugins → Skills → Create → Upload from your computer and select the ZIP.

For local Codex:

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && mkdir -p ~/.codex/skills && cp -R ~/.cache/pragmatic-audit/skills/pragmatic-programmer ~/.codex/skills/

OpenCode

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && mkdir -p ~/.config/opencode/skills && cp -R ~/.cache/pragmatic-audit/skills/pragmatic-programmer ~/.config/opencode/skills/

Project-local variant:

mkdir -p .opencode/skills && cp -R /path/to/pragmatic-audit/skills/pragmatic-programmer .opencode/skills/

Everything else (Agent Skills standard)

rm -rf ~/.cache/pragmatic-audit && git clone --depth 1 https://github.com/CobaltChaser/pragmatic-audit.git ~/.cache/pragmatic-audit && mkdir -p ~/.agents/skills && cp -R ~/.cache/pragmatic-audit/skills/pragmatic-programmer ~/.agents/skills/

Host notes:

• Claude Code reads ~/.claude/skills/ and .claude/skills/.
• OpenCode reads ~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/, and their project equivalents.
• Codex reads local skills from ~/.codex/skills/. ChatGPT workspace skills are uploaded through the UI.
• Cursor and other compatible hosts can use ~/.agents/skills/ or their documented local skill directory.
• Keep SKILL.md at the root of the skill folder. The folder name must match the skill name.

See docs/agent-skill.md for invocation examples and compatibility notes.

Use it in CI

name: pragmatic-audit

on:
  push:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pipx install pragmatic-audit
      - run: pragmatic-audit . --ci --fail-on high --format markdown --output pragmatic-audit.md
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: pragmatic-audit
          path: pragmatic-audit.md

Exit codes:

The gate is opt-in. By default the CLI reports and exits 0. Use --fail-on medium when the codebase is ready for a stricter ratchet.

The 20 core checks

Opt-in history and architecture checks:

Enable them with --include-history or --all.

Full rationale, examples, false positives, and tuning: docs/rules.md.

Hybrid by design

Static analysis is good at finding mechanical violations. It is bad at judging design.

This tool does not pretend otherwise.

1. The scanner produces deterministic findings with locations and fixes. It reads Python and JavaScript/TypeScript structurally, and uses conservative text heuristics for Go, Java, Ruby, PHP, Rust, and others.
2. The report adds a manual review queue: tracer bullets, boundary contracts, orthogonality, domain language, reversibility, test design, and speculative code.
3. The packet gives an agent the evidence and a question set. The agent must open the files, confirm or dismiss each finding, and report only the few changes that most improve changeability.

pragmatic-audit . --agent-packet

That writes pragmatic-audit.packet.json and pragmatic-audit.packet.md in the current directory. Neither file is required for normal use; both are designed to be pasted into an agent session.

What it will not do

• It will not auto-fix code.
• It will not make network requests or call an LLM.
• It will not replace your linter, type checker, test runner, or security scanner.
• It will not produce a definitive quality score. The number is directional and always shown next to raw counts.
• It will not understand every framework’s conventions. False positives are expected; dismiss them with a reason or tune the rule.
• It will not prove that code is correct.

Treat every finding as a hypothesis. Read the code before changing it.

Example report

The bundled bad repository produces a real report: examples/report.md.

The examples are deliberately small and are used by the test suite:

pragmatic-audit examples/bad-repo
pragmatic-audit examples/good-repo

Tuning

Create .pragmatic-audit.toml at the repository root:

[scan]
exclude = ["generated", "public/vendor", "*.min.js"]
languages = ["python", "javascript", "typescript"]

[thresholds]
long_function = 60
deep_nesting = 4
max_params = 5
test_ratio = 0.3

[ignore]
rules = ["PP-MAGIC"]
paths = ["migrations/**"]

[ci]
fail_on = "high"
min_confidence = "medium"

Suppress a single line when the finding is genuinely wrong:

if len(items) > 42:  # pragmatic-audit: ignore PP-MAGIC pagination boundary from the API contract

Suppress a file when the whole file is a known exception:

# pragmatic-audit: ignore-file PP-GLOBALS this module is the state owner

Every suppression needs a written reason. A suppression without a reason is a broken window.

Self-audited

This repository runs pragmatic-audit on itself in CI, and the test suite includes the rules it ships. The current self-audit report is examples/self-audit.md, generated by scripts/self_audit.sh.

The tool is not expected to score 100. It is expected to show its own trade-offs honestly, including deliberate exceptions and false positives.

Contributing

PRs are open. This project gets better when more people encode the principles they actually use. Rule proposals, false-positive reports, new language patterns, docs fixes, and examples are all welcome.

Good first contributions:

• Add a language pattern to an existing rule, with a positive and negative fixture.
• Improve a rule description or a fix suggestion.
• Add a false-positive case that the current tests miss.
• Make an example repository more realistic.
• Tighten the docs.

Read CONTRIBUTING.md before opening a pull request. The short version:

python3 -m unittest discover -s tests -v
python3 -m compileall pragmatic_audit
python3 -m pragmatic_audit . --ci --fail-on high

No new runtime dependencies. Every rule needs a test. Every behavior claim needs a test or a code link.

• Rule proposal template
• Bug report template
• Code of conduct
• Security policy

License

Apache-2.0. Use it at work, in commercial products, and in closed-source repositories. Keep the copyright, license, and NOTICE file, and state significant changes.

Full terms: LICENSE.

Credits

The Pragmatic Programmer, 20th Anniversary Edition is by David Thomas and Andrew Hunt. This project is an independent, unofficial tool. Tip names and numbers are referenced descriptively with attribution. No book text is reproduced. The project is not affiliated with the authors or The Pragmatic Programmers, LLC.

The audit text, prompts, and documentation in this repository are original paraphrases and implementations.