Skip to main content
Comic illustration: a yellow robot stands at A facing a long brick wall while blue helper robots set up to drill through it, and a person crouched beside it points along a dashed route around the end of the wall to B

Systems & SDK Engineering9 min read

You Asked AI to Do Something. Did You Think About How?

Contents

Give a capable coding agent a large job, like normalizing custom React components onto shadcn and Base UI, and it can build an elaborate workflow instead of finishing the work. The antipatterns we see in the field, and what we now tell agents before they start.

The job was simple to state. One robot, one trip: get from A to B as quickly as possible. A brick wall stood in the way, and its end was a few steps off. Asked to plan the trip, the AI measured the wall, decided that straight through was shortest, and gave every step its own helper. One measured, one drew plans, one drilled and one checked. Each reported its part done. The robot was still standing at A.

That comic describes something we have watched happen while directing AI coding agents on real engineering work. An AI coding agent is a model that edits code and runs commands on its own. The clearest case we have observed was a controlled migration in which an agent led the normalization of a library of custom React components onto shadcn and Base UI, the open-source component foundations many React teams now build on. Given a job like that, an agent can produce an impressive volume of activity: plans, inventories, assignments, progress reports. What it produces less reliably is finished work, meaning software that is built, installed, checked and ready for someone to use. When we paused that migration, every component had its code recorded as written. Roughly one in eight had passed every check that applied to it, and none had been delivered. This article collects the antipatterns we have seen in the field, why we think they happen, and the practices we now give agents before they start.

Panel 1: the yellow robot at A eyes a tape-sized hole in a brick wall while the blue robot, who has already walked around the wall's end to B, says straight through is shortest.
Panel 2: the blue robot summons four helpers labeled Measure, Plan, Drill and Check, saying it will give every step its own helper, while the yellow robot waits.
Panel 3: a busy miniature construction site; one helper says its part is done while the yellow robot, still at A, asks which one gets it to B.
Figure 1The AI chooses the approach. Every step gets a helper, every helper finishes its step, and nobody has crossed the wall.

Components, when we paused the migration

Code written
100%
Recorded as written, not yet proven to build or install
Fully verified
1 in 8
Every applicable check passed
Delivered
0%
None had reached an application
Tracker records
~7×
Per component; about a third of logged events were checkpoints

A concrete job, reasonable instructions

The goals of that migration were concrete. Rebuild each custom component on shadcn and Base UI primitives, the basic building blocks those libraries provide, and keep the upstream source untouched so future upgrades stay simple. Normalize the design tokens, the shared names for colors, spacing and type, so every theme maps onto one vocabulary. Package the components so an application can import each one on its own.

The instructions were reasonable too. Be thorough. Get an independent review. Keep the tracker current. Use more agents so the work goes faster. We had also said how to work: use the current code, prefer the standard behavior of the libraries involved before adding fixes of our own, skip review ceremony, and stop only for genuine decisions.

Instructions like those give an agent enough to choose a practical route. It does not always choose it. Each instruction is followed, and followed hard, until the combination produces a process far heavier than the job needs.

Four antipatterns from the field

1. Splitting the job by phase

AvoidA long winding line of blue robots in different hats passes a single brick hand to hand while the yellow robot watches, puzzled.
InsteadOne blue robot in a hard hat carries a small finished control panel along a footprint path around the wall to the B sign, holding a ticked clipboard, while the person gives a thumbs-up.
Figure 2Every handoff completes and the brick barely moves. One owner carries the job all the way to B.

Splitting a large job is sensible. The trouble starts when the pieces are phases instead of outcomes. Writing one component's code, packaging it, installing it in a test application and checking it each go to a different worker, an extra agent session that the lead agent, the coordinator, hands tasks to. Every worker finishes its phase. Nobody owns getting the component all the way to done.

2. Patching failures with process

AvoidThe yellow robot sits dazed beside a single pebble while blue robots surround the pebble with boom gates, cones, fences, warning signs and a tiny inspection booth, turning the path to B into a maze.
InsteadThe person flicks the pebble off the path, the yellow robot walks a clear path toward B, and a blue robot carries away the last traffic cone.
Figure 3Every stumble earns a new gate. Removing the pebble keeps the path clear.

Problems surface late, and the response makes things worse. A test fails because its setup assumed something the real code does not have, and the failure is treated as a product defect. Each failure adds a guard, a classification or another handoff. Often the better fix is to remove the cause, or the boundary that should not have existed.

3. Tracking activity instead of outcomes

AvoidBlue robots stamp clipboards and climb ladders to add check marks to a giant scoreboard of charts and lights, while the sealed crate of finished work sits untouched at A with a cobweb on it.
InsteadThe person points at a small board with three columns, marked by a check mark, a stop hand and a robot face, while the crate has arrived at B and a blue robot gives a thumbs-up.
Figure 4A busy scoreboard while the crate sits at A. Three columns answer what matters: done, blocked, and who owns it.

The tracking grows with the process. When we paused the migration, its tracker held about seven records for every component, and about a third of the logged events were checkpoints, status markers saved along the way. It still could not answer the three questions that matter. Which pieces are finished, which are blocked, and who is finishing each one?

4. The stranded handoff

AvoidThe yellow robot sits on a sealed shipping crate in the sun, chin in hand, under a clock showing hours have passed, while a blue robot sleeps on its clipboard.
InsteadA blue robot in a hard hat wheels the crate on a hand truck toward B while the yellow robot walks alongside, and the clock shows only a minute has passed.
Figure 5Ready to install, and only the coordinator may move it. Taking the step before stopping keeps the work moving.

The most expensive failures are quiet. A package of rebuilt components was ready to install early one morning, with a worker standing by to check it. Only the coordinator was allowed to install packages, and its turn had ended. A turn is one run of an agent; when it ends, the agent waits until a person says continue. The package sat for most of the morning. The install, once it ran, took well under a tenth of a percent of that wait, and the check found a real problem within minutes.

A clever plan can make a simple job complicated.

None of these antipatterns looks unreasonable on its own, which is why they are easy to miss.

Table 1

Antipatterns at a glance

Situations that recur when an agent coordinates a large job, what agents tend to do, and the practice we now ask for.

Each response looks reasonable on its own. Together they bury the work.
SituationAntipatternBetter practice
Work is ready, but only the coordinator may take the next stepEnd the turn and leave it waitingTake the step now, or say plainly that work stops until someone continues
A test fails because its setup assumed something that does not existTreat it as a product defect and widen the investigationCheck the real interface, fix the test setup and rerun the missing case
A reviewer finds one real defectHand the work to a new repair agent and restart reviewThe original owner fixes it, and the reviewer checks the fix
A corrected package becomes availableKeep exploring edge cases on the old versionVerify the fix first, and keep earlier results that still apply
More agents are availableSplit each task by phase across specialistsGive each agent whole tasks it can finish
Something goes wrongAdd a gate, a classification or a tracker fieldAsk what failure the addition prevents, and fix the boundary instead

Why agents take the long way

A blue robot in reading glasses and a hard hat sits at a school desk behind a towering stack of textbooks, studying a giant flowchart and dreaming of scaffolding, cranes and helper robots to go through the wall, while the end of the wall is a few steps away and the yellow robot taps its foot at A holding a pocket watch.
Figure 6It learned engineering from the textbooks. The way around the wall was never in them.

Start with how these models learn. A language model is trained to predict the next token, a word or a piece of a word, across an enormous amount of written text. Written engineering is dominated by textbook examples: tutorials, methodology guides, process documents and worked examples in which every step is named, assigned and checked. The shortcuts experienced engineers take every day are rarely written down. The model sees far more of the formal process than of the judgment that trims it.

An agent's plan is still next-token prediction. Ask it to lead a large migration and the most likely continuation looks like the textbook: inventory, decompose, assign, verify, report. Each step reads as competent, because in the text the model learned from, it usually is.

The agent acts through tool calls, structured requests to run a command, edit a file, start a worker or update a tracker. A tool call is predicted the same way, as the most likely next action given everything in the agent's context, the working memory of the run. That loop explains most of what we saw.

Figure 7

How an agent decides its next step

Each pass around the loop adds to the context the next prediction is made from.

  1. ContextEverything the agent can see: the request, the files, earlier output and its own notes.
  2. PredictionThe model predicts the most likely next tokens, shaped by the textbook-heavy text it learned from.
  3. Tool callSome of those tokens form an action: run a command, edit a file, start a worker, update the tracker.
  4. ResultThe output, and any plan or checklist the step wrote, goes back into the context.

Repeat. The more process the context holds, the more likely the next step adds more.

Two things follow from the loop. What is in the context shapes what comes next, so once the context fills with plans, checklists and handoff notes, more process becomes the likely next step and the workflow feeds itself. And what is not in the context cannot shape anything. A package waiting for an install, or a worker idle for hours, leaves no tokens behind. The cost of a handoff is invisible to the prediction, while the artifact the handoff produces is right there.

Later training rewards answers that people and automated graders rate highly, and thorough-looking work is easy to rate. That tilts the agent further toward visible artifacts. Our instructions then added pressure in the same direction.

Strong compliance turns each preference into an absolute. An instruction to be rigorous becomes a new gate, a stop the work must pass, where ordinary engineering judgment would have been enough. Corrections pile up the same way: a missed update produces a new checkpoint rule, a bad test a new evidence requirement. Each addition looks reasonable alone. Together they build a process that spends its effort maintaining itself.

None of this is unique to AI. Human organizations fall into the same pattern when they reward finishing a phase, keeping specialists busy and reporting in detail, while nobody owns the result end to end.

The human guides the approach

Panel 1: a person in a plaid shirt holds an instruction card for both robots: check what fits, compare the routes, count the time spent getting ready.
Panel 2: the blue robot measures the yellow robot against the tiny hole; the yellow robot says too small, and the blue robot says around takes twenty seconds.
Panel 3: footprints curve around the end of the wall to B, where the yellow robot cheers made it and the blue robot ticks its checklist: job done.
Figure 8The human guides the approach. The robots choose the twenty-second walk.

The second strip is the lesson. The person does not do the job, remove the wall or hand over a finished route. They say what to check: what fits, which route is shorter and how long getting ready takes. The robots do the rest, and the job ends with the robot standing at B.

Best practices: what we tell agents now

We now start agents with a short operating contract, the instructions an agent receives before it begins. It is not a script for every step. It limits how the work is organized as firmly as it describes what to build. Its core rules are short:

  • One owner per outcome. A component, with its parts, types, styles and tests, stays with one accountable owner until it is finished: its checks pass, its findings are resolved and its review is recorded. Splitting it needs a concrete reason, and a phase label is not one.
  • Prove one real path before scaling. Take a single piece through the normal build, package, install and check before adding workers. Draw the playbook, the repeatable steps, from what actually worked.
  • Check at natural boundaries. Run strict checks as each package becomes ready, early enough to catch basic errors, with no ceremony after every small edit.
  • Review once, and send findings home. Finished work gets one independent review. Findings go back to the same owner, and the follow-up review covers those findings.
  • Measure finished outcomes. Count finished pieces, open defects, waiting, rework and how often a person had to step in. Record counts and busy agents are not progress.
  • Replace rules; don't append them. When the policy changes, keep one current version and remove the old wording.
Listing 1

A starting brief for a large job

Operating contracttext
FIRST PROOFBefore adding workers, take one component through the realbuild, package, install and checks, then one independentreview. Keep the smallest playbook that worked. CHECKS AND REVIEWRun strict checks when a package is ready, not after each edit.Review each finished component once. Send findings back to itsowner, and recheck only those findings. PROGRESSTrack finished components, open defects, waiting, rework andhuman step-ins. Fix the cause of a failure instead of adding aguard, label or handoff. Replace old rules; do not stack them.Before ending a turn, take any ready step or hand it to someonewho can act now. Never leave ready work waiting on you. OWNERSHIPOne owner keeps each component's code, types, styles, package,tests and fixes until it is done: checks pass, findings areresolved and its review is recorded. Split work only for aconcrete reason. A phase is not a reason.
An illustrative example.

A large job still needs a capable agent. It also needs a brief that says what finished looks like, who owns each piece and when to stop adding process. Tell AI what matters, set the limits, and guide the work.

The full comic is available as a poster: download the poster (1200 × 1800).

In brief

Key takeaways

  1. Activity is not progress.

    When we paused the migration, every component had its code recorded as written, roughly one in eight was fully verified and none had been delivered.

  2. Keep one owner per outcome.

    Splitting a job by phase moves responsibility between workers until nobody owns the result.

  3. Watch for stranded handoffs.

    A ready package waited most of a morning for an install that took well under a tenth of a percent of that time.

  4. Make every new step earn its place.

    Adding a guard, a classification or a handoff after each failure builds a process that maintains itself.

  5. Tell the agent what matters, set the limits and say how success is measured.

    Then review finished work once and send findings back to the owner.