AGENTS.md and HUMAN.md, explained

What AGENTS.md is

AGENTS.md is a plain markdown file at the root of a repository that tells a coding agent how to work on that project. The official site describes it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." The format is stewarded by the Agentic AI Foundation under the Linux Foundation, and more than twenty agents read it, including Codex, Cursor, Jules, Devin and GitHub Copilot (as of July 2026).

The reason the convention exists is practical. A new person on your team reads the README, guesses the build command, and asks someone when the guess is wrong. An agent cannot ask. It guesses, runs npm test on a project that uses pnpm test, reads the failure, and tries something else. You pay for every one of those tokens. Writing the real command down once removes that whole class of failure.

There are no required fields. The site is explicit about it: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." That is the entire specification. The value is not in the format. It is in the file sitting at a path that every tool already looks at.

Where the file goes and which file wins

Put the first one at the repository root. In a monorepo you can add more inside each subproject, and the rule is simple: "agents automatically read the nearest file in the directory tree, so the closest one takes precedence." A conflict between two files resolves toward the file being edited, and anything you type into the chat overrides both.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

The nesting is worth using, because it is the only way to say something that is true in one folder and false in the next. A rule like "every endpoint validates its input" belongs beside the endpoints. In a root file it loads on every unrelated task and buys nothing.

What belongs in an AGENTS.md

Write down what an agent cannot work out by reading the code. The exact build, test and lint commands come first, in the form you would paste into a terminal. Add the command for running one test, because an agent that only knows how to run the whole suite will run the whole suite forty times. Name the conventions that differ from the tool default, since the agent already knows the default and only needs to hear about your deviation. Add the commit message shape and the pull request rules if you have them.

Be concrete enough that a claim can be checked. "Use 2-space indentation" is a usable instruction because it either happened or it did not. "Format code properly" is not, because nothing in it can be verified. The same goes for locations: "API handlers live in src/api/handlers/" beats "keep files organised".

Negative rules earn their space too. "Never edit files under dist/, they are generated by npm run build" stops one specific mistake, and because it names the cause, the agent can work out the equivalent case you did not write down.

What never belongs in one

Never put a secret in one of these files. The file is committed to git, loaded into context at the start of every session, and sent to a model provider on every request. An API key in an AGENTS.md is an API key in your repository history and in a third party's logs. Point at the secret instead of pasting it: "the database password is in .env, which is gitignored; ask before reading it." The wider discipline is covered in keeping credentials out of an agent's reach.

Leave out anything the agent can derive by looking. A pasted directory listing, a copy of your dependency list, an architecture overview that restates the folder names: all of it goes stale the week after you write it, and it costs context on every session in the meantime. Keep the pitfalls and the reasons. Drop the inventory.

CLAUDE.md is the Claude Code instance of the same idea

Claude Code reads CLAUDE.md and does not read AGENTS.md on its own. A project file lives at ./CLAUDE.md or ./.claude/CLAUDE.md, personal preferences for every project go in ~/.claude/CLAUDE.md, and an organisation can push a machine-wide file to /etc/claude-code/CLAUDE.md on Linux. Discovered files are concatenated from the filesystem root down to your working directory, so the file closest to where you launched the session is read last.

If your repository already has an AGENTS.md, do not maintain a second copy. Import it, then add only what is Claude specific:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink works when you have nothing extra to add:

ln -s AGENTS.md CLAUDE.md

The command prints nothing on success. In your next session run /context and confirm CLAUDE.md appears under Memory files. If it is missing from that list, the file never loaded, so nothing in it applied. To generate a first draft instead of writing one, run /init: it reads the codebase and produces a starting file, and when a CLAUDE.md already exists it suggests improvements rather than overwriting.

Keep each file under about 200 lines. Longer files consume more of the window and adherence drops. If you want to see what else competes for that space, what actually fills an agent's context window breaks it down.

One point deserves emphasis. An AGENTS.md is guidance, not a permission system. The content arrives as ordinary context, so the model reads it and usually complies, but nothing blocks an action that contradicts it. For a rule that must hold every single time, such as "never push to main", use a hook or a permission setting, because those run as code and do not depend on the model deciding to obey.

Tools that write these files for you

Two projects on the GitHub trending list on 30 July 2026 show where the convention is heading.

agent0ai/dox (1,368 stars as of July 2026) is a framework for keeping a tree of AGENTS.md files current. It ships no package and no runtime. You copy the contents of its AGENTS.md into your own root AGENTS.md, and that is the install. For a project that already exists, you tell your agent:

Initialize DOX tree for this project now.

The agent then creates the child AGENTS.md files and their indexes, walks that tree before it edits anything, and updates the affected documentation after a change lands. The bet behind it is that documentation an agent maintains as a side effect of its work stays true, while documentation a person updates by hand does not.

HUMAN.md, the same trick pointed at you

Intuition-Lab/personal-model (1,260 stars as of July 2026) applies the pattern to a person instead of a repository. The project frames your HUMAN.md as the output of the system rather than a file you type: "a living model of what matters now, how you tend to decide, and where your attention is moving." It runs locally on macOS 13 or later, captures activity after you grant macOS permission, and exposes the result to agents over MCP (model context protocol). The short install path:

uv tool install personal-model
persome onboard
persome model open --after 30

You need none of that to get most of the benefit. A hand-written HUMAN.md is about twenty lines: your role, your timezone, the stack you actually use, the decisions you have already made and do not want reopened, and how much explanation you want back. It saves the same repeated explaining that a project file saves, one layer up.

One caution. A HUMAN.md is a profile of a person, so it is sensitive by definition. Keep it out of a public repository. Put it in ~/.claude/CLAUDE.md, or in a gitignored CLAUDE.local.md at the project root, which loads alongside the committed file and is treated the same way.

A starter template you can copy

This is short on purpose. Delete the sections that do not apply, and resist adding ones you cannot keep current.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Write it, then correct it in place. The signal for adding a line is that you typed the same correction into the chat twice. That one rule keeps the file useful, and it stops the file growing into a document nobody reads, machines included. Once it is stable it travels with the repository, which matters most when the agent runs somewhere other than your laptop: running a coding agent on your own server covers that setup.

FAQ

Is AGENTS.md the same file as CLAUDE.md?

They are the same idea under two filenames. Claude Code reads CLAUDE.md and ignores AGENTS.md unless you connect them. Keep one file as the source of truth and link the other to it, either with a line reading @AGENTS.md at the top of your CLAUDE.md or with ln -s AGENTS.md CLAUDE.md. Two full copies maintained separately will disagree within a month.

Does writing an AGENTS.md guarantee the agent follows it?

No. The content is delivered as context, so the model reads it and generally complies, but nothing blocks an action that contradicts it. Vague instructions are followed least reliably, and two files giving opposite guidance leave the agent to pick one arbitrarily. For a rule that must hold every time, use a hook or a permission rule, which are enforced by the client whatever the model decides.

Should AGENTS.md be committed to git?

Yes, for anything true about the project: build commands, layout, conventions. That is the point of the file, because your teammates' agents then start with the same context yours does. Anything personal or specific to one machine belongs in a separate gitignored file, and credentials belong in neither.

What is HUMAN.md and do I need one?

HUMAN.md is a machine-readable profile of a person rather than a project. It holds your role, your constraints, and the decisions you have already settled so they do not get reopened every session. You need no tooling to start: twenty hand-written lines in your user-level instructions file gives you most of the value. Treat it as personal data and keep it out of any repository you push.