The agentic coding workflow: plan, execute, verify

Autocomplete and pasting errors into a chat window are useful, but they aren’t delegation. Coding agents change the unit of work: you hand over a task, and the agent reads files, edits code, runs commands and reports back.

When it works, it’s like pairing with a tireless junior. When it doesn’t, you’re cleaning up after someone who confidently rewrote half your codebase. The difference is rarely the model. It’s the workflow around it.

1. 🧭PlanSize the task, write the brief, review the agent's plan
2. ↓→
3. ⚙️ExecuteAgent works inside tests, types and lint
4. ↓→
5. 🔍VerifyYou check the diff: files, tests, then code

↺ Commit at green, discard freely, repeat with the next small task

The mental shift: from typing to delegating

With autocomplete, you’re the author. With an agent, you’re closer to a tech lead: you define the work, set the boundaries and review the result.

🃏 The three skills that now matter most

Tap a card to flip it

DecompositionBreaking work into pieces an agent can finish and you can verify.SpecificationSaying what "done" means before anyone writes code.ReviewReading a diff quickly and spotting what's wrong.

Step 0: size the task

Task size is the biggest predictor of success I see. Too small and the brief isn’t worth writing; just type the code. Too big and the agent loses the thread and hands you a 40-file diff you can’t review.

✅ A task is well-sized when…

0 / 4 completed

• You can describe the goal in two or three sentences.
• You can state how you'll know it's done (a test passes, an endpoint returns X, a page renders Y).
• The diff will be reviewable in one sitting, roughly a normal pull request on your team.
• It touches one area of the codebase, or a small, known set of areas.

↺ Reset

🎮 Delegate it or keep it?

1 / 9 · Score: 0

Would you hand this to an agent as a single task?

Good agent taskKeep it / split it first

Next →

/ 9

↺ Try again

If a task is too big, don’t hand it over as-is. Ask the agent to help you split it, then delegate the pieces one at a time.

Step 1: write a real task brief

One-line prompts work for trivial changes. For anything else, a short brief takes two minutes and saves twenty.

1. 1

   Goal

   What should be true when the task is done, and why.

2. 2

   Constraints

   What the agent must not do or must respect: no new dependencies, don't change the public API, follow the pattern in file X.

3. 3

   Acceptance criteria

   Concrete, checkable conditions. Ideally commands that pass.

4. 4

   Relevant files

   Where to start looking, so the agent doesn't wander.

A brief for a small feature:

## Goal
Add cursor-based pagination to GET /api/orders. The mobile app
currently loads all orders at once and times out for large accounts.

## Constraints
- Keep the existing response shape; add `nextCursor` at the top level.
- Don't add new dependencies.
- Follow the pagination pattern already used in `src/api/invoices.ts`.
- Don't modify the database schema.

## Acceptance criteria
- `limit` query param, default 50, max 200.
- `cursor` query param returns the next page, ordered by createdAt desc.
- New tests in `tests/api/orders.test.ts` cover: first page, next page,
  last page (nextCursor null), invalid cursor (400).
- `npm test` and `npm run typecheck` pass.

## Relevant files
- src/api/orders.ts
- src/api/invoices.ts (reference pattern)
- src/db/queries/orders.ts

Note the reason (so the agent makes sensible trade-offs), the reference pattern (so it doesn’t invent one) and a definition of done a machine can check.

A brief for a bug fix:

## Goal
Fix: users with an apostrophe in their last name (e.g. O'Brien) get a
500 when updating their profile.

## Reproduction
1. Create a user with last name "O'Brien".
2. PATCH /api/profile with any change.
3. Server logs show a query error in updateProfile.

## Constraints
- Fix the root cause, not the symptom. No string escaping hacks.
- Don't touch unrelated queries, even if they look similar. List them
  in your summary instead and I'll decide.

## Acceptance criteria
- Write a failing test that reproduces the bug FIRST, show me it fails.
- Then fix it and show the test passing.
- Full test suite passes.

## Relevant files
- src/services/profile.ts
- src/db/queries/users.ts

🧠 Brief check

Score: 0 / 4

1. 1. Which acceptance criterion is most useful to an agent?

   Make it work wellnpm test and npm run typecheck pass, with new tests for the invalid-cursor caseFollow best practices

   A machine-checkable condition lets the agent verify its own work.

2. 2. Why include a reference file like src/api/invoices.ts?

   To give the agent more to readSo it follows an existing pattern instead of inventing a new oneIt's required by most agents

   Pointing at the pattern prevents invented structure.

3. 3. Why state the reason behind the goal ("the mobile app times out")?

   PolitenessIt helps the agent make sensible trade-offsIt makes the brief longer

4. 4. In a bug-fix brief, what should come before the fix?

   A refactor of nearby codeA failing test that reproduces the bugUpdating dependencies

   The failing test proves the bug and becomes the spec for the fix.

↺ Try again

Step 2: give the agent repo context once

You shouldn’t repeat “we use pnpm, not npm” in every brief. Most agents load a project-level instructions file at the repo root, often named something like AGENTS.md or CLAUDE.md. Check your tool’s docs for the exact filename.

Treat this file like code: review changes, keep it current, delete dead lines. If the agent keeps making the same mistake, add one line here rather than repeating yourself in every prompt.

Step 3: plan first, then review the plan

For anything beyond trivial, ask for a plan before edits. Many agents have a plan or read-only mode; otherwise say “Don’t edit any files yet. Read the relevant code and propose a plan.”

A useful plan lists the files that will change and why, the approach in a few steps, assumptions, and how it will verify the change. Reading it is the cheapest review you’ll ever do: catching “I’ll add a new caching library” here costs one sentence, not a rewrite.

🃏 Red flags in a plan

Tap a card to flip it

Scope creepFiles that shouldn't be touched for this task.Invented structureNew abstractions, helpers or layers when an existing one would do.Wrong assumptions"I'll assume the user ID is a number" when it's a UUID.Missing verificationNo mention of tests, or tests that only check the happy path.

Correct the plan in plain language; two rounds is normal. On round four, the task is too vague or too large, so rewrite the brief. Planning also splits big work: “Propose a sequence of small, independently mergeable steps to get from here to X.”

Step 4: execute inside a tight feedback loop

An agent without a verifier is guessing. With a fast test suite, a typechecker and a linter, it can see its own errors and fix them before you look.

✅ Feedback loop setup

0 / 4 completed

• Test, typecheck and lint commands are in the instructions file and work from a clean checkout.
• They're fast, or you've documented how to run a single file or subset.
• The brief tells the agent to run them before reporting done.
• Output is readable: noisy warnings don't bury the real error.

↺ Reset

TDD pairs surprisingly well with agents

1. RedAgent writes a failing test for the behaviour
2. ↓→
3. ReviewYou review the test: it is the spec
4. ↓→
5. GreenAgent makes it pass without changing the test
6. ↓→
7. RefactorAgent cleans up with tests green

One rule I’m strict about: the agent doesn’t get to edit a test to make it pass unless I’ve agreed the test was wrong. Say it in the brief.

Step 5: small commits, and git as the undo button

Agents make many changes quickly. Git is what makes that safe.

The code was cheap to generate; your attention isn’t. Being willing to throw work away is a real skill.

Step 6: run agents in parallel, carefully

Two or three agents on independent tasks is a genuine productivity jump. The key is isolation: two agents in the same working directory will step on each other.

Isolation options: separate git worktrees (each agent gets its own directory and branch on the same repo; my default), separate clones if your tooling dislikes worktrees, or remote/sandboxed agents if your tool offers them.

Step 7: review agent diffs efficiently

Agent output needs review, full stop. The trick is doing it faster than writing the code yourself.

1. 1

   Read the summary, trust nothing yet

   "All tests pass" is a claim, not a fact.

2. 2

   Run the checks

   Tests, typecheck, lint, yourself or via CI.

3. 3

   Scan the file list

   Any file not obviously related to the task is a red flag. Start there.

4. 4

   Read tests before implementation

   Do they assert something meaningful? Would they fail if the feature broke?

5. 5

   Read the implementation

   Hunt for the failure modes below, not style. Formatters handle style.

6. 6

   Check what's missing

   Error handling, edge cases from the acceptance criteria, docs or types to update.

A diff too big to review comfortably is feedback on task size, not a reason to skim. Reject it and split the task.

Common failure modes and how to catch them

The patterns I see most, in my own work and with teams I help. Flip each card for how to catch and prevent it.

🃏 Agent failure modes

Tap a card to flip it

Context driftLate in long sessions, earlier constraints get ignored. Catch: violated rules late on. Prevent: one task per session; durable rules in the instructions file.Overreaching editsYou asked for a fix and got a "cleanup" across 12 files. Catch: the file list. Prevent: "only change what's needed; list other improvements instead."Fake-passing testsWeakened asserts, skips, mocking the thing under test, special-casing test inputs. Prevent: forbid test edits without approval; review tests first.Hallucinated APIsPlausible methods or options that don't exist. Catch: types and tests. Prevent: point the agent at the installed version's source or docs.Confident wrong summaries"Done, all tests pass" when it never ran them. Catch: verify independently. Prevent: require the exact commands run and their output.LoopingFix, fail, variation, fail again. Catch: the same error three times. That's your cue to take the wheel.

When to take the wheel back

Delegating doesn’t mean abdicating.

✅ Step in when…

0 / 5 completed

• The agent has failed the same way three times. It's missing information or the approach is wrong.
• The problem needs judgment the agent doesn't have: product decisions, business trade-offs, security or money.
• You don't understand the code it wrote. If you can't explain the diff, don't merge it.
• It would be faster to just type it.
• The domain is unfamiliar to you. Use the agent to explain and explore; write or closely supervise the code yourself.

↺ Reset

Taking the wheel can be partial: fix the tricky part yourself, commit it, and hand the rest back.

## Goal
I've implemented the new retry logic in src/jobs/retry.ts (see the last
commit). Apply the same pattern to the three other job handlers.

## Constraints
- Match the retry.ts implementation exactly; don't "improve" it.
- One commit per handler.
- If a handler doesn't fit the pattern cleanly, stop and tell me
  instead of adapting it.

## Acceptance criteria
- src/jobs/email.ts, src/jobs/export.ts, src/jobs/sync.ts use withRetry.
- Existing tests for each handler still pass.
- New test per handler for the retry-then-succeed case.

## Relevant files
- src/jobs/retry.ts (reference)
- tests/jobs/retry.test.ts (reference test)

Putting it together

1. 1

   Size

   So the diff will be reviewable.

2. 2

   Brief

   Goal, constraints, acceptance criteria, relevant files.

3. 3

   Plan

   And review the plan before any code.

4. 4

   Execute

   With tests, types and lint as the verifier.

5. 5

   Commit

   At green checkpoints; discard freely.

6. 6

   Review

   File list, tests, then implementation.

7. 7

   Take the wheel

   When the agent loops, or judgment is needed.

None of this is exotic. It’s how good teams already delegate to people; agents just make skipped steps show up faster.

Try this on your next task

✅ Your first plan-execute-verify run

0 / 9 completed

• Pick one task that would make a normal-sized pull request.
• Make sure your repo has an instructions file with the exact test, typecheck and lint commands.
• Write a brief with goal, constraints, acceptance criteria and relevant files.
• Ask for a plan first. Read it and correct at least one thing before approving.
• Require the agent to run the checks and paste the commands it ran.
• Start from a clean working tree on a fresh branch.
• Review the file list first, then tests, then implementation.
• If it fails the same way three times, stop and rewrite the brief.
• Afterwards, add one line to your instructions file based on what went wrong.

↺ Reset