Coding with an agent feels like magic for about a week. You describe a feature, it writes the code, and you move faster than you ever have. Then you ask it to change something, and it confidently rewrites the wrong half, because it never actually understood what the feature was for. It only understood your last sentence.

The problem is not the model. It is that a prompt is a bad place to keep intent. Prompts are momentary. The understanding evaporates the second the conversation ends. What survives is the code, and code tells you what was built, never why.

A prompt is a request, a spec is a contract

When you prompt your way through a feature, every message is a fresh negotiation. The agent guesses at the parts you left out, and its guesses drift. By the tenth message you are no longer building, you are correcting.

A spec changes the shape of the work. Before any code, we write down what we are building and why. What problem it solves, what the inputs and outputs are, what the edge cases are, what done looks like. It does not have to be long. It has to be clear. Now the agent is implementing a contract instead of guessing at a wish.

An agent can build the feature perfectly and still have no idea why it exists. The spec is where the why lives.

The spec is for the humans too

The convenient thing is that the document that makes an agent reliable is the same document that makes a team aligned. The spec is where disagreements surface before they become code. It is where the product owner and the engineer find out they pictured two different things, while changing it is still free.

We have caught more bugs in a one-page spec than in hours of review, because the cheapest place to fix a misunderstanding is before it has been built twice. The spec turns a vague feeling into something you can point at and argue with.

How we work in practice

We keep specs short and close to the code. For a feature, that might be a handful of paragraphs: the goal, the data, the rules, the cases that must work, and the cases that must fail. The agent reads it, implements against it, and we review the result against the same document. When the feature changes, the spec changes first, and the code follows from it.

This also fixes the thing that makes AI coding scary at scale. When intent lives in a spec, a new engineer or a fresh agent session can pick up the work without the context being lost. The understanding is written down, not trapped in one person's chat history.

Speed without amnesia

The promise of AI-assisted development is speed. The hidden cost is amnesia. Move fast enough by prompt alone and you end up with a codebase nobody, human or model, can explain. The spec is the cure. It is a small amount of upfront writing that buys you a system whose intent is legible months later.

Write the spec first. Let the agent build against it. Review against it. You will move just as fast, and you will still understand what you built when it matters.