paqad

Try Paqad

How should I split a large feature into tasks an AI coding agent can finish reliably?

  • Written by Haider Lasani
  • Published
  • 10 min read
Ivo kneels in socks on a rug laid out with rows of index cards, holding one card above the rows as he decides where it goes, a closed laptop at one edge of the rug and his trainers beside it.

TL;DR

Large features often get through specification and planning, then go wrong halfway through implementation as the agent's context fills and the plan slips out of view. Split the feature by behaviour someone can check rather than by layer, agree shared contracts first, size each task to one session with one passing check, and give every seam between tasks its own integration check. Then let what each finished task shows decide whether the next one starts or the plan is revised.

Fine through planning, lost in the middle of the build

Planning a feature with an agent and building it are different kinds of work. Planning is a short run with the whole plan in view. Building a large feature is a long run, and somewhere in the middle the plan stops being in view while the agent keeps going.

That is the pattern a team using GitHub's Spec Kit described in the project's discussions in June 2026 (discussion 2914). Specification, planning and task lists went smoothly, they wrote, but in the middle of implementation the models started to lose track and ignore the plan and tasks, usually around the time context compaction was triggered. They asked whether to write a spec of specs, breaking the feature into smaller sub-specs first, or to have each implementation run take on only a segment of the tasks. Two months earlier a Cursor user asked on the Cursor forum a version of the same thing for a large project: build a full backend in one conversation with several subagents, or split the project into smaller modules and handle each separately?

Both are asking where to cut a large piece of work so that each piece finishes and the pieces still add up to the feature.

What the tool makers say about long runs

The vendors give a consistent reason for cutting at all. Claude Code's best practices say that performance degrades as the context window fills, and that the agent may start forgetting earlier instructions (Claude Code best practices). Spec Kit's own page on complex features names context window exhaustion as the cause of the pattern in that discussion and recommends scoping each implementation run to a limited set of tasks or a phase, then splitting into separately specified sub-features when even one phase is too much (Spec Kit complex features). The team that asked later reported that the spec-of-specs approach worked for several larger features, with a roadmap that each sub-spec referred back to.

Anthropic's engineers saw the same tendency in a long-running harness: the agent tried to build the whole app at once, and working on one feature at a time "turned out to be critical" (Effective harnesses for long-running agents, November 2025). That is an engineering report on one setup, not a controlled study. The rest of this article is how to choose the cuts.

Find the behaviours someone can check

Start from what the finished feature lets someone do, and list those behaviours, not the layers or files. A task called "build the API" is hard to call done, because it does not say what the API must do. A task called "an admin can create an invitation" carries its own check, even if it touches three modules. Spec Kit's task template takes the same view: it groups tasks by user story so that each story can be implemented and tested independently. Vertical slices are a useful default, not the only shape that can be verified alone: an API task that names its endpoints and responses can be checked with contract or integration tests before any screen exists.

Then mark what the behaviours share. Shared contracts, such as a schema, an API shape or a permission rule, are the dependencies, and they go first, because every later task is built against them.

Size each task to one session and one passing check

A task is small enough when one session can finish it without compaction and one check can say it is done. It is too small when finishing it proves nothing a person would care about, such as a model with no caller. Codex's best practices suggest that a prompt include a "Done when" line, and OpenAI's execution-plan guide requires each milestone to be "independently verifiable" (Codex best practices, execution plans). Write each task as a short card the agent can read in a fresh session:

  • Behaviour. One sentence a person could watch happen.
  • Depends on. The contracts and earlier tasks it builds on, by name.
  • Expected files and modules. So a diff outside them stands out.
  • Done when. The test or command that must pass, and what it shows.
  • Out of scope. What the next task will do, so this one does not start it.

If you cannot write the "done when" line, the task is too vague, or cut along a layer with no contract to test against. Cut it again. Treat one session and one check as a sizing heuristic, not a guarantee: a task that fits can still drift, which is why the seams and the evidence after each task matter.

Illustration of Ivo at a wooden library table with his laptop open, pressing one index card flat beside it, while Mira across the table slides the next card toward him past a small stack of cards, a brass desk lamp and two books.
A task is small enough when one check can say it is done.

Give every seam its own check

Locally correct tasks can still fail to form the feature. Each passes its own test against its own idea of the contract, and the mismatch only shows when they meet. Treat the seams as work of their own:

  1. Put a contract test on every shared interface in the first task, so later tasks are checked against the same definition.
  2. After each task that crosses a module boundary, run the previous tasks' checks as well as its own.
  3. Schedule an explicit integration task wherever two behaviours meet, with a check that exercises the path end to end on a running system.
  4. Finish with one end-to-end check of the whole feature, written before the first task starts.

Spec Kit's template marks the same points as checkpoints, for example that two stories "should both work independently" before a third starts. Anthropic's harness report adds the failure to watch for: the agent made changes without noticing that the feature did not work end to end, and did much better once explicitly prompted to test it with browser automation.

Illustration of Ivo in a train seat frowning at two index cards he holds side by side, while Noor across the table, her laptop open in front of her and a coffee cup at her elbow, looks over at him.
Two tasks can each pass and still not fit together.

Let each finished task decide what happens next

The plan is a forecast. Each finished task is evidence about it, and that evidence should decide the next step rather than the task list's order:

Decision guide

  • If the task's check passes, the diff stayed within its expected files and no contract changed, start the next task.
  • If the task needed a file or module the card did not list, update the cards that depend on that area before continuing.
  • If a contract changed, re-check every task built on it and revise the plan before starting new work.
  • If the agent has needed more than two corrections on the same problem, stop. Claude Code's guidance is to clear the session and restart with a better prompt; for a plan, that usually means a smaller or differently cut task.
  • If a seam check fails, fix the contract or the plan, not just the later task.

Keep the progress and the decisions in a file in the repository, so a fresh session for the next task starts from what is true now. OpenAI's execution-plan guide asks for exactly that: a progress list that reflects the current state and a decision log. The article on what to save for a new AI coding session covers what that file needs. The article on keeping an agent in planning until the plan is approved covers when a revised plan needs a new approval.

Paqad does not split a feature into tasks for you. It holds each change it is given to a recorded plan. On Claude Code and Codex CLI, paqad-ai plan compile builds a plan.json whose ordered steps can each name the module and files they expect to touch, with a required reuse declaration. On graduated and full lanes, a change touching more than one module runs a cross-module impact scan, and a breaking or shifting public surface becomes a decision for you; after the specification is frozen, a change of goal raises a decision pause instead of being absorbed. Its feature-development workflow also instructs the agent to stop after a lane-scaled number of build, test and fix rounds and reassess; that is an instruction, not a mechanically enforced cap. None of this proves the split is right, or that nothing outside the plan changed. Paqad's plan file format page shows the fields each plan step can carry.

Frequently Asked Questions

Write the end-to-end check for the whole feature before splitting it. Every task then has to move that check closer to passing, which exposes tasks that only build layers and makes the final integration a known target rather than a surprise.

Look at what changes for each kind of user, and at each point where data crosses a module boundary. Asking the agent to list both in plan mode is a useful first pass, but confirm the dependencies yourself: a missed shared contract is the most expensive error in the plan.

Small enough to review in one sitting and finish in one session, and no smaller than the first change that a test can exercise from outside. If two tasks always have to be reviewed together, merge them.

Contract tests on shared interfaces, re-running earlier checks after each boundary-crossing task, and integration tasks at each seam. Run tasks in parallel only when they touch different files and have no dependencies on each other, which is how Spec Kit's template defines a parallel task.

The task's own check, the diff against its expected files, the seam checks and the number of correction laps it took. A task that passed only after the plan was quietly worked around is a reason to revise, even when everything is green.