View : 114

20/11/2026 00:00am

Illustration of a small robot on a desk holding a paper checklist beside a laptop, with a card showing 8x and a label reading Correlation

What Is AGENTS.md? How to Write One So an AI Coding Agent Works Right in Your Repo

#AGENTS.md

#AI coding agent

#Octoverse 2026

#GitHub Copilot

#Golang

Imagine you have just joined a new team. On day one someone sends you the README. It explains what the project does, but not which command runs the tests, which code formatter to use, or which folders are off limits. You would end up asking your teammates one question at a time.

An AI coding agent runs into the same problem every time it opens a project, and one file format was designed to answer it: AGENTS.md. Today Superdev Academy walks through what it is, where it goes, what to put in it, and how to read the 8x figure from the Octoverse 2026 report that people are quoting about this kind of file.

What is AGENTS.md

The agents.md site defines it as "a simple, open format for guiding coding agents" and compares it to a README for agents: a place for the context and commands an agent needs, which would clutter a normal README for human readers.

The rules are short. The file lives at the root of the repository. In a monorepo with several sub-projects, you can nest a file inside each one. The agent reads the file closest to the one it is editing, and the closer file wins. A command you type directly in the chat with the agent beats everything. The file itself is plain Markdown with no required fields, so you can use whatever headings you like.

Which tools read this file

The agents.md page lists many tools that read the file, such as Codex, Jules, Cursor, Gemini CLI, GitHub Copilot coding agent, Devin, Windsurf, Aider, Zed, Warp and VS Code. That list belongs to the site itself and we have not tested each tool. The site also claims that more than 60,000 open-source projects use the format, which is again a figure from the people who maintain the standard.

The site states that the standard is stewarded by the Agentic AI Foundation under the Linux Foundation. For tools that do not read the file automatically, it gives setup examples: for Aider, add the line read: AGENTS.md to .aider.conf.yml, and for Gemini CLI, set "context": { "fileName": "AGENTS.md" } in .gemini/settings.json.

How to read the 8x figure from Octoverse

The GitHub Octoverse 2026 report says that among repositories created this year, those with an agent configuration file had 8x the number of commits of new repos without one.

Before concluding that writing the file makes work 8x faster, read three limits. First, the report talks about "agent configuration files" in general, not AGENTS.md specifically. Second, this is a correlation and does not prove the file is the cause. Third, projects that take the trouble to write such a file may simply be projects whose people already work hard, and counting commits measures volume, not the quality of the work.

What you can safely take from it is that agent configuration files are becoming common in new repos, which is reason enough to know about them.

What to write in it

agents.md suggests five popular groups of headings: a project overview, build and test commands, code style guidelines, testing instructions, and security considerations, plus guidance on commits or opening a PR. If you write down the test commands, the site says the agent will try to run the relevant checks and fix failures before it finishes.

The following is a hypothetical file for a Go project that we wrote for teaching. Every command is a standard Go command.

# AGENTS.md

## Overview
REST API for a membership system, written in Go. Core code lives in internal/ and the entry point is in cmd/api/

## Commands
- Build: `go build ./...`
- Test: `go test ./...`
- Check formatting: `gofmt -l .` (any file it prints has not been formatted)
- Basic checks: `go vet ./...`

## Code style
- Always return errors, never ignore them with `_`
- Name tests `TestFunctionName_Case`

## Security
- Never put secrets or tokens in code or in this file; read them from environment variables
- Never edit files in migrations/ that have already been merged

Notice that the file is short, to the point, and made of commands that actually run. We suggest starting with three groups: commands, style and security, and adding more when you see the agent get the same thing wrong repeatedly.

Will the agent follow the file every time

There is no guarantee. The file gives the agent context, but the model still has to interpret it and can still get things wrong. Writing "never edit files in migrations/" does not mean it will never happen. Work that touches real data or user permissions still needs a person to read and approve it.

If your team is setting rules for using AI at work, read the overview of the frameworks large organisations use in What is AI Governance, and treat AGENTS.md as the project-level rule that sits inside them.

Try it in 15 minutes

Open a practice project that already has tests. Create an AGENTS.md at the root following the example above, and change the commands to match your project. Then ask the agent you use to add a small function and watch whether it runs the test command before saying it is done. If it does not, first check whether that tool reads the file by itself or needs extra setup, as Aider and Gemini CLI do.


Summary: a short README for agents that actually runs

AGENTS.md is a Markdown file at the root of a repo that tells an AI coding agent how the project builds, tests and writes code. The closer file wins, and a command in the chat beats them all. The 8x figure from Octoverse 2026 is a correlation with "agent configuration files" in general, not evidence that this file makes work faster.

Start with a short file of commands that really run, code style, and security prohibitions, then adjust based on what the agent keeps getting wrong. Important work still needs a person to read it before pressing Merge.

The example in this article is written in Go. If the language is new to you, take a look at the Go Cheat Sheet course from Superdev Academy, which runs 48 minutes with 12 months of access. It does not teach AGENTS.md. Browse all courses at learn.superdevacademy.com/courses.

🎯 Follow dev knowledge from Superdev Academy:

FAQ: Frequently Asked Questions about This Article

A collection of questions and answers to help you better understand the content of this article.