Beyond Vibe Coding: The Three-Layer Spec Stack Every AI Project Needs

There's a reason experienced teams building with AI assistants eventually arrive at the same frustration: the output is good, but it isn't theirs. Claude generates a component that works but uses the wrong radius. Cursor writes a function that's correct but violates the project's naming conventions. The AI isn't broken — it just doesn't know enough about the specific project it's working on.

The solution the industry has converged on is structured specification files. Not longer prompts. Not better system messages. Persistent, version-controlled documents that live in the project root and travel with the codebase everywhere it goes.

The pattern that's emerged looks like this:

project/
├── AGENTS.md      ← who the AI is, and how it behaves
├── SKILL.md       ← what the AI knows how to do
└── DESIGN.md      ← how everything should look

Three files. Three distinct concerns. One coherent AI-assisted workflow.

Layer 1 — AGENTS.md: Identity and Behavior

AGENTS.md defines the AI's role within a specific project. It's not a general system prompt — it's a project-scoped document that tells the AI what kind of collaborator it's supposed to be here, in this codebase, for this team.

A well-written AGENTS.md covers:

• Role and scope — what the AI is responsible for and what it should leave alone
• Tone and communication style — how verbose, how technical, how opinionated
• Project boundaries — what patterns to follow, what anti-patterns to avoid
• Non-goals — things the AI should explicitly not do, even if asked

Without AGENTS.md, the AI calibrates its persona and scope from the conversation context alone. That works for one session. Across a team, across weeks, across different contributors — it produces wildly inconsistent behavior.

Layer 2 — SKILL.md: Procedural Knowledge

SKILL.md defines executable knowledge — the specific things the AI knows how to do in this project context. Think of it as documented workflows, not general capability.

Where AGENTS.md defines who the AI is, SKILL.md defines what it can execute:

• Step-by-step procedures for common tasks (creating a new page, writing a migration, seeding test data)
• Domain-specific knowledge the AI can't infer from the codebase alone
• Trigger conditions — when each skill should be invoked and what inputs it expects
• Verification steps — how the AI checks its own output

A project using Claude Code, for example, can have multiple skills in .claude/skills/ — each one a focused, reusable unit of procedural knowledge that the AI loads on demand rather than carrying in context permanently.

Layer 3 — DESIGN.md: Visual Specification

This is where visual identity becomes machine-readable. DESIGN.md doesn't describe how a design should feel. It specifies how it should be built — with precise values the AI can apply directly to generated code.

A production-ready DESIGN.md covers:

• Color palette with exact hex values and named semantic roles
• Typography — families, weights, sizes, and line heights as a structured table
• Component specs — buttons, cards, inputs with actual CSS values, not descriptions
• Spacing and radius systems — the grid and rounding rules that give a UI its character
• Elevation — shadow values by level, ready to apply as box-shadow CSS
• Do's and Don'ts — explicit rules that AI agents can follow precisely
• Agent Prompt Guide — pre-written starting prompts for common components

The last section is the most underrated. Rather than hoping Claude infers the correct border radius from your color palette, you give it: "When generating a primary button, use these exact values and start from this prompt." The AI's job shifts from guessing to applying.

Why Three Layers, Not One

The most common question is why this needs to be three separate files. Why not one large context document?

The answer is scope and reusability.

AGENTS.md is project-specific but persona-generic. The same role definition might apply across several projects. SKILL.md entries are reusable procedures — a "create new pack" skill works the same way regardless of what the UI looks like. DESIGN.md is visually specific but behaviorally neutral.

When these concerns are separated, you can:

• Update the visual system without touching the behavioral rules
• Reuse skills across projects with different design languages
• Onboard a new AI tool to the project by pointing it at the relevant layer
• Version each layer independently — a typography update doesn't require a behavior review

Mixing everything into one document means every change requires reviewing everything. Separation means targeted updates and predictable outcomes.

What This Looks Like in Practice

A product team using this stack operates roughly like this:

A developer opens Cursor and starts a new feature. Cursor reads AGENTS.md and understands the project conventions. When the developer asks for a new settings screen, Cursor references DESIGN.md for the component specs and SKILL.md for the project's page-creation procedure. The output is on-brand, follows the codebase patterns, and needs minimal rework.

When the design language evolves — new brand color, updated radius system — the team updates DESIGN.md. That single file change propagates to every subsequent AI generation across every tool in the workflow.

That's the compounding effect. Each layer, maintained well, makes every other layer more effective.

Getting the DESIGN.md Layer Right

Of the three files, DESIGN.md is the one that benefits most from starting with a pre-built foundation. Writing AGENTS.md and SKILL.md requires project-specific knowledge that only you have. But DESIGN.md — at least its structural skeleton — can start from an established design system and be adapted to your brand.

Design.md Store has a library of DESIGN.md files built from production design systems across a range of industries and visual directions. Each file is formatted to the open DESIGN.md specification and ready to use as the third layer of your project's spec stack — with Cursor, Claude Code, v0, or any other AI tool that reads document context.

Start with the file closest to your target aesthetic. Adapt the values. Wire it into your project root. Your design layer is done.

The other two are up to you.