How to Write Specs for AI Coding Agents

A spec for an AI coding agent is a structured document that states outcomes, boundaries, and verification criteria before the agent writes a line of code. You write it instead of hoping the agent guesses your intent from a one-line prompt. Learning to write one well is fast becoming the actual skill, replacing a chunk of what used to be hands-on coding.

Why writing code stopped being the job

Something flipped in the last two years. Generating code got cheap. Correctness got expensive.¹ An AI agent can produce a working-looking pull request in seconds. Whether it does the right thing, respects the right constraints, and doesn't quietly break something three services away is a different problem. Nobody has automated that part yet.

The numbers back this up. AI adoption among software professionals hit 90% in 2025, up 14 points from the year before, and more than 80% report real productivity gains.² But only 24% report a great deal or a lot of trust in what the AI actually outputs.² Stack Overflow's 2025 survey found a similar split: 84% of developers use or plan to use AI tools, yet 72% say vibe coding, generating software from prompts with no attention to the resulting code, isn't part of their professional workflow.³ People are using the tools constantly. They are not trusting them blindly.

This isn't just a professional-engineer story anymore. Employees across departments are now building their own internal tools with AI agents, often without IT ever seeing a ticket.⁴ For that growing population of citizen builders, learning to write a decent spec matters even more than it does for career developers, because there's usually no second engineer checking their work.

What a spec actually is (and what it isn't)

A spec is not a PRD and it's not a design doc. A PRD tells a human team what to build and why, in prose meant for people. A spec is written for a system that executes it literally. It states outcomes, constraints, and boundaries in a form the agent can act on directly, not interpret loosely.

Thoughtworks and Martin Fowler's team frame spec-driven development across three maturity levels:

• Spec-first: the spec is written once, used to generate the first pass of code, then effectively discarded. Most current tools operate here.⁵
• Spec-anchored: the spec persists alongside the code and gets updated as the feature evolves, staying a living reference rather than a one-time prompt.⁵
• Spec-as-source: the spec becomes the only artifact a human edits directly. Code is generated from it and marked "DO NOT EDIT."⁵

Most teams today are doing spec-first work and calling it spec-driven development. That's fine as a starting point, but it's worth knowing which level you're actually operating at, since it changes how much effort the document deserves. Thoughtworks placed spec-driven development itself, and GitHub's Spec Kit specifically, in the "Assess" ring of its Technology Radar in late 2025, meaning worth exploring but not yet a default choice, in part because current workflows remain elaborate and opinionated.⁵⁶

What should a spec for an AI coding agent include?

Augment Code's framing is the most useful shortcut: a spec needs to answer six questions. Whatever you leave unanswered, the agent will answer for you, and you probably won't like its answer.⁶

1. Outcomes. What does success actually look like when this is done?
2. In/out-of-scope boundaries. What is explicitly part of this task, and what is explicitly not?
3. Constraints and assumptions. What limits, dependencies, or facts about the environment does the agent need to know?
4. Decisions already made. What choices are settled and not up for the agent to reconsider?
5. Task breakdown. What are the discrete units of work, in order?
6. Verification criteria. How will you or the agent confirm the work is actually correct?

GitHub's own research, based on an analysis of more than 2,500 real agents.md files, converges on a related but slightly different set: the best-performing files consistently cover commands, testing, project structure, code style, git workflow, and boundaries.⁷ Vague, persona-less instructions like "you are a helpful coding assistant" turned out to be the single biggest cause of failure across that sample.⁷ Between Augment's six questions and GitHub's six areas, you get almost everything a spec needs to hold up.

How do you write an AI agent spec, step by step?

Addy Osmani's synthesis of practices from Claude Code, Gemini CLI, and GitHub's own research is the clearest practical playbook available, and it runs against the instinct most people have when they first try this.⁸

1. Start high-level, not exhaustive. Write a short product brief, not an RFC. Let the agent draft the detailed version and hand it back to you for review. Oversized upfront context tends to overwhelm a model's attention budget rather than helping it.⁸
2. Use a plan mode before an execute mode. Have the agent propose a plan in read-only mode first, review it, then let it act. Catching a bad plan is far cheaper than catching bad code.⁸
3. Structure with real markdown, not paragraphs. Headings, numbered steps, and explicit lists parse more reliably for an agent than dense prose.
4. Set boundaries in three tiers, not one flat list. Always do, ask first, never do. A flat list of prohibitions gets ignored more often than a tiered one.⁷⁸ "Never commit secrets" is the single most common helpful constraint found across the GitHub study of 2,500 repos, which tells you how often it needs saying.⁷
5. Break work into modular tasks. One task, one clear verification step, rather than one giant instruction covering an entire feature.⁸

If your team is trying to build something like a reliable AI-native development cycle rather than a pile of one-off prompts, this is the layer where that discipline actually lives.

Meet the frameworks: OpenSpec, GitHub Spec Kit, and the lightweight alternatives

You don't have to invent this format from scratch. Two open-source frameworks have already turned it into something you can install today.

OpenSpec keeps a persistent spec library in an openspec/specs/ folder documenting how the system currently works, plus an openspec/changes/ folder where every new feature gets its own proposal, design notes, task list, and spec delta before it merges back into the library.¹⁹ It's gained more than 27,000 GitHub stars in under six months, a fast adoption curve for a workflow tool with no product to sell.¹

GitHub Spec Kit formalizes the same idea into four gated phases: Specify, Plan, Tasks, Implement. GitHub's framing is explicit that the developer's job shifts from writing code to verifying, at each checkpoint, that the spec, the plan, and the tasks still match actual intent.¹⁰

Both are worth trying. Neither is mandatory. Thoughtworks tested three labeled spec-driven tools, including Kiro and Tessl alongside Spec Kit, and found real friction: one small bug fix turned into four user stories and 16 acceptance criteria, and the resulting markdown was, in places, harder to review than the code diff it was meant to replace.⁵ For a small, well-scoped internal tool, a single AGENTS.md file covering the six core areas GitHub identified is often enough. Save the full framework for work that spans multiple sessions or touches more than one service.

The harness matters as much as the spec

A spec tells the agent what to do. It doesn't by itself make the agent stay inside the lines. That's the job of what Addy Osmani calls the harness: the system prompts, hooks, sandboxes, context management, and subagent structure built around the model.¹¹ His framing is blunt: a decent model with a great harness beats a great model with a bad harness.¹¹ A spec without a harness is a set of instructions the agent can still wander away from mid-task. The harness enforces the boundary tiers you wrote in step four above, rather than leaving them as suggestions. Teams that have looked closely at how agents actually behave in practice have found they lean on the same small set of blunt tools, like grep, over fancier ones, which is exactly the kind of finding worth knowing before you overbuild your harness.

How do you verify the agent actually did what the spec said?

Writing the spec is half the job. Verifying that the output matches it is the other half, and that step doesn't disappear just because the spec was good. Useful patterns include self-checks the agent runs against its own output, an adversarial second agent instructed to find what the first one missed, and LLM-as-judge scoring against your stated verification criteria. None of these replace a human looking at critical paths, especially anything touching auth, payments, or data access. Teams that pair a domain expert directly with the model on every pull request have found it closes gaps automated benchmarks miss entirely, which is the core argument behind a taste-tester approach to reviewing AI-generated code. The security side deserves its own attention too: a spec that never gets checked is just a wish list. Pair whatever spec process you adopt with a fuller governance playbook for AI-written code.

When should you skip writing a spec?

A full spec is overkill for a lot of work, and forcing one on every task just adds friction people will route around. Augment Code's decision framing is a reasonable filter to apply before you reach for a template.⁶

• Skip the spec for small, reversible, low-risk changes: a copy tweak, a config fix, a one-file bug patch you can undo in seconds.
• Write a spec for anything that spans multiple sessions, touches more than one service, or has compliance or security implications.
• Write a spec for anything a second person will need to pick up later without the original context in their head.

The judgment call is yours. The point of the framework is to make that call deliberately instead of defaulting to either extreme.

Why this matters beyond engineering teams

The employees writing these specs aren't only software engineers anymore. Gartner's survey of 302 cybersecurity leaders found 69% of organizations suspect or have evidence that employees are using prohibited public generative AI tools, and Gartner projects more than 40% of enterprises will face a security or compliance incident tied to unauthorized shadow AI by 2030.⁴ Separate research puts the base rate of AI use at work even higher: roughly three-quarters of knowledge workers use AI tools in a given quarter, most of it self-directed rather than sanctioned.¹² A lot of internal software is already being built this way, quietly, with nobody outside the person's own laptop knowing what it does or how it was made.

A spec left behind after the work is done isn't just a workflow artifact. It's documentation. It's the difference between an internal tool a company can audit, hand off, and maintain, and one that only makes sense to the person who prompted it into existence. Simon Willison draws a useful line here between vibe coding, where nobody pays attention to what got generated, and agentic engineering, where an engineer uses the agent but stays fully accountable for what ships.¹³ Writing a real spec, and keeping it, is what makes that accountability possible for the growing number of employees now building the software their companies actually run on. It's also part of what it takes to genuinely own that software rather than just having generated it once and moved on, which is where platforms like Remy come in: turning what an employee built with an agent into something the company can track, support, and keep, instead of a black box nobody remembers the reasoning behind.