AI Coding Agent Guardrails: The Three-File Rule
Set a three-file limit for AI coding agents to keep changes reviewable, reduce rework, and split risky tasks. Learn when the rule helps—and when it doesn't.
The Three-File Rule for Safer AI Coding Changes
AI coding agents can make broad changes across a codebase in a single go. That's useful - but it's also how you end up with a diff that looks "complete" (tests pass, the summary sounds confident) while quietly bundling unrelated work together. Those bundles are hard to review and even harder to unwind later.
One simple guardrail helps: limit an agent to three files per task. If the work truly needs more than that, ask the agent to name the files it expects to touch and explain why - before it starts. Then you can decide whether to split the task.
This isn't a measure of how capable the model is. It's a way to keep the change small enough that a person can actually understand and verify what happened. As AI coding tools become a routine part of day-to-day development, the bottleneck usually isn't "can we generate code fast?" It's "can we check the change responsibly, without turning review into a nightmare?"
This article breaks down what the three-file cap controls, how to use it, when to set it aside, and how to decide when to split a task. The goal isn't to slow an agent down - it's to prevent the speed gains from turning into extra review and maintenance later.
What a three-file limit actually controls
The number three isn't magic. The point is that it gives both the agent and the reviewer a clear boundary. Without one, a vague request like "implement this feature" can balloon into edits across handlers, shared utilities, tests, configuration, docs, and unrelated cleanup. Each edit may be defensible on its own; together, they can turn a straightforward change into something closer to a refactor.
The file cap is especially helpful for behavior changes - work that changes what users (or other systems) experience. In that case, the risk isn't just a typo in one file. It's that changes in multiple places start relying on each other, or that the agent makes assumptions based on earlier parts of the task instead of checking the code it's actually editing as it goes.
Three failure modes the cap helps expose
1. The agent's mental model can drift. As the file count grows, keeping things consistent gets harder. A helper might be renamed in one place but not another. An import can get left behind. A comment might describe behavior that no longer matches reality. None of this is "mystical forgetting" - it's normal engineering slippage. But a larger agent patch makes those slips harder to spot.
The real issue is that bigger tasks create more dependencies to track and more chances for assumptions to diverge from what's on disk. Smaller scope makes it easier to ask the agent to inspect the relevant files, make a coherent change, and verify it before moving on.
2. Review can turn into a rubber stamp. Big diffs demand more attention, and that's exactly why review sometimes becomes superficial. Reviewers may skim, see that tests pass, and approve without tracing how each part connects to the stated goal. That's not meaningful review - it's just clearing the queue.
A compact diff doesn't guarantee correctness. But it makes it more realistic for a reviewer to understand what changed, why it changed, and whether the tests cover what you intended to change. When review time is already tight, that's an operational win, not a cosmetic one.
3. Reverting gets more painful. If a broad change mixes a real fix with a questionable refactor, reverting the whole commit also throws away the good part. When you separate changes, you can keep, adjust, or roll back one coherent unit without dragging the rest along for the ride.
In practice, this is what "smaller blast radius" means. It doesn't eliminate defects - it reduces how much unrelated work gets tangled together when something goes wrong.
File count is a proxy, not a quality score
A three-file change can be messy, and a twenty-file patch can be fine - especially if it's mechanical and consistent. The cap shouldn't be treated like a code-quality metric, or a stand-in for tests. It's a prompt to pay attention to scope.
For behavior changes, a useful question is: does each file contribute to one identifiable outcome? If a task touches a route, a shared service, its tests, some configuration, and multiple UI components, the better question isn't "can the agent edit all of these?" It's "are these changes one intent, and can we review them together without losing the thread?"
How to enforce the rule in practice
This guardrail only works if it affects what happens before code is written. Telling an agent to "keep the change small" is too vague. You want an instruction that creates a clear boundary - and a clear action when the task doesn't fit.
A practical prompt looks like this:
Scope: no more than three files. Before editing, list the files you expect to change and why. If the task needs more than three, stop and propose how to split it into separate tasks. Do not begin implementation until the scope is clear.
The stop condition matters. If the agent just lists more files and keeps going, the cap becomes an optional suggestion instead of a real boundary. Pausing gives the developer a chance to recognize that one ticket may contain multiple independent jobs.
Review the proposed file list before implementation
Once the agent proposes its likely files, sanity-check the list against the task's intent. You don't need a full design review - just a few direct questions:
- Does every file support the same user-visible or system-level outcome?
- Is any file included for optional cleanup rather than necessity?
- Could the change be delivered as a smaller, independently testable step?
- Is the agent changing shared behavior that deserves its own review?
- Are the tests specifically covering the behavior being modified?
If the list points to two distinct outcomes, split the work. For example, "change the account recovery flow and reorganize notification delivery" might sound like one product ticket, but it's at least two intents. You can implement and verify the recovery change separately from the notification refactor.
If the file list is coherent but still exceeds three files, you can make an exception - but do it deliberately, not because the agent's proposed scope automatically becomes the default.
Keep each task independently verifiable
A good split isn't just "first three files" and "next three files." That approach can leave the repository in a weird in-between state where neither part is really testable on its own.
Instead, split along a boundary you can explain and verify. One task might change a service's behavior and its tests. A follow-up task might update a caller to use a new interface. Another might adjust a separate endpoint. If an intermediate change can't compile or pass tests, call that out and choose a sequence that keeps the branch understandable - or combine it with a clear, reasoned exception.
The practical target is: one intent, one reviewable diff, one clear verification step. File count helps enforce that target, but it doesn't replace the actual reasoning.
When the cap is the wrong tool
Rules are only useful if you understand why you're using them. The three-file limit is mainly intended for risky behavior changes in existing code. There are common cases where you shouldn't apply it mechanically.
Mechanical migrations
A symbol rename across forty files, a consistent schema update, or a dependency-version change might touch many files - but it's still one uniform transformation. Splitting it into arbitrary groups of three can make consistency harder to maintain and can create temporary states that are more error-prone than the migration as a whole.
For this kind of work, use a different control set:
- Confirm the change is genuinely mechanical and shouldn't alter behavior unexpectedly.
- Ask for a clear list or summary of affected files.
- Run formatter/type-checker/tests/migration validation across the full change.
- Review representative diffs and inspect the unusual exceptions.
- Keep the migration isolated from unrelated feature work.
The key distinction is not "many files are always bad." It's whether the change is uniform, bounded, and verifiable with checks that cover the whole transformation.
New-file scaffolding
Creating a new module, its tests, and the wiring to make it usable can naturally involve a small cluster of files. Sometimes that's still a coherent task even if it hits or slightly exceeds three files - because it's the minimum set needed to make the new thing real.
If scaffolding requires more files, ask why. Some projects need small configuration or registration updates; others are widening a simple module into a broader integration. In those cases, the number is a reason to inspect scope - not a command to break a naturally connected change into something you can't validate.
A simple exception test
Before you waive the cap, ask:
- Is the change uniform? Mechanical edits behave differently from multiple behavior decisions.
- Can it be checked across the full scope? Tests, formatters, type checks, or migration tools can give stronger coverage than reviewing every line in isolation.
- Will one review still explain the whole change? If the answer is no, split by intent - even if the operation is automated.
If the work is behavior-heavy, touches different subsystems, and can't be verified as one unit, the cap is probably doing its job. If it's a consistent migration with solid validation, a higher file count may be reasonable.
Why task boundaries matter beyond the diff
Yes, the immediate benefit is a smaller diff. But the bigger win is that it makes the task easier to reason about. Requests that end up needing six or ten files often contain multiple intentions hidden inside one sentence or ticket. Asking the agent to name the files up front surfaces that structure early, when it's cheap to adjust.
This matters for delivery. If a feature, cleanup, and integration change are bundled together, a delay or defect in one part can block all of them. Separate, independently verifiable tasks give a team more options: ship the safe part, defer the uncertain part, or roll back one change without discarding everything else.
It also matters for AI oversight. A model can produce a patch faster than a person can fully understand it. That creates an imbalance: generation scales with the tool, while review still takes human time and attention. More code generated doesn't automatically mean more capacity to validate it at the same pace.
Apply the same principle to API and specification work
The same logic applies when an agent updates API contracts or generated specs. Regenerating a full OpenAPI document in one pass can create a huge diff - especially when fields or endpoints change in ways that are hard to assess all at once. A narrower unit - say, one endpoint or one contract change, followed by a check against the running service - keeps the spec tied to observable behavior.
That said, not every endpoint change needs its own tiny unit. A shared contract change can legitimately affect multiple routes. The right choice depends on the boundary of the behavior and what validation you can actually run, not a rigid preference for "small patches."
The broader lesson is that context engineering isn't just about giving a model more information. It's also about limiting what you ask it to do at once. A well-scoped task reduces assumptions, makes verification more direct, and helps the reviewer do a clearer job.
The business cost of oversized changes
A broad patch carries costs beyond the minutes spent staring at a diff. It can increase regression risk, consume scarce review capacity, delay releases, and make ownership unclear when something fails. Those costs are easy to miss because code generation feels fast, and the output looks productive right away.
A smaller, coherent change may require more back-and-forth with the agent. That's not necessarily slower in the ways that matter. If each step is easier to test and roll back, the overall delivery process can become more predictable. The real metric isn't "how many tokens did we generate?" It's the cost of moving a verified change into production - and maintaining it afterward.
A practical adoption checklist
You don't need to redesign your whole AI workflow to try this. Apply it to your next behavior change, see how it affects review, and decide whether the boundary helps in your environment.
Before the agent edits code
- State the intended outcome in one or two sentences.
- Set a maximum of three files for behavior changes.
- Ask the agent to list the files it expects to touch and explain each one.
- Tell it to stop and propose a split if the scope exceeds the cap.
- Remove unrelated cleanup from the task unless it's required for the outcome.
While reviewing the result
- Compare the actual diff to the proposed file list.
- Check whether the agent added any unrequested behavior or extra refactoring.
- Verify tests cover the behavior being changed, not just that "tests passed."
- Read the diff as one connected change: confirm names, imports, comments, and callers stay consistent.
- If the approach is wrong, decide whether you can revert or revise a single coherent unit.
After a few tasks
Look at what happens in practice, not just whether the rule was "followed." Did it surface overloaded tickets? Were reviews easier? Did the agent repeatedly propose unnecessary files? Did the cap create awkward intermediate states? Use what you learn to tweak your prompt and identify which exceptions make sense for your codebase.
A useful operating rule is:
For behavior changes, default to three files or fewer. For larger scopes, require a file list, a reason to keep the work together, and a verification plan.
That keeps the benefit without pretending every code change has the same risk profile.
Conclusion
A three-file limit is a practical way to keep AI-assisted behavior changes reviewable. It forces the agent to state scope before coding, gives you a chance to separate mixed intents, and keeps each change small enough to verify and revert when needed.
Use it as a default, not dogma. Waive it when a larger change is genuinely uniform and can be validated across its full scope. Use it when the work changes existing behavior and a wide diff would make review less meaningful.
Try it on your next coding-agent task: "Three files maximum. List what you would touch before you start." If your honest answer is that you need more, decide whether it's one coherent change or several tasks that should be split - even within a single ticket. That choice is often more valuable than another round of prompt tuning.
The three-file approach was described in the original source article.