AGENTS.md and HUMAN.md: Wetin Dem Mean

Wetin AGENTS.md be

AGENTS.md na plain markdown file for the root of repository wey dey tell coding agent how e suppose work for that project. The official site describe am as "README for agents: one dedicated, predictable place to provide the context and instructions wey go help AI coding agents work for your project." Agentic AI Foundation under Linux Foundation dey manage the format, and more than twenty agents dey read am, including Codex, Cursor, Jules, Devin and GitHub Copilot (as of July 2026).

The reason for this convention na practical one. New person for your team go read the README, guess the build command, and ask person when the guess no correct. Agent no fit ask. E go guess, run npm test for project wey dey use pnpm test, read the failure, and try another thing. You dey pay for every one of those tokens. If you write the correct command down once, e go remove this whole type of failure.

No required fields dey. The site talk am clearly: "AGENTS.md na just standard Markdown. Use any headings wey you like; the agent go simply parse the text wey you provide." Na the complete specification be that. The value no dey for the format. E dey for the file wey dey for path wey every tool already dey check.

Where dem put the file and which file go win

Put the first one for repository root. For monorepo, you fit add more inside each subproject. The rule simple: "agents automatically read the nearest file for the directory tree, so the one wey dey closest na im get priority." If two files conflict, the file wey you dey edit go win, and anything wey you type for chat go override 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 useful because na the only way to talk something wey true for one folder but false for the next one. Rule like "every endpoint validates its input" suppose dey beside the endpoints. If you put am for root file, e go load for every unrelated task and e no go add any benefit.

Wetin suppose dey inside AGENTS.md

Write down wetin agent no fit work out from reading the code. Put the exact build, test and lint commands first, for the format wey you go paste into terminal. Add command to run one test, because agent wey only sabi run the whole suite go run the whole suite forty times. Name conventions wey different from the tool default, because agent already sabi the default and only need hear about your change. Add commit message format and pull request rules if you get dem.

Make the instructions concrete enough so person fit check the claim. “Use 2-space indentation” na useful instruction because e either happen or e no happen. “Format code properly” no useful, because nothing inside am fit verify. Same thing apply to locations: “API handlers dey inside src/api/handlers/” better pass “keep files organised”.

Negative rules still deserve space. “Never edit files under dist/, dem na generated files from npm run build” go stop one particular mistake. Because e name the cause, agent fit work out the equivalent case wey you no write down.

Wetin no suppose dey inside one

No ever put secret for any of these files. Git dey commit the file, e dey load am into context for the beginning of every session, and e dey send am to a model provider for every request. API key wey dey inside AGENTS.md dey for your repository history and for third party logs. Point to the secret instead of pasting am: "the database password dey inside .env, wey gitignore don exclude; ask before you read am." The wider discipline dey covered for keeping credentials away from agent reach.

Leave out anything wey agent fit derive by looking. Directory listing wey you paste, copy of your dependency list, architecture overview wey just repeat the folder names: all of dem go become stale the week after you write dem, and dem dey use context for every session until then. Keep the pitfalls and the reasons. Remove the inventory.

CLAUDE.md na Claude Code version of the same idea

Claude Code dey read CLAUDE.md and e no dey read AGENTS.md by itself. Project file dey for ./CLAUDE.md or ./.claude/CLAUDE.md, personal preferences for every project dey go inside ~/.claude/CLAUDE.md, and organisation fit push machine-wide file go /etc/claude-code/CLAUDE.md for Linux. System dey join discovered files from filesystem root reach your working directory, so na the file wey dey closest to where you start the session dey read last.

If your repository don already get AGENTS.md, no maintain second copy. Import am, then add only wetin concern Claude:

@AGENTS.md

## Claude Code

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

Symlink go work when you no get anything extra to add:

ln -s AGENTS.md CLAUDE.md

The command no go print anything if e succeed. For your next session, run /context and confirm say CLAUDE.md dey show under Memory files. If e no dey for that list, the file no load at all, so nothing inside am apply. To generate first draft instead of writing one yourself, run /init: e go read the codebase and produce starting file, and if CLAUDE.md already dey, e go suggest improvements instead of overwriting am.

Keep each file below about 200 lines. Longer files dey use more space for the window, and adherence dey reduce. If you wan see wetin else dey compete for that space, wetin really dey fill agent context window explain am.

One point need emphasis. AGENTS.md na guidance, e no be permission system. The content dey enter as ordinary context, so model go read am and usually comply, but nothing go block action wey contradict am. For rule wey must hold every single time, like "never push to main", use hook or permission setting, because dem dey run as code and dem no depend on whether model decide to obey.

Tools wey dey write these files for you

Two projects for GitHub trending list on 30 July 2026 show where this convention dey go.

agent0ai/dox (1,368 stars as of July 2026) na framework wey dey keep tree of AGENTS.md files current. E no ship any package or runtime. You go copy the contents of its AGENTS.md enter your own root AGENTS.md, and na so you install am. For project wey don already exist, tell your agent:

Initialize DOX tree for this project now.

The agent go create the child AGENTS.md files and their indexes, check that tree before e edit anything, and update the affected documentation after change land. The idea behind am be say documentation wey agent dey maintain as part of its work go remain correct, but documentation wey person dey update by hand no go.

HUMAN.md, na di same trick wey dem point at you

Intuition-Lab/personal-model (1,260 stars as of July 2026) dey apply dis pattern to person instead of repository. Di project dey treat your HUMAN.md as di system output, no be file wey you type: "a living model of what matters now, how you tend to decide, and where your attention is moving." E dey run locally for macOS 13 or later, e dey capture activity after you grant macOS permission, and e dey expose di result to agents through MCP (model context protocol). Di short install path na:

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

You no need any of dat to get most of di benefit. Hand-written HUMAN.md fit be about twenty lines: your role, your timezone, di stack wey you really dey use, di decisions wey you don already make and no want make dem reopen, and how much explanation you want make dem send back. E dey save di same repeated explaining wey project file dey save, but for one level higher.

One caution. HUMAN.md na profile of person, so e sensitive by definition. No keep am for public repository. Put am for ~/.claude/CLAUDE.md, or for gitignored CLAUDE.local.md for di project root. E go load together with di committed file, and dem go treat both di same way.

Template wey you fit start with and copy

This one short on purpose. Delete the sections wey no apply, and no add ones wey you no fit keep up to date.

# 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 am, then correct am for the same place. The signal say make you add one line na when you don type the same correction for chat two times. This one rule keep the file useful, and e stop the file from growing into document wey nobody dey read, including machines. Once e stable, e dey move together with the repository. This one matter pass when the agent dey run for somewhere wey no be your laptop: running coding agent for your own server explain that setup.

FAQ

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

Na the same idea under two filenames. Claude Code dey read CLAUDE.md and dey ignore AGENTS.md unless you connect dem. Keep one file as the source of truth and link the other one to am, either with a line wey dey read @AGENTS.md for the top of your CLAUDE.md or with ln -s AGENTS.md CLAUDE.md. Two complete copies wey you dey maintain separately go disagree within one month.

If I write AGENTS.md, e guarantee say the agent go follow am?

No. The content dey enter as context, so the model dey read am and generally comply, but nothing dey block action wey contradicts am. Vague instructions dey get followed with the least reliability, and two files wey give opposite guidance go leave the agent to choose one arbitrarily. For rule wey must hold every time, use a hook or permission rule. The client dey enforce dem regardless of wetin the model decide.

I suppose commit AGENTS.md to git?

Yes, for anything wey dey true about the project: build commands, layout, and conventions. Na the purpose of the file, because your teammates' agents go then start with the same context wey your own agent get. Anything personal or specific to one machine suppose dey inside separate gitignored file, and credentials no suppose dey inside either one.

Wetin be HUMAN.md, and I need one?

HUMAN.md na machine-readable profile of a person, no be project. E dey contain your role, your constraints, and decisions wey you don already settle, so dem no go reopen every session. You no need any tooling to start: twenty handwritten lines inside your user-level instructions file go give you most of the benefit. Treat am as personal data and no keep am inside any repository wey you push.