The Spec That Makes AI Agents Work Independently

March 22, 2026

I keep coming back to the same problem.

Someone tells me they tried running Claude Code on a task and it “went off the rails.” They describe the prompt they used. The prompt is always something like: “Build a dashboard for user analytics.”

That’s not a spec. That’s a wish. (More on this pattern in why vibe coding breaks at scale.)

What a spec actually is

A spec is the document that makes you unnecessary. If the AI agent can read your spec and build the thing without asking you a single question, the spec is good enough. If it needs to ask – or worse, if it guesses instead of asking – the spec is incomplete.

Here’s a real spec I used last week for a Scouter feature:

Task: Add creator search endpoint

File: src/api/routes/creators.ts

Add a GET /api/creators/search endpoint that accepts:
- q (string, required) – search query
- platform (enum: instagram | tiktok | youtube, optional)
- min_followers (number, optional, default 1000)
- max_followers (number, optional)
- page (number, optional, default 1)
- per_page (number, optional, default 20, max 100)

Use the existing CreatorService.search() method.
Return the standard paginated response format from src/api/types.ts.
Add input validation using the existing zod schemas in src/api/validation/.
Add the route to the router in src/api/index.ts.

Test: a GET to /api/creators/search?q=fitness&platform=instagram
should return a paginated list of creators matching the query.

That took me about 90 seconds to write. Claude Code built it in under 4 minutes. The diff was 3 files, all correct. I reviewed, approved, and moved on.

The five things every spec needs

I’ve run hundreds of these tasks. The specs that work always have the same five elements. (I expand on each one with before/after examples in how to write specs that AI can execute.) The ones that fail are always missing at least one.

1. The file path. Where does this code go? Not “somewhere in the API layer.” The actual path. src/api/routes/creators.ts. Claude Code is navigating a codebase. Give it the map.

2. The interface. What goes in, what comes out. For an API endpoint: the parameters, the types, the response shape. For a UI component: the props, the rendered output, the user interactions. The more precise the interface, the less interpretation the agent does.

3. The existing code to use. “Use the existing CreatorService.search() method.” This is the most underrated part. Every codebase has patterns, utilities, and conventions. If you don’t point the agent at them, it invents new ones. Then you have two patterns where you had one.

4. The constraint. What this is NOT. “No multi-entry export.” “Max 100 per page.” “Don’t modify the existing schema.” Constraints prevent scope creep. The agent will add features you didn’t ask for if you don’t tell it not to.

5. The test. How do you know it works? One concrete scenario. “A GET to this URL should return this shape.” The test isn’t for a test suite (though it can be). It’s for the agent to know what done looks like.

What happens when you skip the spec

Last month I got lazy. I told Claude Code: “Add export functionality to the journal view in Lucid.”

It built an export system. A comprehensive one. Multi-format (PDF, Markdown, plain text, HTML). Multi-entry batch export. Custom date range selector. Export history. It was impressive. It was also about 400 lines of code I didn’t need and it touched 12 files across 4 directories.

I threw it away and wrote a spec.

The spec version: 47 lines of code, 3 files, PDF only, single entry, 4 minutes. That’s the one that shipped.

The vague prompt produced more code. The spec produced the right code.

Why this matters for parallel work

You can’t run 8 vibe coding sessions. Each one needs you watching, correcting, redirecting. You’re the context. Without you, the agent wanders.

Specs make you optional during execution. You write the spec (60–90 seconds). The agent builds (3–20 minutes). You review the diff (2–5 minutes). The agent never needs you in between.

That’s what unlocks the 8-terminal workflow. Not a better AI. Not a faster computer. Better instructions.

Write the spec. Let it build. Review the output.

Eight times.