cc-audit

cc-audit is a lightweight command-line tool for checking an AI coding agent's configuration file (CLAUDE.md or AGENTS.md) against 12 baseline rules. It is written as a single Python file, has no external dependencies, and is about 240 lines of code, making it easy to integrate and use. The tool is designed to help developers ensure their agent configuration follows best practices and avoids common problems.

Main capabilities

• Detect missing baseline rules, including the 12 rules on token budget, visible failures, precise edits, convention over novelty, and more.
• Find leaked secrets, such as GitHub personal access tokens (PAT), AWS keys, API keys, and plaintext passwords.
• Identify a missing "project-specific" section.
• Flag files that cross the 200-line compliance cliff.
• Output a compliance score, a list of missing rules, and leaked-secret flags.
• Exit codes: 0 means pass, 1 means warn, 2 means fail.
• Support the --json option to output machine-readable results.

The 12 rules

1. Think before coding - raise tradeoffs and assumptions before writing code.
2. Simplicity first - solve the stated problem with the least code.
3. Precise edits - touch only the relevant code and match the existing style.
4. Goal-driven execution - define success criteria in advance and verify before claiming completion.
5. Do not make the model do non-language work - route deterministic logic through code.
6. Hard token budget - limit token consumption per task, stop at the cap, and ask.
7. Expose conflicts - do not average two incompatible patterns.
8. Read before writing - understand adjacent code first.
9. Tests gated by correctness - assert behavior, not shape.
10. Checkpoints for long-running operations - commit between multi-step changes.
11. Convention over novelty - follow established patterns rather than inventing.
12. Visible failures - expose partial failures, skipped lines, and truncated output.

Usage

• Run directly: execute as a Python script to check the specified CLAUDE.md or AGENTS.md file.
• As a GitHub Action: place the configuration file in .github/workflows/cc-audit.yml and every PR will generate a compliance report in the run summary, while a push containing leaked secrets will fail the build.
• Use the --json option to get machine-readable output.

Use cases

• When development teams use AI coding agents, ensure the agent configurationFollows best practices.
• Integrate into CI/CD pipelines to automatically check configuration file compliance.
• Individual developers review their own agent configuration files.

Limitations

• Based on a scan of 492 public CLAUDE.md files, the median compliance score is only 3/12, with no file achieving a perfect score, indicating generally low compliance.
• The most frequently missed rule is "do not edit out of bounds," which 98% of files failed to comply with.
• No leaked production secrets were found, but the tool can still detect them.
• The rules are derived from claude-code-pro-pack and may not cover all scenarios.
• The tool only checks configuration files and does not execute actual code.

Additional Information

• The repository includes the dataset data/scan-500.json and the analysis.
• The tool is used in pairing with claude-code-pro-pack.