You skipped the spec: how I work with coding agents every day

When a developer tells me they tried coding agents and the code was bad, my first question is about the spec. Usually there was none. They described a feature in two sentences, the agent built something plausible, and the result was not what they meant.

The agent did what it was asked. The ask was the problem.

My workflow fixes that by putting the spec in the middle of everything. The agent writes the spec, and nearly all of the code and tests too. My work is to steer: decide what I want, question the agent where I think it is wrong, and approve the design before anything gets built.

This is the third post in a series on working with agents. The first covers the developer’s agent stack. The second covers skills over prompts.

The loop

Here is the sequence I follow for almost every change:

1. I tell the agent what I want and why.
2. The agent writes the spec.
3. I read it and question it.
4. The agent revises the spec, sometimes including the whole architecture.
5. Once the design is final, the agent implements it.
6. The agent tests it, including in the browser.

Steps 3 and 4 are where the value is.

Question the spec where you think it is wrong

I do not review an agent’s spec by reading it and nodding. I ask it questions built around three things: what I want, how I want it done, and where I think the agent is making a mistake.

The answers matter more than the original spec. When I push on a design choice, a good answer shows the agent understood the constraint and picked a defensible option. A weak answer shows it filled a gap with something that sounded right. Based on how it answers, I change the design.

Sometimes that means asking for a completely different architecture. That is cheap at this stage. Nothing is built yet. The same change after implementation costs a rewrite, a review cycle, and usually a second round of bugs.

This is where your experience earns its place. The agent can write a spec faster than you can. It cannot know which part of your system will push back on its design. You can, and the spec review is where you apply that.

Then let it build and test everything

Once the design is settled, I hand off implementation and testing completely. The agent writes the code, writes and runs the tests, and checks the result in the browser through Playwright or Chrome DevTools.

The browser step is not optional. The most common failure I see is an agent that claims it is done too early. It writes code, reads it back, and reports success. Making it open the app and click through the flow it changed catches the cases where the code compiles but the feature does not work.

Two other failures show up often enough to plan for:

• The agent ignores the codebase’s conventions. The fix is repository rules built from review comments, so conventions apply before the code is written.
• Long sessions drift. The agent loses earlier decisions or fills its context with old file dumps. I start a fresh session per task, send big reads to subagents, and write decisions into the spec instead of trusting the chat to remember them.

Run agents in parallel, carefully

I run several agents at once in two ways.

The first is parallel sessions on independent tasks. If two changes do not touch the same files, they can run in separate sessions or worktrees at the same time. Each one follows the same loop. I review each spec separately.

The second is subagents inside one task. When a task needs wide research, the main session sends a subagent to do the reading and return the conclusion. The main session keeps its context for the decisions.

The limit is my attention, not the number of agents. Every parallel session still needs its spec reviewed. Running five sessions whose specs nobody reads is five times the original problem.

What a lead should set up

A workflow that lives in one engineer’s habits disappears when that engineer moves on. To make it the team’s default:

1. Make spec, review, build, test the expected path for agent work, not a personal preference.
2. Write review standards for agent-written PRs. Decide what a reviewer checks, and make “verified in the running app” part of done.
3. Put the repository rules and shared skills in place, so every engineer’s agent starts from the same conventions.
4. Review specs, not only diffs. A bad design caught at the spec stage costs minutes. Caught in code review, it can cost days.

Where your time goes now

Working this way, I write very little code by hand. I do more of the work that was always the hard part: deciding what to build, questioning the design, and checking that what shipped actually works.

If the agent’s code was bad, look at the spec first. Then look at whether anyone questioned it.