Planning a task the agent can actually finish

Why agents mostly fail on ambiguity, not ability

You’ve probably seen this pattern: you ask the agent to “add rate limiting to the API,” it edits five files, breaks two tests, and leaves you with a half-finished refactor.

The problem usually isn’t that the agent can’t write the code. It’s that the task is underspecified: scope is fuzzy, constraints are implicit, and “done” isn’t defined beyond your head.

Modern coding agents are very good at following a crisp plan and surprisingly bad at guessing your intent from a one-sentence wish. When they guess wrong, they still sound confident, so you only notice the problems when you try to run or review the change.

If you tighten the plan, the same agent can often produce a small, correct PR on the first try. This article is about how to write that plan in a repeatable way.

Spot your starting level

Before changing your workflow, locate how you already use agents. Different starting points need different adjustments.

Scan these patterns and pick the one that feels closest:

Level 1: ChatGPT-style helper

You mostly paste snippets into chat, ask “what’s wrong?”, and copy back fixes by hand. You rarely let the agent touch the repo directly.

Level 2: Local editor assistant

You use inline completions or simple edits ("extract this function", "rewrite for readability") but big changes still feel risky. Outputs are often partial or off in style.

Level 3: Repo-aware agent

You run agents that read the project, propose patches, or open PRs. Sometimes they nail it, sometimes they wander or leave things half done.

This guide assumes you’re at Level 2 or 3. If you’re at Level 1, you can still apply the same task spec, but you’ll paste the plan and diffs manually instead of pressing an “agent mode” button.

The four-part agent task spec

A task the agent can finish has four parts:

1. 1
   Scope: What changes, in one clear sentence.
2. 2
   Constraints: How it must be done or what it must respect.
3. 3
   Verification: How we’ll decide it’s done.
4. 4
   Size: The intended complexity / time box.

Think of this as a micro design doc you write in 2-3 minutes before invoking the agent.

Here’s a minimal template you can adapt:

Goal / scope: <one-sentence outcome the code should achieve>

Context: <1-3 sentences or a quick bullet list of relevant files, data flows, or existing behavior>

Constraints:
- <any required APIs, patterns, performance or security constraints>
- <any files or areas that must not change>

Verification:
- Automated: <specific tests or test commands that should pass>
- Manual: <explicit steps with inputs + expected outputs>

Size / limits:
- Target: roughly <N> lines / <under 30 minutes> of human work
- If this is too large, stop and propose how to split it.

We’ll use this template in a moment on a concrete example. First, you need a feel for what “under 30 minutes” looks like in practice.

Right-sizing: what “under 30 minutes” really means

"Let the agent implement user profiles" is not a single task. A human can’t do that in 30 focused minutes, and neither can an agent.

You want tasks that are closer to:

• “Add server-side validation that username is 3-20 chars, alphanumeric plus underscore, and show a friendly error on the profile form.”

For most back-end or full-stack work, under 30 minutes of human effort usually means:

If you struggle to describe the change crisply, the task is too big. Split by:

Agents chain well across multiple small tasks; they thrash on one giant, muddy one.

First attempt: rewrite a vague task into a finishable spec

Time to practice on something real.

Pick a tiny change you actually need in your current project. If you don’t have one, use this stock example:

Improve the error message when a user enters an invalid email into the signup form, and prevent submitting if the email is invalid.

This is how many people feed it to an agent:

Improve the signup email validation and error message.

That’s vague. Let’s reshape it into the four-part spec.

Worked spec

Goal / scope: Strengthen signup email validation so invalid emails can’t be submitted, and show a clear inline error message near the email field.

Context: Next.js app. Signup form at `app/signup/page.tsx` posts to `/api/signup`. Client-side validation currently uses a simple regex in `lib/validation.ts` but lets some invalid emails through. Error messages appear under the field using the existing `<FormError>` component.

Constraints:
- Reuse the existing `<FormError>` pattern for UI; don’t introduce a new error component.
- Keep the validation logic in `lib/validation.ts`; don’t inline regexes into React components.
- Don’t change the API contract of `/api/signup`.

Verification:
- Automated: Extend or add tests in `__tests__/validation.test.ts` to cover invalid emails like `"a@", "@example.com", "a@b", "user@@example.com"`.
- Manual: In the browser, go to `/signup`, enter `"user@@example.com"`, click submit, and confirm: (1) the request is blocked client-side, (2) the email field is outlined in red as in other error states, and (3) the error text reads “Enter a valid email address.”

Size / limits:
- This should require changes in at most 3 files and be doable in under 30 minutes of careful human work.
- If additional refactors seem necessary, stop and propose a follow-up task instead of doing them now.

Copy this pattern, but swap in your own project-specific paths, components, and checks. Then pass that spec to your agent (Claude Code, Cursor agent mode, etc.) and let it run once without further hand-holding.

Reading the results: good vs poor feedback signals

Once the agent finishes, your job is not to fix everything by hand. Your job is to read the feedback and decide what to change in your next task spec.

Here’s what to look for:

You can also use runtime behavior as feedback: if your manual check passes exactly as described, your spec guided the agent well.

When an agent “fails,” resist the urge to blame the model or rewrite all the code yourself. Treat the output as a structured critique of your task spec. If the diff is scattered, your scope was fuzzy. If tests are missing, your verification was weak. The model is a mirror for your planning, not just an autocomplete with delusions of grandeur.

Retry: tightening scope, constraints, and verification

Let’s say your first attempt produced a partial or messy change. Instead of escalating to a giant corrective prompt, rewrite the task using what you just learned.

Using our signup example, imagine the agent:

Your second-iteration spec might sharpen things like this:

Follow-up task: Complete email validation work by localizing changes and adding tests.

Goal / scope: Ensure all email validation logic lives in `lib/validation.ts` and that invalid emails are fully covered by tests.

Adjustments from previous attempt:
- Move any validation changes out of `components/Input.tsx` back into `lib/validation.ts`.
- Do not modify `components/Input.tsx` at all in this task.

Constraints:
- Use the existing test file `__tests__/validation.test.ts`; do not create new test suites.
- For each invalid email case (`"a@", "@example.com", "a@b", "user@@example.com"`), add or update a test asserting `validateEmail` returns a failure with the message “Enter a valid email address.”

Verification:
- All tests in `__tests__/validation.test.ts` pass via `npm test validation`.
- Grep for `validateEmail` shows no remaining ad-hoc regex checks in components.

Instead of saying “fix what you just did,” you’re editing the plan in light of concrete feedback. Over a few iterations, you’ll start to see patterns in where your specs are weak and tighten them preemptively.

When to plan yourself vs let the agent plan

Agents can also plan their own steps: “Summarize the changes required and execute them.” Sometimes that’s fine; sometimes it’s exactly what causes thrash.

Use this rule of thumb:

• You plan when the task involves design, tradeoffs, or non-obvious constraints (performance-sensitive code, security invariants, tricky UX flows).
• Agent plans when the task is constrained and mechanical (convert tests from Mocha to Jest, migrate one endpoint to a new DTO, apply the same validation rule across a set of forms).

If you let the agent plan, bound it:

First, propose a short 3-5 step plan for this task. I’ll confirm it before you execute. Each step should be doable in under 30 minutes and limited to specific files. Do not introduce new libraries or major abstractions without asking.

Evaluate the proposed plan like you would a junior teammate’s. If it’s off, correct it in plain language and have the agent replan before writing code.

Reviewing and merging agent-written code

Even with good task specs, you remain the editor. Treat the agent like a fast but naive collaborator.

During review, focus on three things:

1. Diffs, not prose.

Read the actual changes, not just the agent’s summary. Look for broken invariants, performance regressions, or security footguns the model can’t fully appreciate.

2. Verification actually implemented.

Check that every verification step you listed is reflected in code:

If any step is missing, send a follow-up task instead of silently patching everything yourself. That keeps the planning loop honest.

3. Red flags that demand a re-plan.

If you see new abstractions, extra dependencies, or cross-cutting refactors you didn’t ask for, stop. Your next task should clarify constraints and explicitly ban that scope, not reward the agent by cleaning it up manually.

Over time, your “unit of work” shifts from “I’ll go fix this” to “I’ll design a finishable task, let the agent attempt it, and then I’ll review and adjust the plan.” That’s the leverage point you control.