Write The Spec First

Tell an agent "add login" and it will fill in every blank you left open: which auth method, whether there's a password reset flow, whether it's free to add a new dependency to solve it. None of those guesses are wrong exactly — they're just not your decisions. You find out an hour later, after undoing the wrong one.

The problem: vague prompts force guesses

"Add authentication" is a goal, not a spec. It doesn't say which token strategy, whether password reset is in scope, or whether the agent can reach for a new library to get there faster. An agent facing that gap does the only reasonable thing: it picks the most common answer. Sometimes that's fine. Often it's not — and you only find out after the code is written, tested, and half-reviewed.

A spec closes the gap before the agent starts. It doesn't need to be a formal document. It needs four things: what you're building, why, what's explicitly out of scope, and the discrete tasks that get you there.

What goes in a one-page spec

Compare the two:

• Vague: "add authentication"
• Clear: "JWT tokens, no password reset, no new dependencies"

That one line removes three decisions the agent would otherwise have made for you. It's not more words for the sake of it — every clause rules out a specific guess. "JWT tokens" picks the auth strategy. "No password reset" bounds the scope. "No new dependencies" constrains the implementation to what's already in the project.

A useful spec answers:

• What you're building, in one or two sentences.
• Why — the constraint or goal driving it (so the agent can make judgment calls that still serve the intent).
• What's out of scope — the things it should not do, which is usually the part a plain prompt skips entirely.
• The task list — the feature broken into small, ordered pieces.

How to run it

1. Write the spec.
2. Pick the next task from the list.
3. Have the agent implement just that task.
4. Review the diff.
5. Commit.
6. Move to the next task.

This loop keeps you in control at every step instead of reviewing one giant diff at the end, where mistakes are harder to isolate and more expensive to unwind. Small commits also give you a clean rollback point if a task goes sideways — you revert one commit, not a day's work.

When it's worth the effort

A one-page spec is overkill for a one-line fix — don't write one to change a button color. It earns its keep on anything with real surface area: a new feature, a tricky integration, anything where an agent working from a bare prompt would have to guess at more than one thing.

Power tricks

• Specs aren't frozen. If a task reveals that a constraint doesn't actually work — say, "no new dependencies" turns out to make JWT verification unreasonably fiddly — go back, edit the spec, and rerun that task.
• Constrain outcomes, not code structure. A spec should pin down decisions like auth strategy and scope, not dictate exact implementation details — leave the agent room to write idiomatic code within your constraints.
• Never batch task review. The point of splitting the spec into tasks is granular review — reviewing everything at the end defeats it.