code-linting

Code linting

A linter's job is to make an entire category of review comment impossible. Every rule you enable should retire a conversation nobody should have again.

The failure mode: a lint config so noisy that people run it with --no-verify, or so lax it catches nothing. Both end with the linter ignored. Aim for a config where every reported problem is worth fixing, because that is what keeps the signal trusted.

1. Find out what already exists

Never add a second linter alongside a working one. Check for config files, CI lint steps, and editor settings before proposing anything.

ls -a | grep -Ei 'lint|format|pre-commit|editorconfig|prettier|ruff|eslint'

Also check whether it currently passes. A config that has been failing for months is a different problem from a missing config — that one is a decision to make, not a tool to install.

Done when: you know which tools are configured, whether they run in CI, and whether they currently pass.

2. Pick the stack's tooling

Read the matching reference for the recommended tool, its config, and the rules worth enabling or disabling:

Stack	Reference
Python	references/python.md
JavaScript / TypeScript	references/javascript.md
Go	references/go.md
Rust	references/rust.md
Java / Kotlin	references/jvm.md
Ruby	references/ruby.md
Shell	references/shell.md
SQL	references/sql.md
Markdown / YAML / JSON	references/markup.md
Docker / Terraform	references/infra.md

For a stack not listed, apply the principles below and prefer the ecosystem's dominant tool over the technically best one — adoption beats capability for a linter.

Done when: one formatter and one linter chosen per language in the repo.

3. Separate formatting from linting

These are different jobs and conflating them causes most lint pain.

• Formatting is not a matter of opinion once a tool is chosen. Zero configuration, run on save, auto-fix always, never discussed again.
• Linting catches likely bugs and real hazards. It requires judgment and should be tuned.