How to Split a Big Task for an AI Coding Agent

A task is the right size for an AI coding agent when you can name one observable check that proves it worked. Not "it looks right". A command you can run, a page you can load, a test that goes from red to green. If you cannot name that check, the task is too big, and no amount of prompt polish will save the run.

That single rule fixes most of the failures people blame on the model. Agents rarely fail because they cannot write the code. They fail because they were handed something with no edge, ran out of context halfway through, and started guessing about the second half.

The failure signatures of an oversized task

You can diagnose this from the output without reading the diff. Each of these has a specific cause, and the cause is almost always size.

The third row is the expensive one, because it looks like success. A green suite that tests nothing is worse than a red one. A green suite you did not specify is a false receipt.

The splitting rule, concretely

Take the task and try to write this sentence: "This is done when ___ passes."

If the blank takes one command, you have a task. If it takes a paragraph, you have two or more tasks. If you cannot fill it in at all, you have a research question that needs a person first.

Three worked examples of that sentence doing its job:

• "Add user profiles" becomes "This is done when..." and stalls immediately. Too big.

• "Add a profiles table with a migration" becomes "This is done when npm run migrate succeeds and \d profiles shows the four columns." That is a task.

• "Add the profile edit form" becomes "This is done when npm test -- profile-form passes and the form saves a changed display name that survives a page reload." Also a task.

Notice the second and third are not equal in size. They do not need to be. Equal-size chunks are a Gantt chart habit that does not apply here. What matters is that each one ends in a check.

How to split, in order

1. Split by verification boundary first. Anywhere the proof changes shape, that is a seam. A migration is proven by running it. An API endpoint is proven by a request. A UI is proven by an interaction. Three different proofs means three tasks, even if it feels like one feature.

2. Then split by blast radius. Two tasks that touch the same file will fight if you run them concurrently. Keep them sequential or keep them apart. This is the same constraint behind merge conflicts with coding agents.

3. Then split by decision. If a task contains a choice you have not made, split the choice out and make it yourself. An agent asked to pick between two architectures will pick one and then defend it for the rest of the run.

4. Stop splitting when the setup cost dominates. A task that takes you four minutes to describe and the agent ninety seconds to do is too small. You are the bottleneck at that point.

Rule three is where most of the value is. making the agent show its plan first exists because agents make silent architectural decisions inside tasks that were not supposed to contain any.

A full worked split

Say the ticket is "let customers export their data". Here is that turned into agent-sized work, with the check for each.

1. Add the export_jobs table and migration. Done when the migration runs clean and the table has id, user_id, status, requested_at, file_url.

2. Add a background job that writes a CSV for one user id to storage and updates the row. Done when invoking the job for a seeded user leaves a downloadable file and status = 'complete'.

3. Add the POST /exports endpoint that enqueues a job for the authenticated user. Done when an authenticated request returns 202 and creates exactly one row, and an unauthenticated one returns 401.

4. Add the account page button and status display. Done when clicking it shows a pending state, and a completed export shows a download link.

5. Add rate limiting: one export per user per hour. Done when a second request inside the hour returns 429.

Five tasks, five checks, five reviewable diffs. The same work handed over as one ticket produces one enormous diff where step five is silently missing and step two writes the CSV in memory for a table with two million rows.

Note that step five is separate on purpose. Bundled into step three it becomes an implementation detail the agent may or may not honour. Given its own check, it either exists or it does not.

Writing the task so it holds

Each split task still needs three things in the prompt, and they take one line each:

• The check. State it as a command. npm test -- exports beats "make sure it works".

• The boundary. Name the files or directories in scope. Agents respect a stated boundary far more reliably than an implied one, which is most of what stopping an agent changing code you didn't ask about comes down to.

• The prior state. What already exists that this builds on. Without it, the agent re-derives your schema from scratch and gets it subtly different.

If your rules file already carries your conventions, you do not repeat them per task. That is the point of having one, and it keeps each task prompt short enough that you actually write it.

When the agent still stalls

Sometimes a correctly sized task still goes sideways. Two checks before you blame the split:

Did it have the context it needed? An agent that cannot see the existing schema will invent one. Keeping an agent from losing context covers the mechanics, and long tasks lose context in the middle first.

Is it looping? Repeating the same two edits means the task contains an unresolved contradiction, usually a check that cannot pass given a constraint elsewhere. An agent stuck in a loop is a signal to reread the task, not to rerun it.

For the wider picture of what agents handle well and where the ceilings sit, the coding tools overview has the wider comparison.

FAQ

How big should a task for an AI coding agent be? Small enough that one command proves it worked, and large enough that describing it takes less time than doing it yourself. In practice that is usually a single migration, a single endpoint, or a single component.

Should I split by file or by feature? Neither. Split by verification boundary, then check that the pieces do not fight over the same files. Files are a side constraint, not the organising principle.

Why does my agent stub things with TODO? Almost always because the task exceeded what it could finish in the space available, so it produced the shape of the answer instead of the answer. Halve the task and rerun.

Can I just give the agent the whole ticket and let it split the work? You can, and it will produce a plan. Read that plan and check each step ends in something observable, because agents split by narrative structure more often than by verifiability.

Does this change with a bigger context window? Less than you would hope. A bigger window reduces the running-out-of-room failures, but the review problem gets worse: one enormous correct diff is still harder to check than five small ones.