AGENTS.md and HUMAN.md: wetin dem mean

Wetin AGENTS.md be

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

The reason for this convention dey practical. New person for your team go read README, guess the build command, then 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, then try another thing. You go 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 because the file dey for path wey every tool already dey check.

Where the file dey go and which file dey win

Put the first one for repository root. For monorepo, you fit add more inside each subproject, and the rule simple: "agents automatically read the nearest file for the directory tree, so the one wey dey closest go take precedence." 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 dey useful, because na the only way to talk say something true for one folder but false for the next one. Rule like "every endpoint validates its input" suppose dey beside the endpoints. If e dey root file, e go load for every unrelated task and e no gain anything. If your root file don already grow one section for each service, split am into nested layout na the fix, and e explain which rules go move down and which ones go remain for top.

Wetín suppose dey inside an AGENTS.md

Write down wetín agent no fit work out by reading the code. The exact build, test and lint commands suppose come first, for the form wey you go paste inside terminal. Add command wey dey run one test, because agent wey only know how to run the whole suite go run the whole suite forty times. Name conventions wey different from the tool default, because agent already know the default and only need hear about your own difference. Add commit message format and pull request rules if you get dem.

Make the instructions concrete enough for person to check the claim. "Use 2-space indentation" na usable instruction because e either happen or e no happen. "Format code properly" no be usable, because nobody fit verify wetín e mean. 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/, npm run build generate dem" go stop one specific mistake, and because e name the cause, agent fit work out the equivalent case wey you no write down. Rule about scope belong here too, because if you leave agent to use im own judgement, e fit rewrite more than wetín you ask for: one skill wey plenty people copy dey only insist on the smallest change wey go work.

Wetin no suppose dey inside one

Never put secret for any of these files. Git dey commit the file, e load am into context when every session start, and e send am go model provider for every request. API key wey dey inside AGENTS.md go dey for your repository history and third party logs. Point to the secret instead of pasting am: “the database password dey inside .env, wey gitignore cover; 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 folder names: all of dem go stale one week after you write dem, and dem go use context for every session before then. Keep the pitfalls and the reasons. Remove the inventory. The reasons deserve separate explanation, because agent wey no fit see why unusual structure dey there fit quietly refactor am away. Na this be the reason for keeping DESIGN.md beside this one.

CLAUDE.md na Claude Code version of the same idea

Claude Code dey read CLAUDE.md, but e no dey read AGENTS.md by itself. Project file dey for ./CLAUDE.md or ./.claude/CLAUDE.md. Personal preferences for every project go inside ~/.claude/CLAUDE.md. Organisation fit push one machine-wide file go /etc/claude-code/CLAUDE.md for Linux. System dey concatenate discovered files from filesystem root down reach your working directory. So, file wey dey closest to where you launch the session go read last. Every session wey you start for that directory go load the same stack. Na this make am workable to run two sessions side by side for one machine, and those sessions fit hand work give each other while dem dey run.

If your repository already get AGENTS.md, no maintain second copy. Import am, then add only the things wey 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

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

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

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 follow am. But nothing go block action wey contradict am. When model quietly skip rule wey you write and you no fit tell why, work through why instruction dey get dropped before you rewrite the wording for the third time. For rule wey must hold every single time, like "never push to main", use hook or permission setting. Dem dey run as code and dem no depend on model deciding to obey.

Tools wey dey write these files for you

Two projects wey dey 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 content of its AGENTS.md enter your own root AGENTS.md, and na that be the installation. 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 don land. The idea behind am be say documentation wey agent maintain as part of its work go remain correct, while documentation wey person dey update by hand no dey.

HUMAN.md, na the same trick wey dem aim at you

Intuition-Lab/personal-model (1,260 stars as of July 2026) dey apply the pattern to person instead of repository. The project describe your HUMAN.md as 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 the result to agents through MCP (model context protocol). The short install path:

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

You no need any of that to get most of the benefit. Hand-written HUMAN.md na about twenty lines: your role, your timezone, the stack wey you really dey use, decisions wey you don already make and no want reopen, and how much explanation you want back. E dey save the same repeated explanation wey project file dey save, but one layer above.

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 at project root. E go load alongside the committed file and dem go treat both the same way.

Starter template wey you fit copy

This one short on purpose. Delete the sections wey no apply, and no add ones wey you no fit 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 am first, then correct am for the same place. The signal to add a line na when you type the same correction for chat twice. 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 travel with the repository. This one matter most when the agent run somewhere wey no be your laptop: running coding agent for your own server cover that setup.

FAQ

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

Na the same idea under two filenames. Claude Code dey read CLAUDE.md and ignore AGENTS.md unless you connect dem. Keep one file as the source of truth and link the other to am, either with line wey dey read @AGENTS.md for 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 normally comply, but nothing dey block action wey contradict am. Vague instructions dey get followed less reliably, and two files wey give opposite guidance leave the agent to choose one anyhow. For rule wey must hold every time, use hook or permission rule. 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 belong for 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 person, instead of project. E 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 for your user-level instructions file go give you most of the benefit. Treat am as personal data and keep am out of any repository wey you push.