Lint rules > docs (enforced > suggested)

Documentation that says "we use camelCase for variable names" is a suggestion.

·Documentation is treated as infrastructure (owned by engineering, not HR or PMO)
·Lint rules enforce conventions rather than relying on documentation alone (enforced > suggested)
·Knowledge graph of the codebase (CodeTale, Graph Buddy, or equivalent) is operational

·Documentation freshness is tracked (pages older than 90 days are flagged for review)
·Knowledge graph is integrated with agent context pipeline (agents query it at runtime)

Evidence

·Documentation ownership in engineering team's responsibility matrix
·Lint rules enforcing conventions with corresponding documentation references
·Knowledge graph dashboard showing codebase coverage

What It Is

Documentation that says "we use camelCase for variable names" is a suggestion. A lint rule that rejects non-camelCase variable names on every commit is an enforcement. Enforced standards require no motivation, no code review reminders, no culture campaigns. They apply consistently across every engineer, every PR, and every agent-generated commit. They are zero-maintenance after initial configuration because the tool maintains them.

The principle extends beyond naming conventions. Any standard that can be expressed as a detectable pattern can be enforced via lint: required docstrings on public functions, ADR links in files implementing architectural decisions, prohibited import patterns that violate layering rules, mandatory test presence for new modules, required environment variable documentation in configuration files. Each of these can live in a documentation page that engineers are asked to follow — or it can live in a lint rule that enforces compliance automatically.

Lint rules are superior to documentation for enforcing standards for three interconnected reasons. First, they apply at the moment of violation, not at the moment of review — the feedback loop is minutes, not days. Second, they apply uniformly — no reviewer fatigue, no inconsistency across teams, no exceptions for senior engineers who are too senior to be told about style. Third, they apply to AI-generated code. When an agent generates a PR, it runs through the same lint checks as human code. Lint rules are one of the primary mechanisms for maintaining code quality in a world where a significant fraction of committed code was generated by an agent, not reviewed carefully line by line.

At L3, the shift is from maintaining standards through documentation and review to maintaining them through automated enforcement. This does not eliminate documentation — it changes what documentation is for. Documentation explains the reasoning behind standards; lint rules enforce the standards themselves. The documentation answers "why do we do this?" The lint rule ensures it is done.

Why It Matters

Agents follow lint rules automatically - a lint rule in a pre-commit hook or CI pipeline applies to every commit regardless of source; agents working in the repository will naturally produce compliant code because non-compliant code fails the checks they observe and respect
Review bandwidth is finite; lint is not - code review can enforce five or six standards reliably before reviewer attention degrades; lint can enforce fifty without fatigue, inconsistency, or interpersonal friction
Lint rules document standards in executable form - a lint configuration file is a machine-readable specification of what the codebase requires; agents can read lint configuration to understand project standards without relying on documentation that may have drifted
Enforcement reduces onboarding friction - new engineers do not need to memorize all standards before contributing; the lint tool teaches them through immediate feedback on their first PRs, without requiring a senior to notice and correct violations in review
Standards without enforcement create two-tier teams - documented-but-unenforced standards will be followed by conscientious engineers and ignored by engineers who are busy or unconvinced; this creates inconsistency that is worse than having no standard at all

Getting Started

Audit your existing documented standards - collect every "we do X because Y" rule in your READMEs, coding conventions docs, and onboarding materials. Sort them into two categories: standards that can be expressed as a detectable pattern, and standards that require human judgment. The first category is a lint rule backlog.
Start with zero-controversy rules - pick the five documented standards that are most universally agreed upon and convert them to lint rules first. These are your proof of concept. Don't start with the contested rules — start with the ones where "why isn't this already a lint rule?" is the natural question.
Choose your enforcement stack - identify which lint tools are appropriate for your languages and contexts: ESLint for JavaScript/TypeScript, Ruff or Pylint for Python, custom rules via ast-grep or semgrep for language-agnostic structural patterns, custom CI scripts for documentation requirements. Add a configuration file to the repository that represents the canonical standard.
Add lint to CI as a required check - lint must run on every PR and block merge on failure. A lint check that is advisory is not enforcement. If the organization is not ready to fail PRs on lint violations, start with a subset of rules as warnings and graduate them to errors after the codebase has been cleaned up.
Address the existing violation baseline - before adding new lint rules, fix existing violations or mark them with suppression comments that require justification. A PR that adds a new lint rule and immediately shows 3,000 violations is not useful. Do a cleanup commit first, then add the rule as a required check going forward.
Document the reasoning, enforce the standard - for each lint rule, write a one-line comment in the lint configuration explaining why the rule exists. This preserves the institutional knowledge without relying on a separate documentation page that may drift.

Tip

Write lint rules with actionable error messages. "Prefer const over let" is an instruction an engineer or agent can act on immediately. "Variable declaration error" is not. The error message is documentation: it should explain both what is wrong and why the rule exists.

6 steps to get from here to the next level

Common Pitfalls

Over-tightening rules before the team has bought in. A lint configuration that fails 30% of PRs on the first day will be met with resistance, suppression overrides, and eventual removal of the rules. Start with rules the team already agrees with, prove the model, then expand. Enforcement is most durable when it feels like help, not surveillance.

Writing lint rules without exception mechanisms. Some standards are universal; some have legitimate exceptions. A lint rule with no suppression mechanism will be worked around via creative code rather than documented exceptions. Provide a suppression comment format that requires a reason: // lint-disable-next-line: camelCase -- external API uses snake_case. This makes exceptions visible and auditable.

Letting lint configuration drift from documented standards. If the documented coding conventions say one thing and the lint rules enforce another, engineers will follow the lint (because it fails CI) while the documentation becomes fiction. Keep lint configuration and documentation in sync, or eliminate the documentation in favor of comments in the lint config.

Applying lint rules retroactively to unrelated PRs. When a new lint rule is added, existing violations should be cleaned up in a dedicated commit, not in unrelated feature PRs. Mixing lint cleanup with feature changes makes code review harder and creates noise in the git history that obscures meaningful changes.

Confusing lint rules with architectural guardrails. Lint rules are good for local patterns: naming conventions, required docstrings, import restrictions, prohibited API usage. They are not good for system-level architectural constraints that require understanding of the full system context. Architectural standards that cannot be expressed as local detectable patterns should remain in ADRs and documentation, not forced into lint rules that will be incomplete or incorrect.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has a documented coding standards document that no one fully follows. Code review occasionally catches violations, but reviewers have different opinions about which rules matter most, and the inconsistency across teams is a constant source of friction. He has been told that enforcing standards more consistently requires either more senior reviewer time (which is not available) or a cultural change that hasn't happened despite years of trying.

Lint rules solve Bob's consistency problem structurally. He should commission a one-sprint effort to convert the top 20 standards from the coding conventions document into enforced lint rules. The output is a lint configuration file, a cleanup commit, and a required CI check. After this, those 20 standards are enforced on every commit, every PR, and every agent-generated change — without consuming additional senior reviewer time. Bob should frame this to his team as a reviewer bandwidth investment: "every rule we enforce via lint is a rule that doesn't consume review attention." The long-term goal is a team where code review focuses on logic and design — the things that require human judgment — not on naming and formatting, which are better handled by tools.

SarahProductivity Lead

Sarah has observed that engineers who join from well-linted codebases onboard faster to new standards than engineers who join from loosely enforced ones. The difference is muscle memory: engineers who are used to lint feedback accept it as part of the development cycle; engineers who are not often experience it as bureaucratic friction. She wants to use lint as an onboarding accelerator, not an obstacle.

Sarah should work with Victor to make the lint configuration a documented artifact in the onboarding path. New engineers should understand which tools enforce which standards, why each rule exists, and how to work with the lint feedback rather than against it. She should track the rate of lint suppression comments added by new engineers in their first month — a high rate suggests the lint rules feel arbitrary or obstructive. She should use that signal to identify rules that need better documentation, better error messages, or genuine reconsideration.

VictorStaff Engineer - AI Champion

Victor has a specific problem that lint rules solve directly: when agents generate code, that code must meet the same standards as human-written code, but agents cannot read the coding conventions document and apply it reliably across thousands of lines. Lint rules translate the conventions document into machine-executable form. An agent that generates code in a repository with strong lint enforcement will naturally produce compliant code because non-compliant code fails the CI checks the agent observes.

Victor should champion converting every standard that can be expressed as a lint rule into a lint rule, with a specific focus on the standards that most often cause agent-generated code to fail review. He should use semgrep or ast-grep for language-agnostic structural patterns that are not covered by standard language linters: prohibited architectural patterns, required documentation annotations, forbidden import paths. He should also ensure that lint rule configurations are included in the context provided to agents through the CLAUDE.md file or MCP server, so agents can read the configuration directly and understand what is required before generating code.