The small spec that stopped my AI agent from wandering

The problem

The agent kept wandering.

I would ask for one section. It would improve three. I would ask for a copy change. It would touch layout. I would ask for a button fix. It would rename a component because the new name was “cleaner.”

The work looked productive, but review felt terrible.

A diff with twenty tiny surprises is not a gift. It is homework.

The bad first fix

I tried adding stronger language to the prompt:

Only do what I asked. Do not change anything else. Stay focused.

That helped for about five minutes.

The agent still had to decide what “done” meant. It still had to decide which files were in scope. It still had to decide whether a nearby cleanup counted as helpful or risky.

When the task boundary lives only in my head, the agent cannot respect it.

The spec that worked

The fix was a small spec file.

Not a giant product requirements document. Not a corporate ceremony. Just a one-page agreement between me and the agent.

The shape looked like this:

# Unit 04: Agent workflow module

## Goal
Add a 7-step workflow section that teaches the user how to work with AI coding agents.

## Design
Use the existing card style. Make the steps easy to scan on mobile and desktop.

## Implementation
Create one Astro component. Pull all text from the variables file. Do not add React.

## Dependencies
None.

## Verify when done
- Workflow renders on the home page
- Buttons are keyboard accessible
- npm run build passes

That was enough.

The agent no longer had to infer the boundaries. The spec named them.

Why this works

A good spec removes three kinds of guessing.

First, it removes product guessing. The goal says what the user should get.

Second, it removes technical guessing. The implementation section says where the change belongs and what patterns to follow.

Third, it removes finish-line guessing. The verification section says how we know the work is done.

This is where agentic development starts to feel calmer. The model can still make mistakes, but the mistakes are easier to catch because the work has edges.

The happy path

Now I give the agent one unit at a time.

The prompt is simple:

Read the context files. Read Unit 04. Implement only that unit. Run the verification steps. Report the files changed.

The review becomes smaller. The build either passes or it does not. If the agent edits a file outside the spec, I can reject that part without debating taste.

That matters because AI code review is not just about code quality. It is about attention. A small spec protects your attention.

A spec template you can copy

Use this when a task feels too fuzzy:

# Unit NN: Short feature name

## Goal
What user-facing outcome should exist when this is done?

## Design
How should it feel, look, or behave?

## Implementation
Which files or folders are in scope? What patterns must be followed?

## Dependencies
What packages, APIs, or assets are needed? Write "None" if there are none.

## Verify when done
- Command to run
- Behavior to click or inspect
- Files that should not change

Keep it boring. Boring specs are useful specs.

Questions people ask

Is this too slow for small projects?

It feels slower at the start. It is faster when you count the time saved during review and cleanup.

Should every task have a spec?

Every code change that can drift should have one. Tiny copy edits can be simpler. New sections, components, workflows, and refactors deserve a spec.

Can the agent write the spec?

Yes, but review the spec before code starts. If you let the same agent invent the scope and implement it in one breath, you are back to guessing.

The lesson

The spec did not make the agent smarter.

It made the task smaller.

That was the whole trick.