What Is AGENTS.md?

AGENTS.md is a plain-text instruction file stored in a repository that explains how AI coding agents should work in that project. Tools like Cursor, Windsurf, and other AI-assisted editors read AGENTS.md to understand coding style, testing requirements, and project-specific rules.

The file sits alongside code and documentation, so it travels with the repository and can be versioned, reviewed, and rolled back like any other configuration.

General-purpose models do not know your local conventions by default. By reading AGENTS.md on startup or when analyzing a project, AI coding assistants can align their suggestions with your preferred patterns and safety constraints.

This reduces repeated prompt boilerplate and makes behavior more predictable. It also gives teams a concrete artifact they can inspect when they want to know "what have we told the agent to do here?"

A simple AGENTS.md file defines coding conventions, testing expectations, and workflows in direct, imperative language. The example below is intentionally short but shows the basic structure.

# AGENTS.md

## Repository context
- This is a TypeScript monorepo using Next.js and Prisma.
- Treat instruction files as production configuration.

## Coding conventions
- Prefer explicit types in public interfaces.
- Keep business logic out of React components.
- Write idempotent database migrations.

## Testing expectations
- Add or update tests for any non-trivial behavior change.
- Keep unit tests fast and deterministic.
- Prefer integration tests around critical workflows.

## Workflow
- Explain trade-offs when proposing significant design changes.
- Call out security or data-handling implications explicitly.

Teams often extend this template with language about observability, performance budgets, or domain-specific rules. The key is to keep instructions concrete and stable rather than mixing them with transient project notes.

For guidance on managing AGENTS.md across many repositories, see How to Manage AGENTS.md Across Repositories.

• Keep instructions concise and concrete rather than aspirational.
• Use sections for context, coding conventions, testing, and workflows.
• Review AGENTS.md changes like code, with clear ownership and approval.
• Link to authoritative docs instead of duplicating long explanations.
• Document which tools read AGENTS.md in your environment.

Common issues include treating AGENTS.md as a chat-style note to a single tool, embedding time-sensitive information that quickly goes stale, and copy-pasting the same file into many repos without a plan to update it later.

Teams also sometimes overload AGENTS.md with generic best practices instead of focusing on the specifics that change agent behavior in that repository. A smaller, well-governed file is easier for both humans and agents to use.