AGENTS.md vs HUMANS.md
AGENTS.md tells agents how to work on your code. HUMANS.md tells them how to work with you. You need both, and they never compete: one describes a repository, the other a person.
| AGENTS.md | HUMANS.md | |
|---|---|---|
| What it describes | A codebase: build, tests, conventions | A person: what they read, what they decide, when to interrupt them |
| Who writes it | The maintainers of a repository | The person it describes, and nobody else |
| Who reads it | Coding agents working in that repository | Any agent working for that person or writing to them |
| Where it lives | At the root of a repository, nested per package | ~/.humans/me.md for you; humans/<id>.md in a team repository |
| Format | Free Markdown, no required fields | YAML fields with closed values, checked by a JSON Schema |
| Free text | All of it is free text | Written locally, compiled into fields; never sent to other agents |
| Permissions | Can tell agents what they may run | Never grants a permission; can only make agents ask less |
| When both disagree | Wins on what an agent may do in the repository | Wins on how the agent writes to you and when it stops for you |
Use both
Keep your AGENTS.md as it is. Point your agent at your HUMANS.md from your personal instructions, so it follows you from one repository to the next. In Claude Code, add this line to ~/.claude/CLAUDE.md:
@~/.humans/me.mdFor Codex and others, see implementations.
When they disagree
The repository wins on what an agent may do. If an AGENTS.md says “ask before you deploy”, the agent asks, even if your HUMANS.md says to decide reversible things alone. HUMANS.md wins on how the agent talks to you: what comes first in a message, how questions are grouped, and when it may interrupt you. The rule is in § 4 of the spec.
Other files called HUMANS.md
The name is used elsewhere for two other things. Some projects keep a list of contributors in a HUMANS.md, in the spirit of humans.txt. Others, such as attogram/agents, use it for guidance written for people who work alongside agents. A HUMANS.md profile is the one that starts with a YAML block containing humans: "0.2"; agents ignore the others.