sisyphusse1-ops

Posted on May 10

I shipped cc-audit as a GitHub Action. Now your CLAUDE.md gets linted on every PR.

#github #ai #devops #actions

Quick follow-up to my earlier post about scanning 492 public CLAUDE.md files. Takeaway from that scan: median compliance with the 12-rule baseline was 3/12. The top-missed rules were rules 9, 10, 12, and 1 — the behavior-file equivalent of skipping unit tests.

The fix is easy: run a linter. The harder part is remembering to run it.

So I packaged cc-audit as a GitHub Action. Drop three lines into your repo's workflow, and every push that touches CLAUDE.md or AGENTS.md gets an automatic report in the run summary — plus a hard fail if someone ever pastes a real API key into the behavior file.

The workflow

# .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

That's it.

What you get

Every matching push/PR runs cc-audit against the file. The run summary shows:

Metric	Value
File	`CLAUDE.md`
Rules covered	7 / 12
Compliance score	58 %
Leaked secrets	0
Status	warn

The step fails with a loud ::error:: annotation if any leaked-secret pattern is detected — OpenAI keys, Anthropic keys, GitHub PATs, AWS access keys, Stripe live keys, postgres URLs with credentials. Placeholder-aware, so <YOUR_KEY> and sk-example-... don't trigger false positives.

By default it doesn't fail the build on mere rule-coverage warnings, because a 7/12 file isn't "broken" — it's just not thorough. You can flip that with:

      - uses: sisyphusse1-ops/cc-audit@v1
        with:
          fail-on-warning: true

Auto-install the baseline

There's also a companion action for the claude-code-pro-pack itself. If your repo doesn't have a CLAUDE.md / AGENTS.md yet, this installs the 12-rule baseline in one step:

- uses: sisyphusse1-ops/claude-code-pro-pack@v1
  with:
    flavor: both            # claude | agents | both
    install-templates: true # also copy templates/ and examples/

It's polite — skips files that already exist unless you pass overwrite: true.

End-to-end demo

I shipped a demo repo that uses both actions:

→ github.com/sisyphusse1-ops/ccpp-demo

Check the Actions tab — you'll see real runs installing the pack, then linting it. The install workflow is workflow_dispatch so you can fork the repo, trigger the install on your fork, and watch the same thing happen on your own files.

Why bother

Three reasons I wrote this and why you might want to run it:

Behavior drift. CLAUDE.md files get edited casually by whoever's on-call for the agent that week. Compliance scores drift down over months. A linter in CI catches it.
Secret leaks. The 492-file scan found zero real leaks, which is great — but the base rate of pasting .env contents into docs is nonzero across the wider population. A 40 ms check on every PR catches it before it hits the default branch.
Onboarding. New engineer opens your repo. CI report in the PR summary shows them the 12-rule baseline exists, which rules your file covers, and which it doesn't. The explanation is in the action output, not in a wiki page they won't find.

Install time

Workflow file: 3 lines.

CI overhead per run: 20-30 seconds on ubuntu-latest (no Docker image pull, just checkout + Python stdlib).

Token cost: zero.

Cost to break your build: zero if no secrets leaked.

Repos

cc-audit (linter + action) — github.com/sisyphusse1-ops/cc-audit
claude-code-pro-pack (baseline rules + installer action) — github.com/sisyphusse1-ops/claude-code-pro-pack
ccpp-demo (both in action, end-to-end) — github.com/sisyphusse1-ops/ccpp-demo

All three MIT.

If this saves you a merge review, or catches a leaked key, let me know. That's the use case I optimized for.

DEV Community