AGENTS.md: give your coding agent permanent instructions

📺 Watch the video on Instagram

Every time you open a new chat with your agent, it starts from scratch. It doesn't know which project it's in, what stack you use or what your team's rules are. AGENTS.md solves that.

What is AGENTS.md?

AGENTS.md is a text file that lives at the root of your repository. When an agent like Claude Code or Cursor starts working on your project, the first thing it does is read it.

In it you define everything the agent needs to know: the project's stack, how to run it, how to test it, the team's conventions and what not to touch.

It's basically the onboarding you'd give a new developer on their first day, but for your agent. And you only write it once.

AGENTS.md

└── repository root

└── the agent reads it before it starts working

What goes inside: the structure we use at Devlights

A good AGENTS.md has four clearly distinct sections. This is how we organize it:

1. Stack

Framework, database, main libraries. The agent needs to know what it's working with before it touches a single line of code.

markdown

# Stack
- Next.js 14
- Supabase
- Tailwind CSS

2. Conventions

How we name variables, whether we use semicolons, which linter runs, how folders are organized.

markdown

# Conventions
- No semicolons
- Single quotes
- Components in PascalCase, hooks prefixed with `use`
- ESLint + Prettier configured in the repo

3. Workflow

How tests are run, how deploys happen, which branches exist and what each one is for.

markdown

# Workflow
- Tests with Vitest before every commit
- `main` branch protected, requires a PR
- Automatic deploy to staging from `develop`

4. Restrictions

Files it must not modify, dependencies it must not upgrade without a heads-up, patterns the team decided not to use.

markdown

# Restrictions
- Don't modify /lib/core without opening a dedicated PR
- Don't upgrade major dependencies without approval
- Don't use `any` in TypeScript

Four sections, one file, and the agent starts every session knowing exactly how your team works.

The difference in practice: with and without AGENTS.md

To understand the real impact, it's worth comparing the same request in two scenarios.

Without AGENTS.md: you ask Claude Code to add a new endpoint to the project. The agent generates it with the structure it assumes is correct, with conventions that aren't your team's, in a folder that doesn't match the project's pattern.

With AGENTS.md in the repo: same instruction, same project. The agent uses the right stack, follows the team's conventions, puts the code in the right folder and runs the tests before finishing.

Without AGENTS.md → generic agent, guesses and assumes
With AGENTS.md    → your team's agent, follows the rules

Nobody told it any of this in the prompt. It read it straight from the file. That's the difference between an agent that "sort of gets" your project and one that works like another member of the team.

It works with any agent, not just one

An important point: AGENTS.md isn't a single-vendor standard. It isn't tied to one tool that could change direction or be discontinued tomorrow.

If your team switches agents tomorrow, the file is still valid. Nothing needs to be rewritten.

And if you work in a team, the file goes into the repository like any other: every developer has it, and every agent the team uses, no matter which one each person picks, works from the same base context.

One file    → multiple compatible agents
In the repo → the whole team uses it

When to create it

If you're starting a new project today, create the AGENTS.md before writing the first line of code. The time it takes to write, between 15 and 30 minutes for a typical project, pays for itself many times over in corrections you won't have to make.

If you already have a project underway, it's never too late to add it. Your next session with the agent will start with all the context you used to repeat by hand.

Coming up in the next episode

Once the agent knows how your team works, the next step is to give it specific expert knowledge: how to install skills so you don't have to explain the same thing every time you need something specific.

In the next video we show you exactly how to do it.