Why does your first agent run disappear into plumbing?

Why does your first agent run disappear into plumbing?

Because "build me an app where people can share reading lists" contains one sentence about reading lists and an unwritten twenty about everything that has to exist before a reading list can have an owner. Your agent reads the whole request, including the unwritten part, and starts at the bottom. By the time it reaches your actual idea it has spent most of its run, most of its context window, and most of your patience on work that is identical in every product.

Nothing has gone wrong. That is what you asked for.

Unpacking one sentence

Take that request literally and see what it implies.

For someone to have a reading list, there has to be a someone, which means accounts. For accounts to be useful across visits, there has to be sign-in, which means sessions, and email verification, and a decision about passwords or codes or social sign-in. For a list to be private, every query has to be scoped to its owner. For any of it to be online, there has to be a server, a database, a container, and a deploy.

And that is the free version. Charge for it and you add a checkout, a webhook, a subscription record, and the logic that decides whether this account may currently use the feature.

Somewhere in there is the part you actually care about: what a reading list is, what makes yours different, why anyone would use it. It is perhaps five percent of the code and effectively all of the product.

Why the agent starts at the bottom

Two reasons, and both are good reasons.

Dependency order. You cannot write a reading list that belongs to a user before the user exists. The agent is not procrastinating, it is topologically sorting. The plumbing genuinely does come first.

Ambiguity. Your one sentence about reading lists is under-specified, and your agent knows it. Sign-in is not under-specified at all; there is a well-known right answer it has seen thousands of times. So it does the confident work first and arrives at the ambiguous work later, with less room left, which is precisely backwards from what you want.

The cost is not the tokens

It is tempting to think of this as a waste of money. It is worse than that, in three specific ways.

The interesting decisions happen last, when there is least room. Your feature is the part that needs your judgment, several rounds of it. It gets whatever is left of the run and the context window after the plumbing has consumed both.

You cannot review what you got. By the end you have a large diff spanning sign-in, payments, email, and your feature. The question you need to answer is not "does this work", it is "is this right in the four places where wrong and right look identical". That is a slow, careful read of code you did not write and did not want to think about. Most people skim it, and the failures that skim misses surface months later.

There is nothing to check the work against. In a codebase with no test suite the agent has no way to know whether it has finished. It cannot run anything. It reports success because the code it wrote looks like code that works, which is the only signal available to it.

What actually changes the outcome

Not a better prompt. The problem is not phrasing, it is the starting position.

Point the agent at a codebase where accounts, sign-in, payments, email, jobs, permissions, and deploy already exist, are tested, and are documented, and every constraint above inverts:

• The dependency order is already satisfied. Users exist. Accounts exist. The agent starts at your feature because there is nothing underneath it left to build.
• The whole run goes to the ambiguous part, which is where you actually want its attention and yours.
• The diff is small and entirely about your product. You can review it properly, because it is the part you have opinions about.
• The agent can check itself. There is a test suite, so "done" becomes something it can verify rather than assert. It runs the tests, sees what failed, and fixes it before you ever look.

That last one is the biggest change, and it is the one people underestimate. An agent that can verify its own work behaves differently from one that cannot. It stops guessing.

The conventions matter as much as the code

A subtle point that is easy to miss: a kit gives an agent more than working plumbing. It gives it a grain to follow.

When every existing feature is built the same way, an agent adding the next one has a template. It does not have to invent a structure, and it does not have to guess whether you would prefer this or that, because there is a worked example sitting right there and a written note saying "copy this shape".

That is why the guide file matters so much. A short document that says "here is the one right way to do each thing, here is the file to copy, here is the rule that must never be broken" removes most of the decisions an agent would otherwise make on your behalf, badly, at three in the morning. It is worth writing carefully, and it is covered in how to write a guide file your agent will actually follow.

What good looks like

Here is the shape of a run that is going well. You ask for a feature. The agent reads the guide file, finds the existing example of a similar feature, copies its structure, writes the model, the permission rules, the screens, and the tests, runs the whole suite, fixes the two things that failed, and comes back with a diff that is entirely about your feature and nothing else.

That is not a better agent. It is the same agent, standing somewhere else when it starts.

The one-line version

Your first run does not disappear because your agent is weak. It disappears because you asked it to build a foundation, and foundations are large, mandatory, and identical everywhere.

Give it the foundation and ask for the building.

If you want the concrete list of what that means, see what a starter kit is and everything One Shot gives you on day one.