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.



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


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


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


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


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.
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.
| Situation | Antipattern | Better practice |
|---|---|---|
| Work is ready, but only the coordinator may take the next step | End the turn and leave it waiting | Take the step now, or say plainly that work stops until someone continues |
| A test fails because its setup assumed something that does not exist | Treat it as a product defect and widen the investigation | Check the real interface, fix the test setup and rerun the missing case |
| A reviewer finds one real defect | Hand the work to a new repair agent and restart review | The original owner fixes it, and the reviewer checks the fix |
| A corrected package becomes available | Keep exploring edge cases on the old version | Verify the fix first, and keep earlier results that still apply |
| More agents are available | Split each task by phase across specialists | Give each agent whole tasks it can finish |
| Something goes wrong | Add a gate, a classification or a tracker field | Ask what failure the addition prevents, and fix the boundary instead |
Why agents take the long way

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.
How an agent decides its next step
Each pass around the loop adds to the context the next prediction is made from.
- ContextEverything the agent can see: the request, the files, earlier output and its own notes.
- PredictionThe model predicts the most likely next tokens, shaped by the textbook-heavy text it learned from.
- Tool callSome of those tokens form an action: run a command, edit a file, start a worker, update the tracker.
- 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



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.
A starting brief for a large job
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.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
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.
Keep one owner per outcome.
Splitting a job by phase moves responsibility between workers until nobody owns the result.
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.
Make every new step earn its place.
Adding a guard, a classification or a handoff after each failure builds a process that maintains itself.
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.



