AGENTS.md is a plain Markdown file you put in the root of a code repository to give AI coding agents the instructions they need: how to install dependencies, how to run the tests, which code style to follow and what they must never touch. Think of it as a README written for agents instead of people. There are no required fields or special syntax. Agents read the file before they start work, and the nearest AGENTS.md to the file being edited takes precedence.
The format is having a big year. The official AGENTS.md site says it’s used by over 60,000 open-source projects and lists tools including OpenAI Codex, Google’s Jules and Gemini CLI, GitHub Copilot’s coding agent, Cursor, VS Code, Zed, Aider, Devin and JetBrains Junie. In December 2025 it became a founding project of the Linux Foundation’s new Agentic AI Foundation. And on 6 October 2026, Next.js 16.4 shipped new agent tooling, including an --agent option for next upgrade. AI agents are now a normal part of web development, so a good AGENTS.md is worth ten minutes of your time.
I set up a small demo repository on 12 October 2026 to test the template and the helper scripts in this post. All the output below is real.
README files are for humans: what a project is, how to get started, how to contribute. Coding agents need extra, more precise detail that would clutter a README, such as the exact test command, the lint rules and the folders that are off-limits.
The AGENTS.md site gives three reasons for keeping it separate:
Before AGENTS.md, each tool invented its own file name. One open, shared name means you write the instructions once and every compatible agent can use them.
The site says the format “emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.”
On 9 December 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF), with founding contributions from Anthropic, Block and OpenAI. Its three inaugural projects were the Model Context Protocol (MCP), goose and AGENTS.md. The press release describes AGENTS.md as “a simple, universal standard that gives AI coding agents a consistent source of project-specific guidance needed to operate reliably across different repositories and toolchains.” Being under a neutral foundation is a big part of why other tools have adopted it rather than inventing alternatives.
Create a file called exactly AGENTS.md (capital letters, with the S) in the root of your repository, next to README.md, and commit it like any other file.
For a larger project or monorepo, you can add more AGENTS.md files inside sub-folders. The site explains that agents read the nearest file in the directory tree, so the closest one wins and each sub-project can have tailored instructions. It mentions that, at the time of writing, OpenAI’s main repository had 88 AGENTS.md files.
There’s no required structure. The site suggests these popular sections:
It also suggests adding anything you’d tell a new teammate: commit message format, pull request rules, deployment steps, large datasets to avoid. From my own testing, I’d add a Boundaries section with clear “never” and “ask first” rules, because they’re the instructions that prevent the most damage.
Here’s the file I used in my demo repo, a small PHP and JavaScript site. Copy it and adjust the commands to your project:
# AGENTS.md
## Project overview
Small PHP + JavaScript portfolio site. PHP 8.4, MySQL 8.4, no framework.
## Setup and test commands
- Run tests: `python3 -m unittest discover -s tests`
- Lint PHP: `php -l index.php`
## Code style
- PHP: `declare(strict_types=1);` at the top of every file
- Escape all output with `htmlspecialchars()`
## Boundaries
- Never commit `.env` or anything in `uploads/`
- Ask before adding a dependency
A few principles that make this work:
python3 -m unittest discover -s tests is not..env” matters because secrets in Git history are hard to remove. If it’s already happened, my guide to removing a file from a Git repo but keeping it locally shows the fix, but remember the old commits still contain it, so rotate the secret too.An AGENTS.md is only useful if its commands actually work. The site’s FAQ says agents will run the testing commands you list and try to fix failures before finishing, so a stale command wastes an agent’s time or, worse, makes it “fix” the wrong thing. I wrote a small Python script that finds every AGENTS.md, pulls out lines starting - Run tests: or - Lint …:, runs the command from that file’s folder and reports the result:
"""Run every command listed after 'Run tests:' or 'Lint ...:' in each AGENTS.md."""
import pathlib, re, subprocess, sys
PATTERN = re.compile(r"^- (Run tests|Lint[^:]*): `([^`]+)`", re.M)
failed = 0
for path in sorted(pathlib.Path(".").rglob("AGENTS.md")):
for label, cmd in PATTERN.findall(path.read_text(encoding="utf-8")):
result = subprocess.run(cmd, shell=True, cwd=path.parent, capture_output=True, text=True)
status = "ok" if result.returncode == 0 else f"FAILED ({result.returncode})"
failed += result.returncode != 0
print(f"{path}: {label}: {cmd} -> {status}")
sys.exit(1 if failed else 0)
Running it in my demo repo, which has a root AGENTS.md and a nested one in packages/api/:
AGENTS.md: Run tests: python3 -m unittest discover -s tests -> ok
AGENTS.md: Lint PHP: php -l index.php -> ok
packages/api/AGENTS.md: Run tests: python3 -c "print('api tests ok')" -> ok
Then I broke a command on purpose, changing the lint target to a file that doesn’t exist:
AGENTS.md: Run tests: python3 -m unittest discover -s tests -> ok
AGENTS.md: Lint PHP: php -l missing.php -> FAILED (1)
packages/api/AGENTS.md: Run tests: python3 -c "print('api tests ok')" -> ok
The script exits with code 1, so you can run it in CI and fail the build when the instructions go stale. One warning: it executes whatever commands the file contains, with shell=True. Only run it on repositories you trust, exactly as you’d only let an agent run commands in a repo you trust.
To list every AGENTS.md in a project, use find:
$ find . -name AGENTS.md | sort
./AGENTS.md
./packages/api/AGENTS.md
To understand which file applies to a given source file, walk up from that file’s folder until you find one. This little function mirrors the “nearest file wins” rule:
import pathlib
def nearest_agents_md(file_path, root="."):
root = pathlib.Path(root).resolve()
folder = pathlib.Path(file_path).resolve().parent
while True:
candidate = folder / "AGENTS.md"
if candidate.exists():
return candidate.relative_to(root)
if folder == root or folder.parent == folder:
return None
folder = folder.parent
print(nearest_agents_md("packages/api/routes.php"))
print(nearest_agents_md("packages/web/app.js"))
packages/api/AGENTS.md
AGENTS.md
A file in packages/api/ gets the API instructions; a file in packages/web/, which has no AGENTS.md of its own, falls back to the root file. Keep nested files short and only include what’s different for that package, so you don’t have to update the same rule in five places.
The AGENTS.md FAQ is clear: the closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything. So if your file says “use tabs” and you ask an agent in chat to use spaces for one change, the chat instruction applies.
That has a security side. An AGENTS.md is just text the agent trusts, so treat changes to it like changes to code: review them in pull requests. A malicious or careless edit (“skip the tests”, “commit directly to main”) changes how agents behave in your repo.
If you already have an older agent file, the AGENTS.md FAQ suggests renaming it and leaving a symbolic link for backward compatibility. Its example is mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. In my demo, that produced:
lrwxrwxrwx AGENT.md -> AGENTS.md
On Windows, symbolic links need extra permissions, so check your team’s setup before relying on them.
The FAQ also shows how to point two specific tools at AGENTS.md: for Aider, add read: AGENTS.md to .aider.conf.yml; for Gemini CLI, set "context": { "fileName": "AGENTS.md" } in .gemini/settings.json.
These are the problems most likely to make an AGENTS.md less useful:
vendor/” or “never run migrations against production”, they may do exactly that.There’s no official limit, but shorter is better. Agents read the file as part of their working context, so every line competes with your actual code for attention. For a small project, 20 to 60 lines is plenty: an overview, the commands, a handful of style rules and the boundaries. For a large monorepo, keep the root file general and put package-specific detail in nested files. If a section grows beyond a screen, move it to a separate document and link to it from AGENTS.md.
AGENTS.md is committed and often public, and agents may echo its contents into logs or pull requests. Never put API keys, passwords or private URLs in it. Instead, tell the agent where configuration comes from, for example “API keys are read from environment variables; see .env.example”. The same rule applies to front-end code: anything shipped to the browser is public, which is why keeping an AI API key off the browser matters.
AGENTS.md is a Markdown file in a code repository that gives AI coding agents project-specific instructions, such as build and test commands, code style and boundaries. It’s often described as a README for agents.
The official site lists many, including OpenAI Codex, Google’s Jules and Gemini CLI, GitHub Copilot’s coding agent, Cursor, VS Code, Zed, Aider, Devin, Windsurf and JetBrains Junie. Check each tool’s docs for the details of how it loads the file.
No. It’s standard Markdown with no required fields. Use any headings you like. Clear sections, short bullet points and exact commands in backticks work best.
In the root of your repository, next to README.md. In a monorepo you can add extra AGENTS.md files in sub-folders; agents use the nearest one to the file they’re editing.
Your explicit chat prompt wins. Between files, the AGENTS.md closest to the edited file takes precedence over ones higher up the tree.
It started as a collaboration between AI tool makers including OpenAI, Google, Cursor, Amp and Factory. Since 9 December 2025 it has been a project of the Agentic AI Foundation under the Linux Foundation.
No. The file is committed and may be public. Explain where configuration lives, such as environment variables, without including the actual secret values.
// note
This is a learning note from studying the web. It is one small topic, written so I can remember it. It is not a course and not a claim that I have finished the subject.
If a sentence is wrong, say so from the contact page and name this title. Drafts never appear here. Related notes, when they exist, are other published posts, and the same sample rule applies to each of them.
PHP 8.6 is due on 19 November 2026. I built RC3 and tested the new features: partial function application with ? and ..., clamp(), readonly property defaults, Time\Duration, the SortDirection enum and JSON errors with a location.
Python 3.15 adds frozendict, a built-in immutable, hashable dictionary. Tested examples: creating one, why you can’t change it, using it as a dict key or in a set, merging with |, isinstance checks and a fallback for older Python.
enumerate(items, start=1) gives you a counter that starts at 1 alongside each item. Tested examples for lists, dicts, zip, reversed order, file line numbers and comprehensions, plus why it beats range(len()) and the list.index() trap.
UAC (User Account Control) is the Windows feature that runs your apps with standard rights and asks before anything gets admin power. Here’s how the two tokens, the dimmed secure desktop, the four slider levels and the registry settings fit together.