leo-claude-mktplace/plugins/claude-config-maintainer/commands/config-lint.md

description

description
Lint CLAUDE.md for common anti-patterns and best practices

Lint CLAUDE.md

This command checks your CLAUDE.md file against best practices and detects common anti-patterns that can cause issues with Claude Code.

What This Command Does

1. Parse Structure - Validates markdown structure and hierarchy
2. Check Security - Detects hardcoded paths, secrets, and sensitive data
3. Validate Content - Identifies anti-patterns and problematic instructions
4. Verify Format - Ensures consistent formatting and style
5. Generate Report - Provides actionable findings with fix suggestions

Usage

/config-lint

Lint with auto-fix:

/config-lint --fix

Check specific rules only:

/config-lint --rules=security,structure

Linting Rules

Security Rules (SEC)

Rule	Description	Severity
SEC001	Hardcoded absolute paths	Warning
SEC002	Potential secrets/API keys	Error
SEC003	Hardcoded IP addresses	Warning
SEC004	Exposed credentials patterns	Error
SEC005	Hardcoded URLs with tokens	Error
SEC006	Environment variable values (not names)	Warning

Structure Rules (STR)

Rule	Description	Severity
STR001	Missing required sections	Error
STR002	Invalid header hierarchy (h3 before h2)	Warning
STR003	Orphaned content (text before first header)	Info
STR004	Excessive nesting depth (>4 levels)	Warning
STR005	Empty sections	Warning
STR006	Missing section content	Warning

Content Rules (CNT)

Rule	Description	Severity
CNT001	Contradictory instructions	Error
CNT002	Vague or ambiguous rules	Warning
CNT003	Overly long sections (>100 lines)	Info
CNT004	Duplicate content	Warning
CNT005	TODO/FIXME in production config	Warning
CNT006	Outdated version references	Info
CNT007	Broken internal links	Warning

Format Rules (FMT)

Rule	Description	Severity
FMT001	Inconsistent header styles	Info
FMT002	Inconsistent list markers	Info
FMT003	Missing code block language	Info
FMT004	Trailing whitespace	Info
FMT005	Missing blank lines around headers	Info
FMT006	Inconsistent indentation	Info

Best Practice Rules (BPR)

Rule	Description	Severity
BPR001	No Quick Start section	Warning
BPR002	No Critical Rules section	Warning
BPR003	Instructions without examples	Info
BPR004	Commands without explanation	Info
BPR005	Rules without rationale	Info
BPR006	Missing plugin integration docs	Info

Expected Output

CLAUDE.md Lint Report
=====================

File: /path/to/project/CLAUDE.md
Rules checked: 25
Time: 0.3s

Summary:
  Errors:   2
  Warnings: 5
  Info:     3

Findings:
---------

[ERROR] SEC002: Potential secret detected (line 45)
  │ api_key = "sk-1234567890abcdef"
  │          ^^^^^^^^^^^^^^^^^^^^^^
  └─ Hardcoded API key found. Use environment variable reference instead.

  Suggested fix:
  - api_key = "sk-1234567890abcdef"
  + api_key = $OPENAI_API_KEY  # Set in environment

[ERROR] CNT001: Contradictory instructions (lines 23, 67)
  │ Line 23: "Always run tests before committing"
  │ Line 67: "Skip tests for documentation-only changes"
  │
  └─ These rules conflict. Clarify the exception explicitly.

  Suggested fix:
  + "Always run tests before committing, except for documentation-only
  +  changes (files in docs/ directory)"

[WARNING] SEC001: Hardcoded absolute path (line 12)
  │ Database location: /home/user/data/myapp.db
  │                    ^^^^^^^^^^^^^^^^^^^^^^^^
  └─ Absolute paths break portability. Use relative or variable.

  Suggested fix:
  - Database location: /home/user/data/myapp.db
  + Database location: ./data/myapp.db  # Or $DATA_DIR/myapp.db

[WARNING] STR002: Invalid header hierarchy (line 34)
  │ ### Subsection
  │ (no preceding ## header)
  │
  └─ H3 header without parent H2. Add H2 or promote to H2.

[WARNING] CNT004: Duplicate content (lines 45-52, 89-96)
  │ Same git workflow documented twice
  │
  └─ Remove duplicate or consolidate into single section.

[WARNING] STR005: Empty section (line 78)
  │ ## Troubleshooting
  │ (no content)
  │
  └─ Add content or remove empty section.

[WARNING] BPR002: No Critical Rules section
  │ Missing "Critical Rules" or "Important Rules" section
  │
  └─ Add a section highlighting must-follow rules for Claude.

[INFO] FMT003: Missing code block language (line 56)
  │ ```
  │ npm install
  │ ```
  │
  └─ Specify language for syntax highlighting: ```bash

[INFO] CNT003: Overly long section (lines 100-215)
  │ "Architecture" section is 115 lines
  │
  └─ Consider breaking into subsections or condensing.

[INFO] FMT001: Inconsistent header styles
  │ Line 10: "## Quick Start"
  │ Line 25: "## Architecture:"
  │           (colon suffix inconsistent)
  │
  └─ Standardize header format throughout document.

---

Auto-fixable: 4 issues (run with --fix)
Manual review required: 6 issues

Run `/config-lint --fix` to apply automatic fixes.

Options

Option	Description
--fix	Automatically fix auto-fixable issues
--rules=LIST	Check only specified rule categories
--ignore=LIST	Skip specified rules (e.g., --ignore=FMT001,FMT002)
--severity=LEVEL	Show only issues at or above level (error/warning/info)
--format=FORMAT	Output format: text (default), json, sarif
--config=FILE	Use custom lint configuration
--strict	Treat warnings as errors

Rule Categories

Use --rules to focus on specific areas:

/config-lint --rules=security        # Only security checks
/config-lint --rules=structure       # Only structure checks
/config-lint --rules=security,content  # Multiple categories

Available categories:

• security - SEC rules
• structure - STR rules
• content - CNT rules
• format - FMT rules
• bestpractice - BPR rules

Custom Configuration

Create .claude-lint.json in project root:

{
  "rules": {
    "SEC001": "warning",
    "FMT001": "off",
    "CNT003": {
      "severity": "warning",
      "maxLines": 150
    }
  },
  "ignore": [
    "FMT*"
  ],
  "requiredSections": [
    "Quick Start",
    "Critical Rules",
    "Project Overview"
  ]
}

Anti-Pattern Examples

Hardcoded Secrets (SEC002)

# BAD
API_KEY=sk-1234567890abcdef

# GOOD
API_KEY=$OPENAI_API_KEY  # Set via environment

Hardcoded Paths (SEC001)

# BAD
Config file: /home/john/projects/myapp/config.yml

# GOOD
Config file: ./config.yml
Config file: $PROJECT_ROOT/config.yml

Contradictory Rules (CNT001)

# BAD
- Always use TypeScript
- JavaScript files are acceptable for scripts

# GOOD
- Always use TypeScript for source code
- JavaScript (.js) is acceptable only for config files and scripts

Vague Instructions (CNT002)

# BAD
- Be careful with the database

# GOOD
- Never run DELETE without WHERE clause
- Always backup before migrations

Invalid Hierarchy (STR002)

# BAD
# Main Title
### Skipped Level

# GOOD
# Main Title
## Section
### Subsection

When to Use

Run /config-lint when:

• Before committing CLAUDE.md changes
• During code review for CLAUDE.md modifications
• Setting up CI/CD checks for configuration files
• After major edits to catch introduced issues
• Periodically as maintenance check

Integration with CI/CD

Add to your CI pipeline:

# GitHub Actions example
- name: Lint CLAUDE.md
  run: claude /config-lint --strict --format=sarif > lint-results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: lint-results.sarif

Tips

1. Start with errors - Fix errors before warnings
2. Use --fix carefully - Review auto-fixes before committing
3. Configure per-project - Different projects have different needs
4. Integrate in CI - Catch issues before they reach main
5. Review periodically - Run lint check monthly as maintenance

Related Commands

Command	Relationship
/config-analyze	Deeper content analysis (complements lint)
/config-optimize	Applies fixes and improvements
/config-diff	Shows what changed (run lint before commit)