cc-audit

Lint any CLAUDE.md or AGENTS.md against the 12-rule baseline for AI coding agents.

One Python file, no dependencies, ~240 lines. Pairs with claude-code-pro-pack.

What it catches

• Missing baseline rules (token budgets, visible failure, surgical changes, convention-over-novelty, etc.)
• Leaked secrets (GitHub PATs, AWS keys, API keys, clear-text passwords)
• Missing project-specifics section
• Files past the 200-line compliance cliff

Use as a CLI

# one file, zero install
curl -fsSL https://raw.githubusercontent.com/sisyphusse1-ops/cc-audit/main/cc_audit.py -o cc_audit.py
python3 cc_audit.py CLAUDE.md

Outputs a compliance score, the rules your file is missing, and flags any leaked secrets. Exits 0 on pass, 1 on warn, 2 on fail.

Add --json for machine-readable output.

Use as a GitHub Action

Drop this in .github/workflows/cc-audit.yml:

name: cc-audit
on:
  pull_request:
    paths: [ 'CLAUDE.md', 'AGENTS.md' ]
  push:
    paths: [ 'CLAUDE.md', 'AGENTS.md' ]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sisyphusse1-ops/cc-audit@v1

Every PR gets a compliance report in the run summary. Pushes with leaked secrets fail the build.

Inputs

Input	Default	Description
path	auto	Path to the file. Auto-detects CLAUDE.md or AGENTS.md in repo root.
fail-on-warning	false	Exit non-zero on any warning. Default fails only on critical issues (leaked secrets).
json-output	empty	Optional path to write the full JSON report.

Outputs

Output	Description
score	Compliance score, 0-100 (percent)
rules-hit	Number of baseline rules covered, 0-12
leaked-secrets	Count of leaked-secret patterns detected
status	pass, warn, or fail

What the 12 rules are

1. Think before coding — surface tradeoffs and assumptions before writing
2. Simplicity first — minimum code that solves the stated problem
3. Surgical changes — touch only relevant code, match existing style
4. Goal-driven execution — define success criteria upfront, verify before claiming done
5. Don't make the model do non-language work — route deterministic logic through code
6. Hard token budget — cap per-task token spend, stop-and-ask at the ceiling
7. Surface conflicts — don't average two incompatible patterns
8. Read before you write — understand adjacent code first
9. Tests gated by correctness — assert behavior, not shape
10. Checkpoints for long operations — commit between multi-step changes
11. Convention beats novelty — follow established patterns over inventing
12. Fail visibly — surface partial failures, skipped rows, and truncated output

Rules come from claude-code-pro-pack.

Real-world data

I ran cc-audit against 492 public CLAUDE.md files pulled from GitHub code search. The dataset is in data/scan-500.json and the analysis is on dev.to.

Headline numbers:

• Median compliance: 3 / 12
• Perfect (12/12) scores: 0
• Files with leaked production secrets: 0
• Most-missed rule: "don't edit out of scope" — 98% missed it

License

MIT.