Introduction to AGENTS.md
What is AGENTS.md?
AGENTS.md is a Markdown file used to give coding agents instructions about your project.
Think of it as a README written specifically for AI coding agents.
A README.md helps a developer understand the project.
An AGENTS.md helps a coding agent understand how it should work inside the project.
README.md
→ Information for humans
AGENTS.md
→ Instructions for coding agents
Why do we need it?
Imagine asking a coding agent:
Add an API endpoint for creating users.
The agent can inspect your code and figure out a lot on its own.
But it may not automatically know that your project expects:
- TypeScript strict mode.
- Zod for request validation.
- Business logic inside service classes.
- Vitest for unit tests.
pnpm testbefore completing a task.- Generated files to never be modified manually.
Without project instructions, the agent has to infer these rules from the repository.
AGENTS.md lets you state them explicitly.
A Simple AGENTS.md
# Project Guidelines
## Development
- Use TypeScript for all new source files.
- Follow the existing folder structure.
- Use `pnpm` for package management.
- Do not modify generated files.
## Testing
- Add tests for new business logic.
- Run `pnpm test` after modifying application code.
- Do not remove failing tests just to make the test suite pass.
Now an agent working inside the repository has clear project-specific instructions.
What Can AGENTS.md Tell an Agent?
Common instructions include:
Build & Development
- Install dependencies using `pnpm install`.
- Start development with `pnpm dev`.
Testing
- Run `pnpm test` after modifying source code.
- Add unit tests for new business logic.
Code Style
- Use TypeScript strict mode.
- Prefer named exports.
- Do not use `any` unless absolutely necessary.
Architecture
- Keep business logic inside the service layer.
- Controllers should only handle HTTP concerns.
Repository Rules
- Do not modify files inside `/generated`.
- Do not commit `.env` files.
There is no required schema for AGENTS.md. It is regular Markdown, so its structure should primarily optimize for clear instructions.
AGENTS.md Is Not Magic
Adding an AGENTS.md does not automatically make an agent understand everything about your application.
It should not replace:
- Good architecture.
- Useful documentation.
- Tests.
- Type checking.
- Linters.
- Code review.
- CI/CD validation.
Instead, it gives the coding agent additional context and working instructions.
Think of it as:
Repository
+
Code
+
Tests
+
Documentation
+
AGENTS.md
↓
Better context for the coding agent
Don't Put Everything in AGENTS.md
More instructions do not automatically produce better results.
For example, this is usually unnecessary:
React is a JavaScript library for building user interfaces.
Components allow applications to split their UI into reusable pieces.
TypeScript is a typed programming language...
The agent likely already understands React and TypeScript.
Instead, tell it what is specific to your project:
- Use server components by default.
- Add `"use client"` only when client-side interactivity is required.
- Keep shared UI components inside `src/components/ui`.
That information actually changes how the agent should work in your repository.
Good Instructions vs Bad Instructions
❌ Bad
Write good code.
Follow best practices.
Make sure everything works.
These instructions are vague.
What does "good code" mean for this project?
What should the agent run to make sure everything works?
✅ Better
- Use TypeScript for all new source files.
- Run `pnpm lint` after modifying application code.
- Run `pnpm test` before completing the task.
- Add unit tests when introducing new business logic.
These instructions are specific and actionable.
Where Does AGENTS.md Live?
The simplest setup places it at the repository root:
my-project/
├── AGENTS.md
├── package.json
├── src/
├── tests/
└── README.md
Larger repositories can also use additional AGENTS.md files inside subdirectories.
my-project/
├── AGENTS.md
│
├── frontend/
│ └── AGENTS.md
│
└── backend/
└── AGENTS.md
This allows different parts of the repository to provide more specific instructions.
We'll explore this properly in Scope & Nested AGENTS.md.
AGENTS.md vs README.md
A useful rule of thumb:
| README.md | AGENTS.md |
|---|---|
| Primarily for humans | Primarily for coding agents |
| Explains the project | Explains how the agent should work |
| Setup documentation | Agent-specific commands and workflows |
| Product/project context | Coding and repository instructions |
There can be some overlap.
You don't need to duplicate your entire README inside AGENTS.md.
Key Takeaway
Think of AGENTS.md as the project's working guide for coding agents.
A useful AGENTS.md answers questions such as:
How should I work in this repository?
What project-specific conventions should I follow?
What should I avoid changing?
What commands should I run?
How should I verify my work?
The goal isn't to tell the agent everything.
The goal is to give it the project-specific instructions it needs to work correctly.
Up Next
How AGENTS.md Works
Next we'll look at how agents discover instructions, how scope works, and what happens when multiple AGENTS.md files exist in the same repository.