How to Write Specs for AI Agents That Actually Execute

Knowing how to write specs for AI agents comes down to one property: implementation decisions flow back into the specification, which is what keeps the spec and the code from drifting apart.

From Static Specs to Specs an Agent Can Execute

Engineering teams using AI coding agents hit the same failure mode: the markdown says one thing, the repository says another, and the next regeneration cycle amplifies the mismatch. Writing in InfoQ, Hari Krishnan frames the underlying problem: a code issue reflects a gap in the specification, and because AI generation is non-deterministic, that gap keeps resurfacing as code is regenerated. That makes static specs fragile in workflows that expect repeated regeneration, review, or multi-step handoffs.

A spec an agent can execute changes the direction of information flow: it stops being a one-time prompt and becomes an evolving artifact that captures requirements, constraints, and implementation decisions. Liu Shangqi at ThoughtWorks, Anthropic's engineers, and Addy Osmani each emphasize a similar operating principle: write enough structure for the agent to act correctly, then update it as reality changes.

Some vendors now describe the spec as workflow infrastructure, not documentation. Augment Cosmos, Augment Code's unified cloud agents platform, available on all paid plans, is one example: its agents run in the cloud, read the repositories they are pointed at, and work in sandboxed virtual machines. This guide explains which sections a spec needs, how much detail helps before it starts hurting output, and how to review an agent-updated spec without creating documentation debt.

Why Static Specs Fail Agent Workflows

Static specs fail agent workflows because nothing carries what implementation learns back, so drift compounds across every regeneration cycle.

The root cause is directional. Static specs flow one way: a developer writes requirements, an agent consumes them, and the spec remains unchanged while the codebase evolves. Writing the decisions back adds a feedback loop. In a talk on AI-native development at InfoQ Dev Summit Munich, Patrick Debois makes the same point: writing specs and requirements down aligns both the agents and the humans on a team.

This feedback loop changes the role of the spec. A community discussion in the github/spec-kit repository, opened September 10, 2025, shows practitioners split on exactly that: whether the spec or the shipped code is the real source of truth once change requests arrive. In mature spec-driven workflows, the specification is the artifact that gets maintained, and implementation is the output regenerated from it.

Not every change has to originate in the spec, but teams that routinely regenerate code from stale specs should expect drift to recur.

Cosmos addresses this where the drift happens: its agents read the repositories on each session, so the context behind a spec update comes from the code as it stands.

The Four Phases of Bidirectional Spec Updates

Bidirectional spec updates require clear separation between initial intent and implementation, followed by review and refinement to keep both aligned. Writing on the ThoughtWorks blog, Liu Shangqi describes the same split, and notes that reviewing and validating the specifications is usually an iterative process that requires a human in the loop.

The four phases below illustrate how multi-agent code-generation workflows are structured when specs are treated as coordination infrastructure rather than as prompts.

Phase 3 is the defining characteristic. Without it, specifications are just elaborate prompts; with it, they become coordination infrastructure that more reliably reflects the current system state over time. Cosmos can put phase 3 on a trigger, not on someone remembering: an Automation wires GitHub to an Expert, so a merged pull request starts the session that revisits the spec.

Krishnan's warning holds here: adopting spec-driven workflows without changing how product, architecture, engineering, and QA stakeholders work together risks generating layers of documentation that are outdated on arrival.

How to Write Specs for AI Agents: Seven Sections That Earn Their Place

A useful living spec gives agents enough context to implement correctly without turning the document into a brittle script. Addy Osmani, writing on O'Reilly Radar, names full commands, project structure, code style shown by example, and three-tier boundaries. The AGENTS.md format adds a project overview, and the last two below keep a spec current once agents write back to it.

1. Agent role and project overview

The agent role and project overview reduce ambiguity by defining priorities, domain, and stack before implementation begins. That framing lets the agent make tradeoffs that fit the repository, not generic defaults.

## Agent Role
You are an implementor for a Node.js REST API serving financial transaction data.
Priority order: correctness > security > performance > code elegance.

## Project Overview
Mission: Real-time transaction processing API serving 10k+ merchants.
Stack: Node 20, TypeScript 5.3, PostgreSQL 15, Redis 7, Docker.

2. Key commands

Key commands improve execution reliability because agents repeatedly need exact build, test, lint, and migration syntax. Full commands reduce guesswork and cut avoidable tool errors.

## Commands
- Run tests: `npm test`
- Run single test: `npm test -- --grep "auth"`
- Build: `npm run build`
- Lint: `npm run lint`
- Database migrations: `npm run migrate:latest`
- Type check: `npx tsc --noEmit`

3. Architecture and critical files

Architecture and critical files cut navigation time because file:line references point agents at the real control points. Exploration overhead drops, and so does the chance of editing the wrong layer.

## Critical Files
| What              | Where                        |
|-------------------|------------------------------|
| App entry point   | `src/index.ts`               |
| Route definitions | `src/routes/index.ts:15`     |
| Auth middleware   | `src/middleware/auth.ts:42`  |
| DB connection     | `src/database/connection.ts` |

4. Code style via examples

Code-style examples improve consistency because a single working snippet shows patterns, error handling, and logging conventions more clearly than prose. Generated code then arrives in a shape reviewers already recognize.

// TypeScript 5.x
// Behavior: returns { error: "User not found" } and logs structured context on failure.
const result = await fetchUser(id)
if (result.error) {
  logger.error("Failed to fetch user", { id, error: result.error })
  return { error: "User not found" }
}

return { data: result.data }

5. Three-tier boundaries

Three-tier boundaries control agent autonomy by separating default-safe actions from changes that require approval or are prohibited outright. High-risk areas stop being one careless edit away.

## Boundaries
### ✅ Always
- Write tests before implementation
- Use TypeScript strict mode
- Log errors with structured fields (never plain strings)

### ⚠️ Ask First
- Adding new dependencies
- Changing database schema
- Modifying authentication logic

### 🚫 Never
- Commit credentials or API keys
- Modify `.env.production`
- Push directly to `main`

6. Implementation status

Implementation status tracking keeps coordination cheap because the spec shows what is complete, in progress, or blocked. Reviewers and parallel agents work from the same state without asking.

├─ ✓ Hero Section (completed)
├─ ✓ Feature Sections (completed)
├─ ◐ Redesign Hero (in progress)
├─ ◐ Mobile View (in progress)
└─ ○ Animations (not started)

7. Decision log

Decision logs prevent repeated debate because architectural choices and their reasons stay attached to the spec. Future agents and reviewers preserve intent and do not rediscover it.

## Decision Log
- March 15, 2026: Using RS256 for token signing (security audit requirement)
- March 16, 2026: Repository pattern for data access (consistency with existing services)

Writing Requirements at the Right Granularity

Requirement granularity determines whether a living spec guides implementation or overwhelms it.

The over-specification problem

Over-specification creates unstable agent behavior because detailed instructions can be either ignored or followed too literally, and both outcomes degrade implementation quality. Teams need enough structure to constrain risk without dictating every step.

Birgitta Böckeler's hands-on evaluation of three spec-driven tools, published in Martin Fowler's Exploring Gen AI series, found the workflow overkill on small work: Kiro turned one small bug fix into 4 user stories carrying 16 acceptance criteria between them. Kent Beck, quoted in Fowler's Fragments on January 8, 2026, identifies the philosophical flaw, calling it a bizarre assumption that nothing will be learned during implementation that would change the specification.

Write enough spec to orient the agent and establish constraints, then iterate. Treat the spec as a hypothesis about what needs to be built, not a finished blueprint.

Declarative outcomes beat imperative instructions

Declarative requirements produce better agent behavior because they describe the desired outcome and constraints without prescribing every implementation step. The agent keeps room to apply the patterns already in the codebase, and the criteria stay reviewable.

Chinmay Kakatkar, writing in Towards Data Science, ran one task through both framings:

The declarative prompt produced a four-line NumPy implementation; the imperative one produced the longer hand-rolled version its steps prescribed. Osmani makes the same case in a newsletter essay on guiding agents with clear problem definitions and success criteria.

Before and after: a complete requirement rewrite

A good requirement rewrite improves implementation accuracy by separating context, constraints, output, and success criteria into fields that agents can act on and reviewers can verify.

Before (under-specified, mixed concerns):

Create a user dashboard that shows analytics. Use Redux for state management.
It should load fast. Use Material-UI. Make it look modern.

This mixes functional requirements, technical mandates, unmeasurable performance goals, UI library choices, and subjective design language.

After (properly structured living spec):

## User Authentication
Context: New users cannot access protected endpoints. We need JWT-based auth.

Constraints:
- Use only standard libraries; no external auth services
- Tokens expire in 15 minutes
- Refresh tokens valid for 7 days
- Must work with existing user DB schema

Output Specification:
- POST /auth/login endpoint returning JWT
- Middleware function for route protection
- Unit tests covering happy path + 3 error cases
- Return format: JSON with {token, refreshToken, expiresIn}

Success Criteria:
- All tests pass
- No breaking changes to existing user endpoints
- Response time < 100ms for token validation

Anthropic's engineering post on context engineering states the governing principle: "striving for the minimal set of information that fully outlines your expected behavior." Minimal does not mean short.

Specs for Multiple Agents: What Is Shared and What Is Per-Agent

When several agents work one repository, the spec splits in two: a shared record of intent, task boundaries, and accepted decisions every agent reads, and per-agent instructions naming what each may touch. Once agents run in parallel, that shared half becomes operational coordination and stops being planning text. Autonomous agents cannot stop to ask which of two conflicting instructions wins, so the shared half has to settle that in advance.

Cosmos organizes that split into three documented primitives. An Expert is a reusable template holding instructions, a model, the capabilities it can reach, and the triggers it reacts to. An Environment is the virtual machine it runs in, bundling a base image, repositories, and environment variables. A Session is the conversation with an Expert: every message, turn, and tool call.

Dependency-aware decomposition matters because shared type or schema changes can create race conditions and merge conflicts if tasks are split without dependency order. Cosmos handles that ordering through its Project Builder Expert, which breaks a feature into tickets and dispatches implementation to PR Author workers in dependency waves. Cosmos ships a library of template Experts for work that recurs across teams:

Human judgment here is a configured policy, never a default: the Risk Analyzer Expert auto-approves intrinsically low-risk changes under a policy the organization sets, and routes the rest to human review. A human always performs the final merge.

Reviewing Agent-Updated Specs

Reviewing agent-updated specs requires checking both implementation accuracy and whether the spec still captures the team's real decisions. GitHub's launch post for Spec Kit described four phases, Specify, Plan, Tasks, and Implement, treating the spec as the shared source of truth; the toolkit has since reached 1.0 and added a converge phase.

Four triggers for spec review

Spec review should happen at predictable transition points because drift usually appears when code, requirements, or data models change faster than documentation. Regular triggers keep the spec close enough to implementation to remain useful.

• After each agent implementation cycle: the team reviews incremental changes, not thousand-line code dumps
• Before the coding phase begins: a reviewer validates the spec itself before implementation starts
• When agents surface ambiguities or edge cases: these moments mark gaps that need clarification
• When data models or requirements change: the spec updates immediately

The fourth is the one teams skip, because a data model change reads as a code change until the spec starts lying.

What to focus on during spec review

Spec review should focus on high-risk mismatches because correctness problems usually hide in architecture, security boundaries, and undocumented decisions rather than syntax. Reviewing those areas first keeps agent-written changes maintainable over repeated regeneration cycles.

Anthropic's guide on building effective agents makes human review structural: automated testing verifies functionality, but human review "remains crucial for ensuring solutions align with broader system requirements." Three areas repay that scrutiny first.

• Architectural coherence: consistency across the codebase and alignment with system design
• Security boundaries: the application security vendor Bright Security singles out authentication, authorization, session handling, and state transitions, where generated code most often flattens who may do what and when
• Decision log entries: confirm the architectural choices recorded in the spec still reflect team intent

All three are invisible to a reviewer reading only the diff.

Why version-controlled specs reduce drift

Version-controlled specs reduce drift because the same review, diff, and history tools used for code also expose requirement changes over time. That creates institutional memory for both humans and agents.

In Osmani's workflow, the spec file is committed to the repo so the agent can use git diff or git blame to understand changes across sessions.

Cosmos keeps the matching record: a Session is saved indefinitely and reopenable, so the reasoning behind a spec edit outlives the session that produced it. The Context Engine does the other half: it semantically indexes and maps a codebase, understanding relationships between hundreds of thousands of files, which keeps a spec anchored to the real structure of the code.

Eight Antipatterns That Derail Agent Workflows

Agent workflows break when the specification either omits critical constraints or tries to control every implementation detail. Osmani's write-up frames the core principle: teams plan, verify, and refine a spec for an AI agent, and never treat it as a one-and-done artifact.

In a separate memo on supervised agentic coding, Böckeler catalogued the failure modes she had to steer around: misdiagnosis of problems, brute-force fixes in place of root cause analysis, and misunderstood or incomplete requirements. Intent plus constraints produces more stable outcomes than procedures plus exhaustive detail.

Protecting critical decisions without over-specifying

Protected-decision markers preserve architectural constraints by separating non-negotiable choices from implementation details that agents can adapt. Security and compliance decisions survive a rewrite that touches everything around them.

<!-- BEGIN USER-SPECIFIED -->
Authentication Design Decision:
We use JWT tokens with 15-minute expiration and refresh token rotation.
DO NOT change this to session-based auth or increase token duration.
Rationale: Security audit requirement from January 15, 2026.
<!-- END USER-SPECIFIED -->

Specs Across the Tool Landscape

Spec-driven development covers a family of workflows whose tools disagree about where the spec lives, who edits it, and what happens when the code moves first. The table below shows how agentic and spec-driven coding approaches differ, so teams can choose on workflow shape and not on marketing labels. Each row reads off that vendor's own documentation, September 21, 2026.

Cosmos combines shared context and memory with explicit multi-agent coordination. That matters most for teams that need orchestration across large, existing codebases rather than single-agent assistance.

A ThoughtWorks blog post from December 2025 calls spec-driven development an emerging approach, and the format layer underneath it has settled faster than the tooling. AGENTS.md is an open format and not a ratified standard, now stewarded by the Agentic AI Foundation under the Linux Foundation and read by Cursor, Codex, Copilot's coding agent, and Augment Code.

What to Do Next

Pick one task this week that is large enough to drift but still reviewable in a single pull request: a JWT auth change, a billing workflow fix, or a cross-service refactor. Write the spec in the repo, define 3-5 measurable success criteria, and require implementation updates to the decision log before merge. That process change usually reveals whether the team has a spec problem, a review problem, or a coordination problem. The tradeoff is that every logged decision is one more thing to review, so measure what the first task costs before widening it.

Frequently Asked Questions About Specs for AI Agents

Related Reading

• 6 Best Spec-Driven Development Tools for AI Coding in 2026
• 5 Best AI Spec Review Tools for Development Teams (2026)
• 6 Best Devin Alternatives for AI Agent Orchestration in 2026
• Best Agentic OS Platforms for Enterprise Teams
• 13 Best AI Coding Tools for Complex Codebases in 2026