# Three files per task: the blast-radius cap I impose on every AI agent

The most useful guardrail I've added to my agentic coding workflow isn't a better model, a longer context window, or a fancier system prompt. It's a hard rule: **three files per task.** Anything bigger gets split, even when the agent volunteers to do it in one shot.

I didn't arrive at this from theory. I arrived at it after a week of agents that cheerfully touched twelve files, ran the tests, said done, and left me to untangle a refactor that had quietly moved three unrelated subsystems in the same commit.

## What the cap actually prevents

When an agent can touch ten files in one task, three failure modes show up together:

1. **It stops reading.** By file seven, it's patching each file against the memory of the earlier ones, not against the actual code on disk. Small inconsistencies accumulate — a renamed helper used three different ways, an import left behind, a comment that no longer matches the function.
2. **The diff becomes unreviewable.** A ten-file diff is where human review quietly gives up. You scan it, nod, and hit approve. That's not review; that's courtesy.
3. **The rollback becomes nuclear.** Halfway through you realize the approach is wrong. Reverting means throwing out the work that was going well too, because it's all tangled in one change.

## How I actually enforce it

I don't ask the agent nicely. I state it as a constraint up front, every task:

> Scope: at most 3 files. If the change needs more, stop and tell me which files you'd touch and why — I'll split it into separate tasks.

Roughly a third of the time, the agent pushes back and lists the files. Half of those times, looking at the list, I realize the task was actually two tasks wearing one description. The other half, I say no — split it.

The other two-thirds of the time, it just works. The agent stays within the boundary, reads each file properly, produces a diff I can actually read in ninety seconds, and the tests cover one coherent slice.

## Where this falls apart

The cap is wrong for two kinds of work. Don't apply it blindly.

**Mechanical migrations** — rename a symbol across 40 files, update a config schema everywhere, bump a dependency. Those are uniform and the agent is genuinely good at them. Three files is absurd here.

**New-file scaffolding** — generate a new module, its tests, and a wire-up. Three new files is exactly one coherent unit. That fits the cap naturally; the cap helps, it doesn't fight.

The cap is for *behavior* changes: logic that touches existing paths, where the risk is the agent quietly coupling two things that should have stayed apart.

## The side effect nobody tells you about

Once you start splitting tasks by file count, you start splitting them by *intent* too. A task that needs six files almost always contains two or three separable intents wearing one ticket. Forcing the agent to list the files makes that visible, fast.

I noticed the same thing on the API side. When I let an agent regenerate a whole OpenAPI spec in one pass, it'd rename fields across every endpoint at once and I'd spend an hour catching up. When I capped it at "one endpoint, one contract, one re-run against the live server" — the way we run it locally in [Powerduck](https://www.powerduck.com/) — each diff was small enough to read, and the spec stayed the source of truth instead of drifting behind the agent's momentum.

Same principle. Small blast radius, real reviewable diff, one intent per change. The model gets smarter every month; the human attention budget doesn't.

## Try it this week

Next time you hand a task to an agent, add one sentence: *Three files max. List what you'd touch before you start.*

You'll be surprised how often the honest answer is "actually this needs to be two tasks."