CLAUDE.md Linter

The problem

Most CLAUDE.md files fail in the same ways: vague directives, missing commands, rules written as suggestions instead of instructions. These aren't obvious when you write the file. They show up as Claude doing the wrong thing, repeatedly, across sessions.

This linter finds those failures before they cost you time.

Usage

# Check ./CLAUDE.md
claudemd-lint

# Show specific fixes for each failure
claudemd-lint --fix-hints

# JSON output (for scripting)
claudemd-lint --json

# CI gate — exit 1 if score below 80
claudemd-lint --min-score 80

Example output

  CLAUDE.md — CLAUDE.md

  ✗ Failures
    ✗ No vague directives [5pt]
      → Replace 'be careful' with specific rules.
    ✗ Has build or run commands [5pt]
      → Add: npm run dev, npm test, etc.
    ✗ References specific file structure [4pt]
      → Add a brief directory outline.

  ✓ Passing
    ✓ Has project description
    ✓ Mentions specific technologies
    ✓ No hardcoded secrets
    ... (14 more)

  Score: 71/100  ██████████████░░░░░░  Grade C

  → Run with --fix-hints to reach 80+.

CI integration

# GitHub Actions
- name: Lint CLAUDE.md
  run: python3 bin/claudemd-lint --min-score 80 --json

Exit code 0 = passes threshold. Exit code 1 = below threshold or file not found. Drop it into any pipeline.

The 20 rules

Requirements

Python 3.6 or newer. No packages. Works on macOS, Linux, and WSL.