The Two Files Every AI-Ready Project Needs

Every AI coding tool now reads a configuration file from your project. Claude Code looks for CLAUDE.md. Codex CLI reads AGENTS.md. Gemini CLI checks for GEMINI.md. Cursor has .cursorrules. GitHub Copilot uses copilot-instructions.md.

They all solve the same problem: AI models have no persistent memory. Every session starts blank. Without a configuration file, you repeat the same instructions every time. Your tech stack, coding conventions, project structure, deployment rules. These files give your AI assistant the context it needs to produce useful output from the first prompt.

But all of those files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, copilot-instructions.md) do the same job. They’re tool-specific flavours of one concept: project instructions for coding agents. Having five names for one thing is confusing, and most projects have none of them.

Here’s what actually matters. There are two files. They solve two distinct problems. Together, they give any AI agent everything it needs to work on your project.

File 1: AGENTS.md — How to build it

AGENTS.md tells AI coding agents how your project works. It’s the closest thing to a universal standard. Originally created for OpenAI’s Codex CLI, it’s now governed by the Linux Foundation and adopted by over 60,000 open-source projects.¹ Claude Code, Cursor, Codex, Continue.dev, Aider, and OpenHands all read it.

The other filenames (CLAUDE.md, GEMINI.md, .cursorrules, copilot-instructions.md) exist because each tool wanted its own format. But the content is identical: project context for a coding agent. AGENTS.md has emerged as the cross-tool standard. Claude Code reads it as a fallback when no CLAUDE.md exists. Cursor reads it alongside .cursorrules. If you’re only going to maintain one file, make it AGENTS.md.

A good AGENTS.md covers:

• Tech stack. Languages, frameworks, versions. “This is an Astro 4 site with Tailwind CSS v4 and TypeScript.”
• Project structure. Where things live. “Articles are in src/content/articles/. Components in src/components/. Layouts in src/layouts/.”
• Coding conventions. How you write code. “Use named exports. No default exports. Prefer const over let.”
• Testing. How to run tests, what framework, what coverage expectations.
• Deployment. How code gets live. “Push to main triggers Vercel deployment. Preview deploys on PR branches.”
• Don’ts. What to avoid. “Never modify the database schema without a migration. Never commit .env files.”

The key insight: AGENTS.md isn’t documentation for humans. It’s documentation for machines. You can be blunt, repetitive, and explicit in ways that would bore a human reader but make an AI agent significantly more reliable.

Here’s a stripped-down example:

# AGENTS.md

## Stack
- Astro 4, Tailwind CSS v4, TypeScript
- Content: Markdown with YAML frontmatter
- Hosting: Vercel (auto-deploy on push to main)

## Structure
- src/content/articles/ — Blog posts (markdown)
- src/components/ — Astro components
- src/layouts/ — Page layouts
- public/images/articles/ — Article header images (1536x1024 PNG)

## Rules
- British English spelling throughout
- No default exports
- All components must be .astro files
- Every article needs: title, date, description, tags, author, coverImage, draft
- Run `npm run build` before committing — zero errors tolerated

## Don't
- Never modify tailwind.config.ts colours without updating DESIGN.md
- Never add dependencies without checking bundle size impact
- Never commit API keys or tokens

Thirty minutes of work. Every AI agent that touches your project reads it automatically.

File 2: DESIGN.md — How it should look

DESIGN.md solves a completely different problem. Introduced by Google Stitch, it captures your visual design system in a format AI agents can read.²

This is where the real gap exists. AGENTS.md has been around since 2025 and has broad adoption. DESIGN.md is new, barely a few weeks old as a formal concept, and most projects don’t have one yet.

Without a DESIGN.md, every time you ask an AI to build a component, you describe your brand from scratch. “Use a warm cream background, amber accents, Cormorant Garamond for headings, Outfit for body text, 11px uppercase mono labels…” And the next prompt, you do it again. And the AI still gets the shadow wrong.

A DESIGN.md captures all of it once. The VoltAgent community has already published 55 DESIGN.md files extracted from real websites including Stripe, Vercel, Linear, Notion, Supabase, and Figma.³ Each file follows a nine-section format:

1. Visual theme and atmosphere. Mood, density, design philosophy.
2. Colour palette and roles. Every colour with its hex and functional purpose.
3. Typography rules. Font families, the full type hierarchy table.
4. Component styles. Buttons, cards, inputs, navigation with hover and active states.
5. Layout principles. Spacing scale, grid system, whitespace philosophy.
6. Depth and elevation. Shadow system, surface hierarchy.
7. Do’s and don’ts. Design guardrails and anti-patterns.
8. Responsive behaviour. Breakpoints, touch targets, collapsing strategy.
9. Agent prompt guide. Quick colour reference and ready-to-use prompts.

The format is plain markdown. No Figma exports, no JSON schemas, no special tooling. Drop it in your project root and any AI coding tool can generate UI that matches your existing design, first time, every time.

Why two files, not one?

You could put everything in AGENTS.md. Some teams do. But there are practical reasons to separate them.

Different problems. AGENTS.md answers “how does this project work?” DESIGN.md answers “how should this project look?” Combining them creates a massive file where an agent parsing build instructions also wades through typography tables and shadow definitions.

Different change rates. Your tech stack and conventions change slowly. Your design system evolves as the product matures. Separating them means you update one without touching the other.

Different owners. In a team, your tech lead owns AGENTS.md. Your designer owns DESIGN.md. Clean separation.

Token efficiency. AI models have context limits. Research suggests frontier LLMs reliably follow around 150-200 instructions.⁴ Two focused files load less total context than one massive file, and each loads only when relevant.

The practical payoff

Before these files, every AI interaction started with explanation. “This project uses Astro with Tailwind. The heading font is Cormorant Garamond. Don’t push directly to main. Use British English.”

After these files, the AI knows all of it before you type your first prompt. The difference compounds. Every session is faster. Every output is more consistent. Every new team member’s AI assistant works the same way from day one.

We added both files to the Squared Lemons website this week. The immediate result:

• New components match existing design without manual correction
• FAQ accordions render with the right style automatically
• No agent ever uses American English spellings
• No agent pushes directly to main
• Every article gets the right frontmatter structure

Total investment: about three hours across both files. The return is permanent.

But what about CLAUDE.md, GEMINI.md, .cursorrules…?

They’re all the same thing as AGENTS.md with different filenames. If your team uses a single tool exclusively, use that tool’s native format. If you use multiple tools (which most teams now do), maintain AGENTS.md as your universal file. Every major tool either reads it natively or falls back to it.

DeployHQ published a comprehensive comparison of every AI config file format.⁴ The conclusion is clear: the content is identical across formats. The only differences are filename and discovery hierarchy. AGENTS.md has the broadest support.

How to start

If you do nothing else today, create an AGENTS.md. It takes 30 minutes and every major AI coding tool reads it. Put it in your project root, commit it, and every AI session from that point forward has the context it needs.

Then, next time an AI agent builds a component and gets the styling wrong, write a DESIGN.md. Extract it from your existing site. You’ll only need to do it once.

Two markdown files. One afternoon. A permanent improvement to every AI interaction with your codebase.

This is also part of why a first version can be stood up quickly now, and part of what I mean by handing something over so that another developer can pick it up cold. Both of those sit under getting it built.

---

Footnotes

1. AGENTS.md Standard, Linux Foundation. https://agents.md/ ↩

2. Google Stitch, “DESIGN.md Overview”. https://stitch.withgoogle.com/docs/design-md/overview/ ↩

3. VoltAgent, “Awesome DESIGN.md” (2026). https://github.com/VoltAgent/awesome-design-md ↩

4. DeployHQ, “CLAUDE.md, AGENTS.md, and Every AI Config File Explained” (March 2026). https://www.deployhq.com/blog/ai-coding-config-files-guide ↩ ↩²