What is AGENTS.md?

AGENTS.md is a Markdown file designed to provide AI coding agents with the context and instructions they need to work effectively on a software project.

Why use AGENTS.md?

A README usually explains the project to developers. An AGENTS.md file can contain information specifically useful to an AI agent working inside the codebase.

Typical information includes:

• Development and build commands
• Testing instructions
• Project architecture
• Coding conventions
• Repository structure
• Pull request guidelines

AGENTS.md example

# AGENTS.md

## Project Overview

This repository contains a web application built with
TypeScript and React.

## Development

Install dependencies:

npm install

Start development:

npm run dev

## Testing

Run tests before submitting changes:

npm test

## Code Style

- Use TypeScript strict mode
- Prefer functional components
- Keep functions small and focused
- Follow existing code conventions

## Project Structure

/src
  /components
  /services
  /utils

/tests

## Guidelines

Before changing architecture, inspect the existing
implementation and preserve established patterns.

AGENTS.md vs README.md

The two files have different audiences.

• README.md primarily documents the project for humans.
• AGENTS.md provides context and working instructions to coding agents.

They can therefore complement each other rather than replace one another.

AGENTS.md and project goals

Agent instructions explain how an agent should work inside a repository. Project goals describe what the project is trying to achieve.

A project can therefore keep both:

project/
├── README.md
├── PROJECT-GOALS.md
├── AGENTS.md
└── src/