---
title: "Lint Rules Beat Rules Files for AI Coding Agents"
description: "Lint rules for AI coding agents beat another line in a rules file: a correction written into code is enforced, reproducible, and cannot be argued around."
author: "MDflow"
date: 2026-11-18
reading_time: "19 min"
canonical_url: https://mdflow.cz/blog/lint-rules-for-ai-coding-agents
md_url: https://mdflow.cz/blog/lint-rules-for-ai-coding-agents.md
---

# Lint Rules Beat Rules Files for AI Coding Agents

*Published November 18, 2026 · 19 min read*


You correct your coding agent. It used the wrong API, imported across a boundary it should not have crossed, patched a symptom instead of a cause. Now: where does that correction go?

Most teams type it into a rules file. It is the path of least resistance — one more bullet in `AGENTS.md`, one more line in `CLAUDE.md`, done in ten seconds. And it is the weakest place the correction could possibly land. **Lint rules for AI coding agents beat rules files** for a reason that has nothing to do with linting being fashionable: a lint rule is enforced, and prose is not.

> **TL;DR** — **Every correction you give an agent should become a deterministic check, not another line in a rules file.** Your codebase is one of the largest inputs your agent gets, so workarounds and dead code get copied as if they were house style; prose instructions are unenforceable, go stale, and give the agent an escape hatch to justify the wrong thing. Fix it in code first (API design, architecture, lint rules, types), add verification second, and keep prose for the judgment that nothing can check — small, canonical, and versioned, which is where a markdown workspace like [MDflow](https://mdflow.cz) belongs. [Start free](/login).

## What a deterministic correction is

**A deterministic correction is a correction that executes.** It is a lint rule, a type, a compiler error, a banned import, a test, or — best of all — an API redesign that makes the mistake impossible to express. The opposite is a probabilistic correction: a sentence in a rules file, a skill, or a code comment, which influences the next agent only if that agent reads it and chooses to comply.

The framing comes from [*All Code Is Slop (Except Mine)*](https://www.youtube.com/watch?v=O_zcc6Xl12g), a talk Lauren Tan — who goes by Potato — gave at AI Engineer, published on 14 November 2026. She works on Grok Bot, and her thesis is blunt: the job of a software engineer is now figuring out how to hold or improve quality while massively increasing output, and getting there is a matter of **trust** — not blind trust, but trust earned by investing in the agent's environment.

She orders that investment as an inverted pyramid, widest layer first:

1. **The code itself** — API design, architecture, refactoring. The layer that eliminates whole categories of mistake.
2. **Static analysis** — lint rules, type systems, compilers, tests. Deterministic, reproducible, cheap to run.
3. **Verification** — runtime and formal. Checks that the thing actually does what was asked, and that the agent understood the goal.
4. **Prose** — rules, skills, agent instruction files. Last, thinnest, and reserved for what genuinely requires judgment.

The ordering is the argument. Most teams work it upside down, because prose is the only layer you can edit in ten seconds.

## Why a rules file is the weakest place for a correction

**Because agents generate output from their inputs, and your codebase is a much bigger input than your rules file.**

Code used to arrive a few pull requests at a time. Tan's comparison: reviewing three colleagues' pull requests in 2024 versus something closer to 300 today, with code arriving as a near-continuous stream. At that rate the codebase stops behaving like an artifact and starts behaving like an ecosystem — her phrase is that the job "is kind of becoming like gardening."

The consequence is mechanical. Any workaround, anti-pattern, deprecated helper or piece of tech debt sitting in your repository **looks exactly like an established convention** to the next agent. It has no way to tell a deliberate pattern from one nobody got round to deleting. So it copies. Weeds spread.

That gives you the test for where a correction belongs: if the agent got it wrong because the codebase showed it the wrong thing, no amount of prose will outrank the example. Delete the example.

There is a second failure mode, and it is the one most teams have not noticed yet.

### Markdown becomes the agent's excuse ledger

Tan reports agents using markdown — documentation, comments, rules, skills — as **a place to record justifications for not doing the right thing**. The agent takes the harder-but-correct path, finds it hard, takes the easy path instead, and writes down why that was acceptable. She also describes the opposite distortion: an agent over-rotating on a small correction and treating it as a hard rule that may never be broken again.

Her example is concrete. At a previous product — Cursor, an Electron app — agents reached for imperative timers (`setTimeout`, `requestAnimationFrame`, `requestIdleCallback`) as quick fixes. The real problem was an architectural clash between VS Code's imperative style and React's declarative one. Each timer was a patch over that clash, and each one arrived with a comment explaining why the patch was justified. Timers spread; rapid creation and destruction of them drives major garbage collection; the app got janky.

The comments were the mechanism, not the evidence. The next agent read a justification and treated it as precedent.

So Grok Bot now bans roughly **99% of comments**. The reasoning Tan gives is worth separating into its four parts, because only one of them is about agents:

- Comments go stale.
- Humans do not read them anyway.
- They give an agent an escape hatch to justify the hard thing not being done.
- **They are not enforceable.** A well-intentioned note to the next agent is not something you can trust.

What replaced them: lint rules with good error messages that tell the agent to fix the root cause rather than patch around it.

## Three corrections that became code

The pattern is easier to copy than to describe, so here are her three examples, in increasing order of leverage.

**1. Ban the API that needs nuance.** Their client framework — Dune, which she compares to a Next.js-style framework for Electron apps — bans React's `useEffect` in product code, allowing it only inside a few framework APIs. The reasoning generalises well past React: an API that needs judgment to use well is a reliable source of slop, and judgment is the thing agents are worst at. The problem was not mitigated, it was categorically eliminated. Nobody reviews for it again.

```text
Correction:  "don't reach for useEffect here"
Weak form:   a line in the rules file
Strong form: the import fails lint in product code
```

**2. Make the boundary a directory.** The Cursor anti-pattern was agents importing main-thread code into the renderer thread, which produces long tasks and jank. Their fix is conventional to the point of being boring: two top-level directories, one for each Electron process, with imports between them forbidden by a dependency-graph analyser and lint rules. The boundary is now visible in the file tree *and* enforced at build time. One less thing to carry in your head during review.

**3. Write the error message for the agent.** The lint rules are not just blocks; they carry the diagnosis. An error that says *fix the root cause, which is X* teaches in the moment the mistake is made, which is the only moment anything is reliably read.

Her general principle, stated as a loop: every time you correct an agent, turn it into a deterministic check, or think about how to eliminate that whole class of problem through better API design or architecture. Do it enough times and review has less and less to catch — until most pull requests can simply merge.

## Verification is the second investment, and it is where the tokens go

**Once the deterministic layers hold, code review stops being about the diff and becomes about the proof.**

Tan says their review has largely shrunk into reading **verification artifacts**: videos, screenshots, diagrams, formal-verification output. The diff tells you what changed. The artifact tells you whether the agent understood what you wanted — which is the thing you actually could not check.

The layers she describes:

- **Runtime verification** — give the agent a way to run the code and drive it with the same debugging tools a developer uses, such as the Chrome DevTools Protocol. Two details are worth stealing. Their runtime-verification skills include a **feature map**: effectively a site map of every feature from the user's point of view, so "the thing in the left sidebar" resolves to a shared vocabulary instead of a guess. And the skills call **custom CLIs** rather than re-deriving a driver each time, which cuts token use and makes the driver itself testable — the argument we made in [CLI Design for AI Agents](/blog/cli-design-for-ai-agents).
- **Formal verification** — TLA+ model checking on major user flows, her example being notifications across multiple devices and platforms, and Lean for proving properties of algorithms such as their own virtualization library (no flickering, no jitter). It has already found bugs. She is explicit that it is not a silver bullet and that they are still experimenting; treat it as one more layer, not a replacement.
- **Property-based testing for UI** — newer, already catching UI bugs.
- **A state-chart skill** — she built a skill that renders a flow as a state machine from the user's point of view, and finds it easier to review than the code, especially alongside the videos and screenshots.

The cost profile is the part to internalise. Tan quotes a developer who, six months earlier, could not trust her agents because subtle bugs kept getting merged, and who now reports that **70% of her daily tokens go into verification** — a figure Tan says matches her own usage. If most of your agent spend is still generation, your loop is probably producing work nobody can check.

None of these techniques are new. Model checking, property-based testing and proof assistants have been available for decades and were usually too expensive to justify on application code. What changed is that agents collapsed the cost of writing and maintaining the specifications. The cheap verifier arrived before the careful engineer did.

## What it bought them — and what to discount

These are one team's self-reported numbers, from a talk that ends with a pitch for the speaker's own product. Read them as directional, not as a benchmark:

| Measure | Reported |
| --- | --- |
| Pull requests she shipped personally, last month | ~3,000 |
| Pull requests her team shipped to production, last month | ~11,000 |
| Contributors with at least one pull request, October | ~227 |
| Stable client releases | about one a day |
| Reverted pull requests | steady at ~0.5% |
| Time to build the environment that allows it | ~6 months |

The rows to read together are the volume and the reverts: output up roughly two orders of magnitude against 2024-era review, revert rate **down** on a relative basis, and app performance improved since launch on startup, typing, opening and switching chats — in an Electron app, with 227 people and an unknown number of agents committing into it.

The capstone example of what high trust looks like: each new release automatically spins up a project that fuzzes the whole build by using the app like a real user, opens a fix pull request per bug it finds, and **auto-merges them**. That is only sane because the foundations make a good pull request the default.

## Where this disagrees with "software factories fail"

We have [argued](/blog/why-ai-software-factories-fail) that lights-off AI software factories fail: models are trained to make tests pass, maintainability has no cheap verifier, and an adversarial reviewer model shares the author's blind spot — so, in Dex Horthy's framing, for now you are stuck reading the code.

Tan is not stuck reading the code. She reports most product code no longer needing deep human review, and fix pull requests merging themselves. That is a real disagreement, and it is worth stating rather than smoothing over.

What they agree on is where the work goes. Neither answer is a bigger reviewer model. Horthy's is written artifacts agreed by humans before the agent starts; Tan's is constraints and verification built into the environment before you automate anything. Same move: **spend upstream so the pull request is one you already expect.** She says it directly — if your inner loop produces slop, automating that loop produces more slop at a higher token bill.

Where to keep your scepticism: her evidence that it holds is a revert rate of about half a percent and improved performance. **A revert rate measures breakage within days.** The thing Horthy says has no cheap verifier is maintainability over months — *this is the fourth abstraction doing the same job* is not a lint rule, and no model checker will catch it. Her deterministic layers do genuinely verify some architectural properties that used to need a reviewer, which is the strongest form of the counter-argument. They do not verify all of them.

So: build the checks, and keep reading the code in the places a check cannot reach.

## Which teams benefit most

1. **Teams where agents write most of the code.** The correction-to-check conversion compounds with volume; below a few pull requests a day, review still catches things.
2. **Teams on a framework with nuanced APIs.** React, async-heavy code, anything with an implicit lifecycle. These are where "ban it in product code" buys the most.
3. **Monorepos with boundaries that matter.** Process boundaries, package boundaries, client/server splits — all enforceable, all commonly enforced only by convention and reviewer memory.
4. **Products where the bug is visual or temporal.** Jank, flicker, race conditions. The diff shows nothing; a recording or a model check shows everything.
5. **Teams with many drive-by contributors.** Tan's 227 October contributors mostly lacked deep context. Constraints in code are how a stranger's agent still lands a good change.
6. **Anyone about to build an orchestration layer.** This is the prerequisite work. Automating an unverified loop is how you buy slop in bulk.

## How MDflow fits

Start with the boundary, because this topic cuts against the product. **MDflow is the prose layer.** It is a markdown workspace: it stores documents and serves them to agents. It runs no linter, enforces no rule, and blocks no commit. In Tan's pyramid it is the fourth layer: the last one, and the one she argues should be thinnest.

We think that is right, and it is the more useful claim than pretending otherwise. The lesson of her talk is not *write no prose*; it is **write prose only for what no check can decide, then treat that prose like code**. Her objections to comments were specific: they go stale, nobody reads them, they are not enforceable, and they drift into justification. Three of those four are properties of *where the prose lives*, not of prose itself.

**What lines up today**

- **One canonical copy, outside the codebase.** Judgment-layer context in a workspace is not sitting in the repository where the next agent reads it as an established pattern. Folder descriptions state what a set of documents is *for*, and `mdflow_get_context` ranks those descriptions above names and titles — so the agent is handed the brief rather than grepping for it. That mechanism is the subject of [Folder Descriptions as Agent Context](/blog/folder-descriptions-agent-context).
- **Stale prose becomes visible instead of silent.** Pro accounts keep [version history](/features) per document, and capture covers every write path — the editor, the HTTP API and the MCP server — so an agent's own edit leaves a previous version behind, with a line-by-line diff and a non-destructive restore. The staleness problem Tan names is partly just prose with no revision log at all.
- **Agents can retire it, not only read it.** The [remote MCP server](/docs/mcp) and the [HTTP API](/docs/api) are read **and** write, so the same loop that notices a rule is obsolete can delete it. Prose nobody can retire is how a rules file becomes a graveyard — see [Let AI Agents Write to Your Knowledge Base](/blog/ai-agents-write-to-knowledge-base).
- **Reviewable by humans in the same place.** Shared links, private sharing by email, comments and raw `.md` twins mean the judgment layer can be argued over by people, which is the only review a judgment call can get.

> **Connect Claude to MDflow:** open the [MDflow connector](https://claude.ai/directory/mdflow) in Claude's Connectors Directory, click **Connect to Claude**, and sign in — no URL or token to paste. One connection covers claude.ai, the Claude desktop and mobile apps, and Claude Code signed in with a Claude subscription. A Personal Access Token is the legacy route for Claude, and the route for clients that send their own auth header, such as Cursor, Codex and the HTTP API.

**Where the report card is worse.** MDflow cannot tell you whether a document is still true, which is the hard half of the staleness problem. There is no deprecation state, no owner-review date, no "this rule is now a lint rule, stop reading it" marker. Version history is also private to the document owner and is not exposed over the API or MCP, so an agent cannot ask what changed and when. If your judgment layer has grown past what one person can re-read, that gap is real.

**Where we are headed** — direction, not a dated commitment. The folder description stays the primitive we invest in, because stating a set of documents' purpose is what makes retrieval work without an index. The other thread is narrowing the distance between where prose is edited and where it is version-controlled, which is why in-place editing for GitHub, Google Drive and OneDrive already ships: a rule that genuinely belongs beside the code can be edited where it lives, instead of being copied into a workspace to drift. Those files are edited *through* MDflow rather than served *by* it — they sit outside workspace search, retrieval and version history — so an agent still reads them from the repository.

## The bottom line

The question to take from the talk is small enough to use today, on the next thing your agent gets wrong: **can this correction be made deterministic?**

If the agent copied a bad pattern, delete the pattern. If it reached for an API that needs nuance, ban the API in product code. If it crossed a boundary, make the boundary a directory and fail the build. If it patched a symptom, write the lint error that names the cause. Only when none of that is possible should the correction become prose — and then it belongs somewhere canonical, dated and reviewable, not appended to a file nobody re-reads.

Then spend your tokens on proof rather than on more generation. The teams shipping thousands of pull requests a month are not reviewing thousands of diffs. They are reading artifacts, and trusting the floor underneath them.

[Start free](/login), [connect an AI agent](/docs/mcp), or [read the API docs](/docs/api).

## Frequently asked questions

### Should a correction to an AI coding agent go in a lint rule or a rules file?

In a lint rule, whenever the correction can be expressed as one. A rules file is prose: nothing enforces it, it is read probabilistically, it goes stale silently, and an agent can write a justification for ignoring it. A lint rule fails the build every time, gives the same message to every agent and every human, and can carry the fix in its error text. Lauren Tan's rule of thumb in her AI Engineer talk is that every time you correct an agent, you ask how that correction becomes a deterministic check instead of another line of prose.

### Why do AI coding agents copy bad patterns from a codebase?

Because the codebase is one of the largest inputs they get, and an existing workaround looks exactly like an established convention. An agent cannot tell a deliberate pattern from a deprecated one that nobody got round to deleting, so tech debt, anti-patterns and dead code get reproduced by the next agent as if they were the house style. That is why cleaning the codebase is a higher-leverage intervention than adding instructions about it.

### Why ban code comments for AI agents?

Because an agent will use a comment to justify not doing the right thing, and nothing enforces a comment. Tan's team found agents writing explanations for why a quick fix was acceptable, then the quick fix spreading because the next agent read the justification as precedent. Her team now bans about 99% of comments and replaces them with lint rules whose error messages name the root cause to fix. Comments also go stale silently, which makes them unreliable as agent context.

### What are verification artifacts in AI code review?

Evidence an agent produces to show that the code it wrote does what was asked: a screen recording, screenshots, a state diagram of the flow, a model-checking result, a property-based test run. Tan reports that her team's review has largely shrunk into reading these artifacts rather than the diff, because the diff no longer tells you whether the agent understood the goal. Reviewing the proof is also what makes the volume survivable.

### Is formal verification practical for application code now?

It is being used in production on narrow, high-value targets, with the honest caveat that it is not a silver bullet. Tan's team model-checks major user flows such as cross-device notifications with TLA+, uses Lean to prove properties of a custom virtualization library, and is experimenting with property-based testing for UI. The economics changed because agents cut the cost of writing and maintaining these specifications, not because the techniques are new.

## Further reading

- [*All Code Is Slop (Except Mine)*](https://www.youtube.com/watch?v=O_zcc6Xl12g) — Lauren Tan, AI Engineer, 14 November 2026. The primary source for everything attributed above.
- [TLA+](https://lamport.azurewebsites.net/tla/tla.html) — Leslie Lamport's specification language, used for the model checking described in the talk.
- [Lean](https://lean-lang.org/) — the proof assistant and programming language.
- [Why AI Software Factories Fail](/blog/why-ai-software-factories-fail) — the maintainability gap, and the case that you are still stuck reading the code.
- [Loop Engineering: Control Loops for Coding Agents](/blog/loop-engineering-agent-control-loops) — how to drive the cleanup once you know what to enforce.
- [The Generator Cannot Be the Validator](/blog/generator-cannot-be-the-validator) — why at least one deterministic check has to stay in the loop.
- [Prose Engineering: Your Agent Is Mostly Not Code](/blog/prose-engineering-for-ai-agents) — the counterweight: what to do with the prose layer you cannot eliminate.
- [AGENTS.md, CLAUDE.md, SKILL.md, llms.txt Explained](/blog/agents-md-claude-md-skill-md-llms-txt) — what each agent instruction file is for, and where each belongs.
- [MDflow MCP docs](/docs/mcp) and [HTTP API docs](/docs/api) — connecting an agent to the prose layer.

