cc-audit — Summary

cc-audit is a single-file Python script (~240 lines, no dependencies) that lints CLAUDE.md or AGENTS.md files against a 12-rule baseline for AI coding agents, detecting missing rules, leaked secrets, and files past the 200-line compliance cliff.

Problem it solves: Most agent configuration files miss critical baseline rules — a scan of 492 public CLAUDE.md files found median compliance of 3/12 rules, with 98% missing "don't edit out of scope." cc-audit provides a fast, zero-install check that can run in CI via a GitHub Action.

Distinctive trait: Minimal design philosophy — one Python file, no dependencies, ~240 lines. Pairs with the claude-code-pro-pack methodology (sisyphusse1-ops/claude-code-pro-pack) as a CI gate for CLAUDE.md quality. The 12 rules are explicitly borrowed from the pro-pack's methodology.

Target audience: Developers and teams who want a lightweight CI gate to prevent CLAUDE.md regressions (leaked secrets, missing baseline rules) on every pull request.

Production-readiness: Minimal/experimental (0 stars, MIT, Python). Last commit May 2026. The value is in the GitHub Action integration and the empirical data (492 public file scan published on dev.to).

Differs from seeds: cc-audit is the smallest framework in the corpus — a single Python checker closer to a linting utility than a framework. It is most similar to AgentLint (harness quality checking) but far simpler: 12 keyword-signal rules vs AgentLint's 58 evidence-backed checks, no CLI flags beyond --json, no interactive mode, no hook validation. The 12 rules are a subset of what AgentLint checks but framed around a specific companion methodology (claude-code-pro-pack).

cc-audit — Overview

Origin

cc-audit was created by sisyphusse1-ops as a companion linter to the claude-code-pro-pack methodology. The 12-rule baseline it checks against comes directly from that companion project.

Philosophy

Minimal and zero-dependency by design:

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

The project shares empirical data: a scan of 492 public CLAUDE.md files from GitHub code search, published on dev.to. Headline numbers:

• Median compliance: 3/12
• Perfect (12/12): 0
• Leaked production secrets: 0
• Most-missed: "don't edit out of scope" (98% missed)

The 12 Rules Checked

1. Think before coding — surface tradeoffs and assumptions
2. Simplicity first — minimum code for the problem
3. Surgical changes — touch only relevant code, match existing style
4. Goal-driven execution — define success criteria upfront, verify before 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
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
12. Fail visibly — surface partial failures, skipped rows, truncated output

Secret Detection Patterns

ANTI_PATTERNS = [
    (r"paypal\.me/[\w-]+",        "leaked paypal link"),
    (r"ghp_[A-Za-z0-9]{10,}",    "leaked GitHub PAT token"),
    (r"sk-[A-Za-z0-9]{20,}",     "leaked API key (sk-...)"),
    (r"\bAKIA[0-9A-Z]{16}\b",    "leaked AWS access key"),
    (r"\bpassword\s*[:=]\s*['\""]", "literal password in clear text"),
]

cc-audit — Architecture

Distribution

• Type: Single Python script + GitHub Action
• License: MIT
• No pip package — direct curl download

Install Methods

# One-time, 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

# GitHub Action
uses: sisyphusse1-ops/cc-audit@v1

Required Runtime

• Python 3 (no dependencies — stdlib only)

Directory Structure

cc-audit/
├── cc_audit.py          # Single-file Python linter (~240 lines)
├── action.yml           # GitHub Action definition
├── data/
│   └── scan-500.json    # Dataset: 492 public CLAUDE.md scan results
├── README.md
└── LICENSE

GitHub Action Inputs

GitHub Action Outputs

Exit Codes

• 0 — pass
• 1 — warn (missing rules, size over limit)
• 2 — fail (critical: leaked secrets)

Score Formula

def score(self) -> int:
    base = int(len(self.rules_hit) / len(RULE_SIGNALS) * 80)  # rules: 80%
    base += 10 if self.has_project_specifics else 0            # +10 for project section
    base += 10 if not self.anti_patterns else 0                # +10 for no secrets
    if self.size_warning: base -= 10                            # -10 over 200 lines
    return max(0, min(100, base))

cc-audit — Components

Scripts (1)

GitHub Action (1)

Data (1)

No Commands, Skills, Hooks, MCP, or Subagents

cc-audit is a standalone Python utility. It has no Claude Code integration, no hooks, and no interactive mode beyond --json flag.

Check Types

Rule Signal Matching (permissive)

Rules are detected by keyword presence anywhere in the file. Example:

("3: surgical changes",
 ["surgical", "touch only", "adjacent code", "match existing style"]),

A rule is "covered" if any signal word appears. Deliberately permissive — the goal is "rule mentioned at all" not "rule stated correctly."

cc-audit — Uniqueness

Differs from Seeds

cc-audit is closest to AgentLint (harness quality checking via static analysis of CLAUDE.md/AGENTS.md) but is dramatically simpler: one Python file, no dependencies, 12 rules vs 58 checks, keyword-signal matching vs sophisticated multi-dimensional analysis. Unlike AgentLint, cc-audit has no Claude Code integration, no interactive mode, no harness-specific checks (no hook validation). The GitHub Action integration is its primary deployment mechanism, making it a CI gate rather than a developer workflow tool. No seed framework directly matches — the closest analogy is a simplified version of one dimension of AgentLint deployed as a GitHub Action.

Key Differentiators

1. Zero dependencies: Pure Python stdlib. curl | python3 install — no npm, no pip.
2. GitHub Action first: The Action integration is the primary use case, not the CLI.
3. Empirical data: Published a scan of 492 real CLAUDE.md files with compliance statistics.
4. Companion to claude-code-pro-pack: The 12 rules are explicitly borrowed from a companion methodology project.
5. Minimalism: ~240 lines is a design constraint, not an accident.

Positioning

cc-audit occupies the "CI gate for CLAUDE.md quality" niche — the simplest possible tool to prevent CLAUDE.md regressions in a pull request workflow. It is not a comprehensive harness auditor (that's AgentLint) and not a methodology framework (that's any of the seed frameworks). It is a sanity check that takes <1 second to run.

Observable Failure Modes

• Keyword-signal gaming: Any file containing the word "surgical" passes rule 3, regardless of meaning.
• False positives on secrets: sk- prefix is common in non-secret strings (e.g., skip-, skeleton-).
• No YAML frontmatter depth: Basic validity only, not semantic check.
• Static keyword list: New valid phrasings for rules are not detected until the signal list is updated.
• No size calibration: 200-line cliff is a fixed constant, not project-dependent.

Companion Project

sisyphusse1-ops/claude-code-pro-pack — the source of the 12-rule baseline. cc-audit is the CI gate; claude-code-pro-pack is the methodology that defines the rules.