What Is AGENTS.md File for AI Coding Agents

A new developer joins your team, opens the repository, and spends two days figuring out how the build system works, which tests to run, and where the deployment scripts live. Now imagine an AI coding agent doing the same thing, except it asks you the same questions every single session.

AGENTS.md fixes this. It is a single file in your repository root that tells any AI coding agent how your project works, what conventions to follow, and what pitfalls to avoid. It is becoming a key part of AI-driven development.

What Is AGENTS.md Used For

AGENTS.md is a repo-local instruction file that provides project-specific context to AI coding agents. When an agent opens your repository, it reads this file first to understand the project's structure, build process, testing conventions, coding standards, and any other rules that a new contributor would need to know.

Think of it as the onboarding document you wish every project had, except written specifically for AI agents rather than humans. It sits in your repository root, gets version-controlled alongside your code, and updates as your project evolves.

"AGENTS.md is the README your AI agent actually reads."

Why a Dedicated File Matters

Without AGENTS.md, every conversation with an AI coding agent starts from scratch. The agent has no idea that your project uses a monorepo structure, that tests must pass before commits, or that the database migration tool has a specific flag order. You end up repeating the same instructions across dozens of sessions.

AGENTS.md solves the cold-start problem. The agent reads it once at the beginning of each session and immediately has the context it needs. Every team member benefits because the instructions are consistent, and new agents or tools that support the format work instantly without custom configuration.

AGENTS.md vs CLAUDE.md vs .cursorrules

Several AI coding tools have introduced their own project instruction files. The formats overlap but differ in scope, portability, and community adoption.

The key difference is portability. CLAUDE.md works great if your entire team uses Claude Code. The .cursorrules file works great if everyone uses Cursor. AGENTS.md aims to work across all AI coding tools, making it the safer long-term choice for teams that use multiple tools or expect to switch tools in the future.

Many teams maintain both. They keep a CLAUDE.md with Anthropic-specific features and an AGENTS.md with universal project instructions. When a tool supports both, the tool-specific file takes priority for its features while AGENTS.md provides the baseline.

How to Write an AGENTS.md File for Your Repo

Start with the Build and Test Commands

The most valuable information for any agent is how to build and test the project. Put this at the top of your file. Include the exact commands, any required environment variables, and common flags.

# Build

npm run build

# Test

npm test                    # run all tests
npm test -- --watch         # run in watch mode
npm run test:integration    # integration tests (requires DATABASE_URL)

# Lint

npm run lint
npm run lint:fix            # auto-fix lint issues

Be specific about prerequisites. If the integration tests require a running database, say so. If the build needs a particular Node version, include that. The agent cannot guess what your CI environment looks like.

Document Your Project Structure

Give the agent a map of the codebase. You do not need to list every file, but highlight the key directories and explain what lives where.

# Project Structure

src/api/         - REST API routes and controllers
src/services/    - Business logic layer
src/models/      - Database models (Prisma)
src/utils/       - Shared utility functions
tests/unit/      - Unit tests (mirror src/ structure)
tests/e2e/       - End-to-end tests (Playwright)
scripts/         - Deployment and maintenance scripts

Spell Out Your Coding Conventions

AI agents follow patterns they see in training data, which may not match your project's conventions. Tell the agent explicitly what patterns to use. Without this, you risk agent drift as the agent invents its own conventions.

# Conventions

- Use named exports, not default exports
- Error handling: throw custom error classes from src/errors/
- Database queries go in the service layer, never in controllers
- All new endpoints need integration tests
- Commit messages follow Conventional Commits format

List What to Avoid

Negative instructions are just as important as positive ones. Tell the agent what not to do based on mistakes you have seen before. This prevents the kind of polished but flawed output teams call workslop.

# Do Not

- Do not add new dependencies without discussing first
- Do not modify the database schema without a migration file
- Do not use console.log for error handling, use the logger from src/utils/logger
- Do not commit .env files or any credentials

AGENTS.md Best Practices for Teams

Keep It Under 500 Lines

A long AGENTS.md defeats its purpose. Every line consumes tokens in the agent's context window. Focus on information the agent cannot easily discover by reading the code itself. Build commands, conventions, and gotchas belong in AGENTS.md. Detailed API documentation does not.

Use Directory-Scoped Files

For monorepos or large projects, place additional AGENTS.md files in subdirectories. When the agent works in a specific package or module, it reads both the root file and the local one. The root file covers project-wide rules. The subdirectory file covers package-specific details.

repo/
  AGENTS.md                  # project-wide instructions
  packages/
    api/
      AGENTS.md              # API-specific conventions
    web/
      AGENTS.md              # frontend-specific conventions

Review It Like Code

AGENTS.md should go through the same review process as any other code change. When someone updates a build command or changes a convention, the AGENTS.md update should be part of the same pull request. Stale instructions are worse than no instructions because the agent will confidently follow outdated procedures. This adds to your team's verification debt.

Test It with a Fresh Session

The best way to validate your AGENTS.md is to start a fresh agent session and ask it to perform a common task. If the agent asks clarifying questions that your file should have answered, update the file. If it makes mistakes that your conventions should have prevented, add those conventions.

"The quality of your AGENTS.md is measured by how few follow-up questions the agent needs to ask."

Include Troubleshooting Tips

Add a section for common problems and their solutions. The agent will encounter the same issues that trip up human developers. If the build fails because of a stale cache, document the fix. If tests flake on a specific platform, document the workaround.

When AGENTS.md Is Not Enough

AGENTS.md handles project-wide context well, but it does not replace other instruction mechanisms. For complex, multi-step procedures like deployment workflows, use dedicated skill files. For tool-specific features like custom slash commands or permission settings, use the tool's native configuration. You also need proper security practices to avoid exposing secrets. AGENTS.md is the foundation layer. It gives every agent a working understanding of your project. Everything else builds on top of it.

Conclusion

AGENTS.md is a repo-local markdown file that tells AI coding agents how your project works, what conventions to follow, and what mistakes to avoid. It is emerging as a cross-tool standard that works across different AI coding environments, unlike tool-specific alternatives like CLAUDE.md or .cursorrules. Writing a good AGENTS.md means starting with build and test commands, documenting project structure and conventions, listing what to avoid, and keeping the file concise enough to fit in a context window without wasting tokens. Using progressive disclosure principles helps here. For teams, it means treating AGENTS.md like code with proper reviews, using directory-scoped files for large projects, and testing it with fresh agent sessions. As AI coding agents become standard tools on every development team, AGENTS.md will be the file that makes them productive from the first session.