Architecture

This document describes the internal architecture of claudelint for contributors. For the project's validation philosophy, scope boundaries, and design principles, see Design Philosophy.

System Overview

claudelint runs all validators in parallel, each executing its category's rules against discovered files, then aggregates and formats the results.

CLI / API

claudelint check-all or programmatic call

↓

Configuration

Merge CLI flags, .claudelintrc.json, defaults

↓

File Discovery

Find files matching validator patterns

↓

Parallel Validators

10 validators run concurrently via Promise.all

↓

Rule Execution

Each rule checks one aspect, reports violations

↓

Formatters

stylish, json, compact, sarif, github

↓

Exit Code

0 = clean, 1 = warnings, 2 = errors

Rules vs Validators

claudelint uses a rule-based architecture inspired by ESLint. Understanding the distinction between rules and validators is critical for contributors.

Rules

Rules are what contributors write. They are individual, focused validation checks located in src/rules/{category}/{rule-id}.ts.

Characteristics:

• 114 rules total organized into 10 categories (ClaudeMd, Skills, Settings, Hooks, MCP, Plugin, Agents, Output Styles, LSP, Commands)
• User-configurable - Can be enabled/disabled, severity changed per-project
• Self-contained - Each rule validates one specific aspect
• Metadata-driven - Include id, name, description, severity, fixable flag
• ESLint-style - Similar pattern to ESLint rules

Validators

Validators are internal orchestrators — classes in src/validators/ that collect and run rules.

Characteristics:

• 10 validators (one per category)
• Not user-facing - Users interact with rules, not validators
• Implementation detail - Orchestrate file discovery, parsing, rule execution
• Extend FileValidator or SchemaValidator - Share common validation infrastructure

See the Validators reference for details on each validator.

Validation Pipeline

A claudelint check-all invocation flows through these stages:

Configuration

The CLI loads configuration from .claudelintrc.json (if present), merging CLI flags, config file settings, and default values. Config controls which rules are enabled, severity overrides, and options like --fix and --cache. See the Configuration Guide for resolution order.

File Discovery

Each validator declares file patterns (e.g., SKILL.md, .mcp.json). Validators discover matching files in the project directory, respecting .gitignore and path filters. See File Discovery for the complete list.

Parallel Execution

All enabled validators run concurrently via Promise.all(). Each validator independently:

1. Finds files matching its patterns
2. Reads and parses file contents (Markdown, JSON, YAML)
3. Executes its category's rules via executeRulesForCategory()
4. Aggregates results

Total wall-clock time equals the slowest validator, not the sum.

Rule Execution

Each rule receives a RuleContext with the file path, content, and user-configured options. Rules call context.report() to emit violations with messages, line numbers, and optional auto-fixes. See the Rule System for implementation patterns.

Result Formatting

Results are formatted for output. Built-in formatters: stylish (default table), json, compact, sarif, and github (for PR annotations). Custom formatters can be loaded by path. See the API Formatters docs for details.

Exit Code

• 0 — No errors or warnings
• 1 — Warnings found (or errors with --warnings-as-errors)
• 2 — Errors found

Project Structure

claudelint/
├── src/
│   ├── api/               # Programmatic API (ClaudeLint class, formatters)
│   ├── cli/               # CLI commands (Commander.js)
│   ├── rules/             # Validation rules (auto-discovered)
│   │   ├── claude-md/     # CLAUDE.md rules
│   │   ├── skills/        # Skills rules
│   │   ├── settings/      # Settings rules
│   │   ├── hooks/         # Hooks rules
│   │   ├── mcp/           # MCP rules
│   │   ├── plugin/        # Plugin rules
│   │   ├── agents/        # Agents rules
│   │   ├── lsp/           # LSP rules
│   │   ├── output-styles/ # Output Styles rules
│   │   └── commands/      # Commands rules
│   ├── schemas/           # Zod schemas for frontmatter validation
│   ├── types/             # TypeScript types and interfaces
│   ├── validators/        # Validator orchestrators
│   └── utils/             # Shared utilities
├── tests/                 # Test files
├── skills/                # Claude Code plugin skills
├── .claude-plugin/        # Plugin manifest and metadata
├── website/               # VitePress documentation site
├── scripts/               # Build and automation scripts
└── schemas/               # Generated JSON schemas

Key Subsystems

API Layer

claudelint exposes both a CLI and a programmatic API that share the same validation engine. The API in src/api/ provides a class-based interface (ClaudeLint) and functional utilities (lint, lintText, formatResults), making claudelint embeddable in other tools, editors, and CI scripts.

Schema Layer

Zod schemas in src/schemas/ define the expected structure of skill frontmatter, agent frontmatter, output style frontmatter, and other configuration formats. Schema-delegating rules wrap these schemas as thin validators, keeping validation logic in one place while making each check individually configurable.

Caching

The ValidationCache caches results keyed by validator name. Cache entries are invalidated when the claudelint version, configuration, or file modification times change. Enable with --cache or the cache config option.

Diagnostic Collection

Library code uses DiagnosticCollector instead of console directly. This keeps the library testable, supports programmatic usage, and provides structured diagnostics with source tracking.

See Also

• Rule System — Rule interface, implementation patterns, and registries
• Internals — Caching, parallel execution, and CLI implementation details
• Custom Rules — Build your own validation rules
• Contributing — Contribution guidelines and rule checklist