Small Linting Checks Beat One Big Linting Check: Real-Time Feedback for Coding Agents
Coding agents follow your rules far more reliably when a linter checks each file the moment they edit it, not once at the end of the task. Here is why, how to wire it into any major harness, and what 840 benchmark runs showed.
Rules the agent read and broke anyway
I had a CLAUDE.md / AGENTS.md full of rules like "never call Instant.now()" and "use apiClient, never raw fetch". The agent read them, nodded, and broke them anyway.
It usually happened somewhere around edit 40 of a session. So I only found out at the end, in the diff, or worse, in code review. Rewriting the rules more forcefully didn't help. Capital letters didn't help either.
Move the check to the moment of writing
A better prompt didn't fix it. Moving the check from the end of the task to the moment of writing did.
After every single file edit, a hook runs the linter on that one file. The agent sees the result on its next turn. If it wrote Instant.now(), it hears about it within seconds, fixes it while the line is still fresh, and moves on.
This is just a feedback loop. It's the same trick that made TDD click for humans, applied to agents:
| Small check | Big check |
|---|
| When | Right after each edit |
| Scope | One file, one fast linter |
| Cost | Under a second, silent when clean |
| Fixing a failure | One edit away |
Why the late check fails
A late check doesn't just find errors later. It finds them in a form the agent handles badly.
At the end of a 40-edit session, the compiler fails, the test suite fails, and lint reports 30 issues across 14 files. Half of them are in code you wouldn't have written. The agent now has to work out which change caused which error, often several edits apart.
That archaeology dig is where agents start taking shortcuts:
adding eslint-disable or # noqa
deleting or skipping the failing test
"I'll handle it later" When the check runs right after the edit, none of this is tempting. The fix is one edit away, and doing it properly is cheaper than working around it.
It works in every major harness
You need two hook points: one that fires after each tool call (to lint the file just edited), and one that fires when the agent finishes its turn (for the slower full check). Every major harness has both now.
| Harness | After each edit | End of turn | Where it lives |
|---|
| Claude Code | PostToolUse | Stop | .claude/settings.json |
| Codex | PostToolUse | Stop | hooks.json or config.toml |
| opencode | tool.execute.after | session.idle event | a plugin in .opencode/plugin/ |
| GitHub Copilot (CLI, cloud agent) | postToolUse | agentStop | .github/hooks/*.json |
| Pi | tool_result | agent_end | an extension in .pi/extensions/ |
The details differ: shell commands vs. TypeScript plugins, and how the hook's output reaches the model. The shape is the same everywhere. Filter for file-editing tools, run the linter on that one path, and return the failures so the agent reads them on its next step.
What we built: codemyrules
We packaged this as a small open-source hook setup, codemyrules (MIT). It does four things:
Per-edit check. After each file the agent edits, it runs your fast linters on that file only.
End-of-turn check. When the turn ends, it runs a slower full check on the files touched in that turn. You still get the big check, but as a safety net, not the first line of defense.
Blocks only on new problems. It fails only on errors in lines the agent changed since HEAD. Old lint debt in the file doesn't derail the agent.
Guards the escape hatches. It asks you before the agent can add a suppression comment or change the lint config.
What 1,280 runs showed
We tested this in agent-rules-bench: 1,280 headless agent runs, 1,532 sessions in total.
| Setup | Models | Runs | Projects |
|---|
| Claude Code | Claude Sonnet 5.5, Claude Haiku 5.5 | 1,048 | Java, Python, TypeScript |
| Claude Code (exploratory) | Claude Opus 5.5, Claude Fable 5.2 | 56 | TypeScript |
| Pi and Codex (exploratory) | Qwen3.6 35B-A3B, run locally | 176 | TypeScript |
The first four studies were exploratory. For the later ones, we pre-registered each analysis plan before we ran them.
The result: in our largest pre-registered study (two open-source projects), the agent broke a rule that was written as prose in the agent docs in 22% of runs (28 of 128). When we wrote the same rules as lint rules with the per-edit hook, the agent broke them in 13% of runs (17 of 128). Most of these breaks in the lint-rule runs look like false alarms from one checker, and we are still checking them by hand. The local model followed the same pattern more strongly: prose was broken in 73% of runs (47 of 64), lint rules in 30% (19 of 64). But in both setups, most of its code did not pass the type check.
Full data, prompts and analysis plans are in the repo.
Try it in your own repo
The principle doesn't depend on our tool or on any one harness:
Find the rules you keep restating. Read through your CLAUDE.md or AGENTS.md. Most of what you repeat there are lint rules in disguise.
Encode them as machine rules. A banned API, a required wrapper and an import boundary can all be custom lint rules in ESLint, Ruff, Checkstyle or similar.
Wire a post-edit hook. Lint only the file just edited, keep it fast and quiet when clean, and make sure the agent sees the failures right away. Keep prose for what a linter can't check: intent, architecture, trade-offs. Let the machine handle the rest.
I'm curious how others handle this. Do you run any checks mid-session, or do you trust the agent until the end of the task and then deal with the fallout?
Sources