Engineering Spec Formats That Work Well With AI Agents

An AI coding agent doesn't fail because it's dumb. It fails because it's guessing. If you hand it a paragraph of prose describing what you want, it'll write code that looks right, compiles, maybe even passes a quick glance. Then it turns out the agent invented an API that doesn't exist, or built the feature against assumptions nobody actually held. The spec wasn't wrong. It just wasn't structured enough for the agent to check its own work against it.

That's the real failure mode behind so-called "vibe coding": not vague intent, but formats with no explicit goals, no constraints, no acceptance criteria. An agent reading unstructured prose has nothing to verify against. It fills gaps with whatever's statistically plausible, and plausible isn't the same as correct. As agent-driven projects scaled through 2025 and into 2026, this pattern (drift, hallucinated APIs, decay under scale) pushed teams toward something more deliberate: structured spec formats built specifically so agents have something concrete to hold onto.

Andrej Karpathy's 2026 term for this shift, "agentic engineering," captures the change in role. The engineer isn't writing code line by line anymore. The engineer is directing a system and checking its output. That role only works if the spec format gives the agent something precise enough to direct and something precise enough to check. Format is what makes the role possible.

The stakes here aren't abstract. Research on this shift suggests an extra hour spent writing a properly structured spec can save roughly three days of agent thrash and three weeks of code review down the line. That's not a small margin. It's the difference between agentic engineering working as advertised and agentic engineering becoming a slower, more expensive way to write bugs.

This piece maps out what the best spec formats have in common: explicit goals, explicit constraints, explicit acceptance criteria, and the structural habits that keep those things useful over time.

The three-layer model: how project context, feature specs, and reusable skills each carry different structural responsibilities

Not every spec needs to say the same kind of thing. Split the problem into three layers, each with its own scope and its own contract with the agent:

Layer 1: Project context. What does the agent need to know about this codebase, all the time, on every task? Build commands, code style, architectural quirks. Layer 2: Feature and task specs. What does the agent need to get done, specifically, on this one unit of work? Layer 3: Reusable agent skills. What procedures should the agent be able to load on demand, across any project, not just this one?

Persistent, task-scoped, portable. Three different jobs, three different lifespans.

The industry is converging on this layering for a reason. As the agent ecosystem matures, a second wave of standardization is showing up: open, file-based, human-readable, version-controlled formats that give agents consistent structured context no matter which tool is reading them.

This is separate from protocols. A protocol of that kind defines how systems talk to each other. These formats define what an agent actually knows going into a task. Different problem, different structural answers.

A spec that mixes all three jobs into one document forces the agent to figure out scope on its own. Is this instruction permanent or just for today? Is this procedure specific to this repo or usable anywhere? Every time an agent has to guess at scope, that's a new place for drift to sneak in.

Layer 1 (AGENTS.md): the structural properties of a project context file that agents can use

AGENTS.md has become the standard project context file for coding agents: build commands, test commands, code style, testing frameworks, architectural decisions, the unwritten rules that live in a senior engineer's head and nowhere else.

The adoption numbers back this up. The file is stewarded by the Agentic AI Foundation under the Linux Foundation, and by mid-2026 it had shown up in more than 60,000 open-source projects. It's read natively by a wide range of agents: Codex, GitHub Copilot, Jules from Google, Devin, Factory, Gemini CLI, and VS Code, among others.

What makes it work isn't a clever feature. It's the absence of one. There's no required schema, no version number to track. Agents read what they can use and skip what they can't. That's what lets it work across a fragmented 2026 agent landscape without every tool maker having to sit down and agree on a spec first.

One notable holdout: Claude Code, as of August 2026, was still loading its own CLAUDE.md instead. That changed with version 2.1.277 on September 18, 2026, when Claude Code started reading AGENTS.md as a fallback whenever no CLAUDE.md was present. The clean fix for teams juggling both: put a single line at the top of CLAUDE.md that imports AGENTS.md (@AGENTS.md), so there's exactly one canonical file and nothing gets out of sync.

Size is the discipline that matters most here, and it's the one teams get wrong most often. This file gets sent with every single prompt. Every unnecessary line is diluting the signal the agent actually needs. The target: under 150 lines, and for smaller repos, 30 to 50 lines is plenty. Run every line through one test: would removing this cause the agent to make a mistake it wouldn't otherwise make? If the answer's no, cut it.

There's real evidence behind this discipline, not just intuition. A 2026 study across 138 real-world repositories found that LLM-generated context files actually lowered agent task success rates, while pushing inference cost up by more than 20%. Developer-written files, by contrast, delivered only a modest 4% improvement, and only when they were minimal and precise. The lesson isn't "write more." It's that density and intent beat completeness every time.

A workable structure covers: overview, build and test commands, code style, testing, security, and commit or PR rules. Leave out anything the agent can already infer, like standard directory layouts, and don't ship whatever an agent's init command auto-generates without the team actually reviewing it first. Treat that auto-generated draft as a starting point: strip what the agent already knows, add what only the team knows.

For monorepos, mirror the team's actual structure in the file's section structure. It keeps things legible once the project gets big enough that one flat list stops making sense.

And to avoid getting locked into one vendor's format: write AGENTS.md as the one source of truth, and have any tool-specific files (like CLAUDE.md) just import it. One file to maintain. Every agent benefits. Nothing gets lost if a tool eventually goes away.

Layer 2 (feature and task specs): the structural properties that make agent execution traceable and correctable

Project context tells an agent about the codebase in general. Feature specs tell it what to build right now, and this is where the "prose description" problem gets sharpest. A paragraph describing a feature gives an agent a target. It doesn't give the agent any way to check whether it hit it.

Two tools show what the fix looks like in practice.

A spec-driven development toolkit, released in September 2024 under an open-source license, had reached 111,000 stars by June 2026. It runs on a four-phase workflow: /speckit.specify, then /speckit.plan, then /speckit.tasks, then /speckit.implement. Each phase produces plain Markdown files that sit right in the repo, diffable and reviewable like any other source file. It's agent-agnostic across roughly 30 different tools, so switching which agent you're using doesn't invalidate the specs already written. The real structural payoff is the separation of the four phases: clarifying intent, analyzing constraints, specifying behavior, and implementing, each kept distinct so the agent can't collapse them into one ambiguous pass.

AWS Kiro launched internationally as a replacement for Q Developer on May 7, 2026. It's an IDE built on an open-source editor base, compatible with VS Code. One prompt can generate three artifacts at once through Quick Spec (which skips the approval gates), or walk through sequential approval steps for each artifact: requirements.md (user stories written in EARS notation, the format "WHEN [condition] THE SYSTEM SHALL [behavior]"), design.md (technical architecture), and tasks.md (implementation steps sequenced by dependency).

EARS notation is the real contribution here. It turns acceptance criteria into something machine-readable and formally testable, not a paragraph of prose that reads fine but can't actually be checked. Kiro's 2026 Requirements Analysis feature pushes this further, using formal logic and SMT solvers to catch contradictions in the requirements before any code gets generated. That's structure doing something prose simply can't: catching a logical conflict before it becomes a bug.

The tradeoff: Kiro's specs are static and don't update automatically as the implementation evolves. Teams already in the AWS ecosystem get the most value. Non-AWS teams take on more overhead for less benefit.

What Spec Kit and Kiro share is traceability. Every implementation step traces back to a specific requirement, so when something drifts, it's detectable instead of invisible.

The outcomes reported from early adopters back up the approach: spec-driven workflows have shown first-pass success rates 3 to 10 times higher than unstructured prompting on non-trivial tasks. Airbnb migrated 3,500 test files in six weeks, on a project originally estimated to take about a year and a half.

But "static" hides a catch: once an agent starts executing against a spec, the code starts to move and the spec doesn't." Once an agent starts executing against a spec, the code starts to move and the spec doesn't. Within hours, what's written in requirements.md may no longer describe what's actually in the codebase. That gap is exactly the problem the next section covers.

Structural case for living specifications and organizational memory

A spec written before a single line of code exists is a snapshot. Once agents start editing that codebase, the system starts changing in ways the original document doesn't capture. Any agent that reads the static spec next is reading the old contract, not the one currently in effect.

Augment Cosmos is a useful reference point for what a living spec looks like structurally. It's a cloud agent platform that launched in 2026. Its specs update automatically as implementation evolves: if an agent changes the shape of an API response, the spec reflects that change right away, so the next agent to touch the code is working from the current contract, not the original one. A Context Engine tracks semantic understanding across more than 400,000 files, plus an Organization Knowledge layer that carries architectural decisions across sessions. The tradeoff is scope: this kind of infrastructure is more than a solo developer on a single repo needs, and as a newer platform, it's still actively evolving.

OpenSpec takes a lighter approach, using delta markers to create something semi-living, open-source and agent-agnostic. It's a good fit for brownfield work, where changes are iterative and full living-spec infrastructure would be overkill.

The question every team should answer before picking a tool: is this spec something an agent reads once, at the start, or something an agent executes against continuously while it changes? That answer should come before the tool choice, not after.

A related, quieter form of drift is organizational memory. An agent that can't carry architectural decisions across sessions ends up re-deriving them from scratch each time. The spec document itself hasn't changed, but the agent's understanding has drifted anyway. That's still spec drift. It just doesn't appear in the diff.

Layer 3 (Agent Skills): reusable, portable spec-like artifacts for repeatable procedures

Agent Skills solve a different problem than either of the first two layers: portability. A Skill is a reusable capability, domain expertise or a team-specific workflow, that an agent can load on demand across any project, not just the one it was written for.

Structurally, a skill is simple: a folder containing a SKILL.md file with two required YAML fields (name and description) plus a Markdown body of instructions, and optionally scripts, templates, or reference files sitting alongside it.

The distinction from AGENTS.md is scope. AGENTS.md lives with a project. A skill travels with the agent. A commit-message skill, a database migration skill, a deployment-checklist skill: each one self-contained, each one version-controlled, each one usable on a completely different codebase tomorrow.

Skills started as an Anthropic project, released as an open standard in late 2025. Adoption spread fast: Claude Code, OpenAI Codex, VS Code, and more than 32 other tools support them, and companies including Atlassian, Figma, Canva, Stripe, Notion, and Zapier published skills right at launch.

The reason that marketplace could form so quickly comes back to the same structural choice AGENTS.md made: keep the schema minimal. Two required fields and a body of Markdown is simple enough to build in an afternoon. No protocol to negotiate, no runtime dependency to install. skills.sh, run by Vercel, is currently the most active registry, and installing a skill is a single command: npx skills add.

The pattern repeats: the same properties that make AGENTS.md useful (a light schema, human-readable text, version control) are what made Skills portable at scale. If the format had come with more complexity baked in, adoption likely would have splintered the same way project context files were splintered before AGENTS.md gave everyone a shared target.

DESIGN.md and the structural problem of visual identity in agent-generated UI code

If you ask an agent to build a frontend component, it has no built-in way to know the brand's colors, its type scale, its spacing rules, or how buttons are supposed to behave on hover. It guesses, usually from whatever CSS comments happen to be lying around, or it ignores brand consistency entirely and just picks something that looks fine.

DESIGN.md is built to close that gap. It pairs machine-readable design tokens, written in YAML, with human-readable explanation in Markdown prose. The agent doesn't just get a hex code. It gets the reasoning behind why that color exists.

The format comes from Google Labs, released as the open export and import format for Google Stitch, an AI-native design canvas that uses Gemini to turn natural language into UI. It's picked up around 14,600 stars.

The workflow: a designer exports a DESIGN.md from Stitch, a developer imports it into the codebase, and from there any agent working on the frontend uses it to keep generated components on-brand. An accompanying npm package handles validation, diffing, and exports the tokens into Tailwind (either v3 JSON or v4 CSS) or the W3C Design Token format.

It's still alpha software. The format is expected to keep changing, and breaking changes are likely. It's worth trying out, but not yet something to build a production pipeline around.

The broader lesson holds regardless of what happens to DESIGN.md specifically: the gap it's trying to fill is the same gap AGENTS.md fills for build commands. Without an explicit, structured source of truth, an agent doesn't leave a blank space where the answer should go. It fills that space with a guess, and the guess looks confident whether or not it's right.

The structural properties shared across effective spec formats

Lay every format covered so far side by side (AGENTS.md, Spec Kit, Kiro, Cosmos, OpenSpec, Skills, DESIGN.md) and six properties appear again and again.

Explicit acceptance criteria. An agent needs something to check its work against, not just a description of what "done" is supposed to feel like. EARS notation's WHEN/SHALL structure, Spec Kit's four-phase progression, and the litmus-test line-pruning discipline in AGENTS.md are all doing the same job from different angles: turning "the agent should probably do this" into something checkable.

Separation of concerns by layer. Mixing project context, feature specs, and reusable skills into a single document forces the agent to guess at scope, and that guess is a fresh entry point for drift. The three-layer model exists specifically to close that door.

Minimal schema, maximum signal. Every format that's actually spread across the 2026 agent landscape is Markdown-first, human-readable, and version-controlled. Add complexity to the format and adoption fragments, because now every tool maker has to agree on how to parse it.

Traceability. Every implementation step should trace back to a specific requirement. That's the difference between drift you can catch and drift you can't.

Machine-readable ground truth for anything domain-specific. EARS notation for requirements, YAML tokens in DESIGN.md, path-based scoping in tool-specific rule files: wherever an agent has to make a call that depends on facts only the team actually knows, those facts need a structured, queryable form, not a paragraph an agent has to interpret.

Living or version-controlled currency. A spec that can't reflect what the implementation actually looks like right now becomes a liability the moment execution starts. Teams need either living-spec infrastructure like Cosmos or a real discipline around keeping static specs updated by hand.

One more thread ties all of this together: agent prompts function as operational policy, not step-by-step instructions. The formats that work well take that policy and put it in a version-controlled file anyone can read and review, instead of burying it inside a system prompt that quietly drifts and that nobody's checking.

When spec-driven development is the right structural choice

None of this is free. Structured specs take time to write, and that time only pays off when the task actually needs the structure.

Spec-driven development earns its keep on cross-service features, migrations, regulated work, and anything where a mistake is expensive to catch late: the kind of task where an hour spent up front genuinely does save days of cleanup after. It's a much harder sell for a quick prototype, a one-off script, or exploratory work where the requirements are still moving and writing a formal spec would mean documenting a target that's about to change anyway.

The judgment call comes down to a fairly simple question: is the cost of the agent guessing wrong higher than the cost of writing the spec? For small, reversible tasks, probably not. For anything that touches multiple services, involves compliance, or would be genuinely painful to unwind, the spec almost always wins. Picking the right layer, and the right amount of structure within it, is what turns an agent from a fast typist into something closer to what Karpathy's "agentic engineering" actually promises: a system doing real work, with a human checking the output against a target that was clear from the start.