AGENTS.md in plain English: one file of house rules for every coding agent

👋 Easy read · Oct 16, 2026 · ~6 min read

Jargon jar: a coding agent is an AI helper that can read and change the files in your project, not just chat about them. A repo (repository) is the project folder you keep under version control. Markdown is plain text with a few symbols, like # for a heading and - for a bullet.

Why everyone is passing this file around

Ever opened a fresh chat with your coding agent and felt like you were training a new intern from scratch, again? Plan before you touch anything. Don’t rewrite the whole app to fix one button. Run the tests. By the third chat of the day, you are reciting the same speech like a flight attendant.

That itch is why a short AGENTS.md went around X at the end of September. One post sharing a six-section file by @Voxyz_ai on Sep 30, 2026 picked up 133,527 views and 1,071 likes, and a near-identical version from @RoundtableSpace on Oct 1 passed 58,679 views. A couple of weeks earlier, the Hacker News thread “Claude Code now reads AGENTS.md if there is no Claude.md” reached 741 points and 285 comments (numbers as of our research). The posts make big promises about turning agents into superstar engineers; we will stick to what the official docs say the file does.

What AGENTS.md actually is

The official site calls it “a simple, open format for guiding coding agents” and “a README for agents” (agents.md). Your README is for humans. AGENTS.md is the note you leave for the robot: how to install things, how to run the tests, and how you like the work done.

A few things make it friendly for beginners:

• No special syntax. There are no required fields. It is ordinary Markdown with whatever headings you like (agents.md FAQ).
• One file, many tools. The site lists a long line of tools that use it, including Cursor, Gemini CLI, Aider, Zed, Warp and Jules from Google, and says over 60,000 open-source projects use the format (agents.md).
• Nobody owns it. It grew out of work across OpenAI Codex, Amp, Jules, Cursor and Factory, and it is now looked after by the Agentic AI Foundation under the Linux Foundation (agents.md).
• Big projects can have several. You can drop another AGENTS.md inside a subfolder. The closest file to the code being edited wins, and whatever you type in chat still beats the file (agents.md FAQ).

Think of it as the house rules taped to the fridge. Every guest who walks into the kitchen sees them, and you never have to give the speech at the door.

Who reads it, and how

Codex reads it first thing. OpenAI’s docs say Codex reads AGENTS.md files “before doing any work” (Codex docs: AGENTS.md). You can keep personal rules in ~/.codex/AGENTS.md and project rules in the project itself. Codex stacks them from the top of the project down to the folder you are working in, so the more specific rules land last. By default it stops adding files once they total 32 KiB, which is a gentle hint to keep the rules short.

Claude Code reads it when there is no CLAUDE.md. Claude Code has its own rules file, CLAUDE.md. Since v2.1.277 on Sep 18, 2026, a project with no CLAUDE.md gets its AGENTS.md read instead, and you can change that under “Project instructions” in /config. The release notes say that it was not yet available on Bedrock, Vertex or Foundry at launch. Anthropic’s memory docs walk through the details (Claude Code docs: AGENTS.md).

Already have both files? Point one at the other. Anthropic’s docs show two ways to keep a single source of truth. Put @AGENTS.md at the top of your CLAUDE.md to pull the shared rules in, then add any Claude-only notes below it. Or, if you need nothing Claude-specific, make CLAUDE.md a shortcut (a symlink) to AGENTS.md with ln -s AGENTS.md CLAUDE.md. The docs suggest the @AGENTS.md import if anyone on the team uses Windows, because symlinks there need extra setup (Claude Code docs: share one file).

One honest caveat from the same docs: these files are context, not a locked door. The agent reads them and tries to follow them, and short, specific rules work better than long, vague ones (Claude Code docs).

A starter AGENTS.md you can copy

Here is a small one we wrote for this article. Swap in your own test command and you are done.

# AGENTS.md

## How we work here
1. Plan first. Before changing code, write a short plan and wait for a thumbs-up on anything big.
2. Make the smallest change that works. Fix the bug you were asked about, not the whole file.
3. Split big jobs into small steps. Finish and check one step before starting the next.
4. Run the tests with `npm test` before you say you are done, and fix anything you broke.
5. Ask before adding new packages, deleting files, or touching anything with passwords or keys.
6. When you finish, explain in plain words what you changed and why.

Six rules fit on one screen, and each one is concrete enough to check. That matches the advice in both the agents.md guide (build steps, tests, conventions) and Anthropic’s docs (“Run npm test before committing” beats “Test your changes”).

The one gotcha: a CLAUDE.md hides it

Here is the speed bump. By default, Claude Code only reads AGENTS.md when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or any folder above it. If one is sitting higher up, Claude reads that and skips your AGENTS.md (Claude Code docs: My AGENTS.md isn’t loading). Your personal ~/.claude/CLAUDE.md does not count against it.

Community member @torfinpd pointed this out on X and counted 161 of 283 popular repos that ship both files. That count is their own finding, not something we or Anthropic have checked, but the rule behind it is in the official docs. The fix is easy: add @AGENTS.md to the CLAUDE.md you already have, or set Project instructions to claude-md-and-agents-md in /config so Claude reads both.

Common mix-ups

• “Is it AGENT.md or AGENTS.md?” It is AGENTS.md, with an S. The official FAQ even shows how to rename an old AGENT.md and leave a symlink behind (agents.md FAQ).
• “Does it replace my README?” No. The README stays for humans, and AGENTS.md holds the extra detail an agent needs (agents.md).
• “Is this the same as a Skill?” Not quite. House rules apply to every chat. A Skill is a recipe card that only comes out when a task matches (see Main Course #1).

Chef’s pick: start with five or six short rules in a root AGENTS.md. If you also use Claude Code and already have a CLAUDE.md, add one line, @AGENTS.md, so every agent reads the same fridge note.

Source: x.com · 2105367927394615364 · 2105602371657036107 · 2108876607431553167 · news.ycombinator.com · item · agents.md · article · developers.openai.com · agents md · github.com · v2.1.277 · code.claude.com · memory