What is AGENTS.md? The file AI coding tools read before they touch your code

AGENTS.md is a Markdown file at the root of a repository, written for AI coding agents instead of humans. When a tool like Cursor, Codex, or Claude Code starts working in your project, it reads the file as context before making changes. Think of it as the onboarding document for a contributor who is very fast, very literal, and completely new to the project every single session.

That last part is the point. Agents don’t remember your project between sessions. Without a brief, every session starts with the agent guessing your conventions from whatever files it happens to open, and guesses produce generic code. With a brief, the conventions are simply known.

What goes in it

The best briefs answer the questions an agent would otherwise have to guess. From shipping one with every Lexington theme, the sections that earn their place:

• Tech stack, with versions. Not “Astro and Tailwind” but which major versions, and where each is configured. Version-specific APIs are where agents most often reach for outdated patterns.
• Folder map. What lives where, and especially the things that are non-obvious: where design tokens live, which folder is generated, what shouldn’t be touched.
• Content and data conventions. If you have content collections, list each one with its required frontmatter and a file to copy as a starting template. Schemas are the easiest thing for an agent to violate confidently.
• Routing and layout conventions. How pages, dynamic routes, and layouts connect, and which layout new pages should use.
• Gotchas. The short list of things that trip tools up in this specific repo. Every project has three or four. Write them down once instead of correcting them forever.

Just as important is what to leave out: anything the agent can trivially read from the code itself (exact function signatures, full dependency lists), and anything aspirational. The brief describes the project as it is. An agent reading wishes will build on wishes.

A skeleton to start from

# Project brief

## Stack
Astro 5, Tailwind CSS 4, TypeScript. Config in astro.config.mjs.

## Structure
- src/pages — file-based routes
- src/components — UI, grouped by domain
- src/content — content collections (see below)
- src/styles/colors.css — all color tokens; never hardcode colors

## Content collections
- posts: title, description, pubDate, author. Copy an existing post.

## Conventions
- Import alias: @/ for src/
- Use existing components before writing new ones
- No new dependencies without asking

## Gotchas
- Files starting with _ in src/content/posts are drafts, excluded from builds

Short is fine. A brief that fits on one screen and is true beats ten sections of boilerplate.

How tools pick it up

Codex and Cursor read AGENTS.md from the project root automatically; a growing list of tools follows the same convention, and for anything that doesn’t, the file is plain Markdown you can point the tool at or paste into its instructions. It also composes with the other context formats: scoped rules for conventions that apply to specific folders, and skills for on-demand capabilities. The brief is the layer they all build on — the one document that says what this project is.

Two habits make it work long-term. First, update it in the same diff as any structural change (“rename the collection, and update AGENTS.md to match”). Second, audit it occasionally by asking the agent to verify each claim against the codebase. A stale brief is worse than none: the agent trusts it.

Every Lexington theme ships with an AGENTS.md written from that theme’s actual code, alongside a design skill and scoped rules. I’ve written about why, and the full method for writing your own is in Making Your Codebase AI-Ready.