Write Linters and Tools Before Code

Large language models are unreliable at preserving document-wide structure because they sample tokens without persistent state: attention favors the beginning and end of a context window, variance persists even at low temperature, and each generation re-derives many branching decisions. The productive remedy is to stop asking models to invent structure and instead encode structure as executable artifacts: grammars, parsers, linters, schema validators and builders. A linter is a deterministic oracle that parses an artifact, applies rules, reports line-numbered errors and exits non-zero; that transforms subjective style into verifiable constraints and lets non‑deterministic systems be optimized against a clear passing condition. Agents should be limited to high-volume, low-branching gruntwork like summarization and filling sections, while structural decisions live in tools.

Concrete practices include writing a formal grammar and invariants, reusing a single parser for linting and rendering, creating deterministic fixers, and building serializers for binary formats so the model emits structured data rather than raw bytes. Markdown needs strict rules because of dialect ambiguity; examples of enforceable rules are a single h2 matching the title, ASCII-only h3/h4 under length limits, no h5, fenced code blocks tagged with a language, and mandatory sections and metadata. Gate repositories on the linter and run a tight loop of generate → lint → auto-fix/revise until zero errors so large-scale generation produces structurally valid outputs.