You're already writing specs (I hope)

Hey! I hope you’re having a relaxing weekend! For this newsletter, I’ve tried something new: sharing an extract summarized of one of the chapters I’m currently writing. Let’s begin with an extract about specs and how you can get 10x more performance from your AI coding agent :D

When was the last time you gave an AI coding agent a five-word instruction and got exactly what you needed?

If you’re honest, the answer is “rarely.” Not because the model is bad. Because the agent doesn’t know what it doesn’t know about your context, and it won’t ask (unless you prompt it to do so, but that’s another story…).

Picture a Monday morning ticket: “Fix the login bug.” No description, no steps to reproduce, no expected behavior. If you’re a human developer, you know what to do: push back. You ask what bug, which login flow, what the user sees versus what they should see. You don’t start until you have enough information.

Now hand that same ticket to an AI coding agent.

The agent doesn’t push back. It reads “login bug,” builds an idea of what login bugs usually look like, and generates a fix. Maybe it addresses a token issue, or a redirect loop, or a missing session expiration check. The code will compile. It may look reasonable. But it’s solving the problem the agent imagined, not the problem you have.

This doesn’t disappear as models get smarter. It’s not a capability problem. It’s a context problem.

You’ve heard “garbage in, garbage out” applied to data pipelines. It applies equally here, with one difference: the garbage coming out looks clean.

When a data pipeline ingests corrupted data, the output is usually obviously wrong. When an LLM generates code from a vague spec, the output looks fine.

The problem is in what the code does, not how it’s written: the code does something reasonable, just not the thing you needed.

The model also never signals doubt. An agent given a vague description produces code with the same confidence as one given a detailed spec. No hedging, no “I’m not sure about this.” Just code, formatted cleanly, ready to copy.

It gets worse over time. A wrong assumption early in a task, say, choosing synchronous where your system needs asynchronous, becomes the base every later decision builds on. By the time the agent has written five hundred lines, that assumption is buried inside a reasonable-looking implementation that doesn’t fit your architecture at all.

A spec breaks this before it starts. The early decisions are made by you, not by the agent mid-flight. The agent handles implementation, but you control the intent.

Here’s something most engineers don’t realize: you already know how to write specs. You’ve been doing it for years (I hope). You just haven’t called it that.

Every PRD your team produces is a spec. Every Architecture Decision Record explains what was decided and why, and what options were ruled out. User stories, when written well, do the same thing: they make intent concrete before anyone writes a line.

What all these documents have in common is that they exist because unclear requirements cost money. The software industry figured this out long before AI was part of the conversation.

We can see exactly the same with the relative cost to fix bugs. It’s the same for AI-generated code. Steering the model initially doesn’t cost much. Fixing stuff once it’s in prod… it’s a different story!

The most common objection: “I don’t have time for this.”

The cost of writing a spec is upfront. Twenty minutes, maybe forty, before any implementation starts. That feels like delay. It is delay.

The cost of not writing one is hidden. It shows up later, spread across things that don’t obviously connect: an implementation that misses the mark, a code review that spends half its time figuring out what the code was supposed to do, a PM conversation to re-clarify something that should have been clear before anyone opened an editor, a production bug that traces back to an assumption nobody thought to question.

None of those feel like the cost of skipping a spec. They feel like normal friction.

It also pays off over time. A spec written today helps the debugging session six months from now, and the new engineer who needs to understand what a feature is actually supposed to do. You pay once.

There’s something a meeting or a Slack thread can’t do: writing forces you to actually commit to answers.

You think you understand a problem. You sit down to write about it. Two paragraphs in, you’ve found an assumption you hadn’t examined, or a constraint you’d quietly forgotten.

Say a team agrees to “add authentication to the admin panel.” Everyone nods in the meeting. Then you sit down to write the spec:

• Which authentication method? OAuth2, JWT, session-based, magic link?

• What happens when a token expires mid-session?

• What about existing sessions if you’re adding auth to something that previously had none?

• Is there a “stay logged in” option, and if so, how long is “long”?

These aren’t edge cases. They’re decisions any implementation will have to make. The spec just forces you to make them before the code does.

When humans work together, an unclear requirement usually leads to a conversation. An agent doesn’t stop to ask. It picks an answer and keeps going. Every gap in your spec is a decision you’ve handed to the model.

Pick one task from your backlog. Before opening your AI tool, write down:

1. Goal: what should be true when this task is complete?

2. Constraints: what must not change or break?

3. Acceptance criteria: how will you verify it’s done? Write three to five testable conditions.

4. Non-goals: what is explicitly out of scope?

Hand it to the agent as context. See what changes.

The spec probably takes fifteen minutes. What it saves is harder to measure, but you’ll notice.

This article is adapted from “AI-Native Engineering: Building Production-Ready Software with AI,” a book about the practices that separate structured, production-ready AI use from vibe coding.