AGENTS.md is a plain Markdown file placed at the root of a repository to give AI coding agents standing instructions about how a project works, what commands to run, and what coding conventions to follow. Unlike a README written for humans, AGENTS.md speaks directly to machines, telling agents like Cursor, Cline, Continue.dev, Aider, and others exactly how to avoid repeating the same mistakes session after session.

Why Are Developers Creating These Files?

Every AI coding agent faces the same fundamental problem: it has no memory between sessions. Close your terminal, and everything you taught the agent about your project evaporates. Open a fresh session, and you're back to explaining that your team uses pnpm instead of npm, or that a particular legacy folder intentionally uses callbacks for a reason.

Without a persistent instruction file, agents tend to run the wrong setup commands, adopt whatever coding style dominates their training data instead of yours, ignore project conventions they have no way of knowing about, and reach for the wrong package manager or runtime version. The most dangerous behavior is when agents confidently invent APIs, file paths, or patterns that don't actually exist in your codebase. Since AI models repeat statistically common patterns, if your project intentionally diverges from the norm, the agent will "correct" you toward the average unless something explicitly tells it not to.

AGENTS.md solves this by living in version control. The guidance survives across sessions and travels with the repository. Every teammate's agent reads the same file and behaves the same way. Developers who add one report noticeably fewer hallucinations and less back-and-forth, often inside the very first session.

Which AI Coding Tools Actually Support AGENTS.md?

Support has grown fast, but it isn't universal, and adoption varies significantly across the ecosystem. Here's where things actually stand in mid-2026:

• OpenAI Codex: The tool that popularized the format and reads AGENTS.md natively, even supporting a hierarchical override system for local-only tweaks.
• Cursor: Added native root-level AGENTS.md support in 2026 and reads it directly without requiring any configuration.
• Devin Desktop: Cognition rebranded Windsurf to Devin Desktop on June 2, 2026, and it reads AGENTS.md natively at the repo root alongside its own.devin/rules/ directory.
• Cline: Also added native support in the mid-2026 wave of tool updates.
• Gemini CLI, Roo Code, Kilo Code, Continue.dev, Aider, Amp, and Zed: All read AGENTS.md, with several treating it as their primary instruction file.
• Claude Code: This is the notable exception; Claude Code reads CLAUDE.md instead of AGENTS.md, despite a heavily upvoted feature request for native AGENTS.md support.

Because behavior varies by tool and version, developers should check their agent's current documentation rather than assuming support. The good news is that AGENTS.md is plain Markdown, so even a tool that doesn't officially parse it can still be pointed at it.

How to Create an Effective AGENTS.md File

• Start with a description: Begin with a one-line description of what the project is, so the agent understands the context immediately.
• List exact commands: Include your precise setup, build, test, and lint commands so agents don't guess or use defaults that break your workflow.
• Document non-obvious patterns: Note anything counterintuitive that an outsider would "fix" by mistake, such as intentional use of callbacks or specific architectural choices.
• Set hard constraints: Add rules about what agents should never do, such as committing secrets, touching certain folders, or using specific package managers.
• Keep it lean: Write only the guidance that agents can't infer from the code itself; a recent academic study from ETH Zurich found that AI-generated context files often made things worse by adding unnecessary steps and cost, while human-written ones helped modestly.

For a TypeScript web app, a complete AGENTS.md might include sections on setup commands like "pnpm install" (never npm or yarn), coding standards such as TypeScript strict mode with no exceptions, and project structure guidelines that specify where business logic and route handlers belong.

Where Should AGENTS.md Live in Your Repository?

The default is straightforward: place one AGENTS.md at the root of your repository. For a single-package project, that's all you need. Monorepos are where the system becomes more powerful. You can place additional AGENTS.md files inside individual packages, and agents automatically read the nearest one in the directory tree. The closest file to whatever code you're editing wins, so the root file sets sensible defaults while each package overrides them with its own local rules.

This approach scales surprisingly well. OpenAI's main repository reportedly carries 88 separate AGENTS.md files, with the root file defining global conventions, module-level files encoding local invariants, and explicit chat prompts still overriding everything so developers always have the final say.

Creating an AGENTS.md requires nothing to install. Developers simply create the file, write Markdown, and commit it to version control. There's no schema, no YAML, and no special syntax to learn. The agent reads the text and treats it as standing instructions for the repository.

As AI coding agents become more integrated into development workflows, the ability to give them persistent, project-specific guidance without reinventing the wheel each session is becoming a practical necessity. AGENTS.md represents a simple but powerful shift in how teams can work alongside AI tools, turning what was once a memory problem into a solved one.