We used to have README.md written by humans for humans. Today, most repos have adopted the AGENTS.md/CLAUDE.md convention. It’s the entrypoint for agents to get up to speed and start building. It’s usually written by agents, very detailed, and quickly tends to drift and get stale.

The line between README.md and AGENTS.md is quickly blurring.

This is why I propose we start a new convention, HUMANS.md

It’s pretty simple - the conventional README.md just points you to either file. Here’s an example from my latest project, worktui.

HUMANS.md should answer the important questions for the humans. Short and curated for the readers with limited eye span and reading times. Mermaid diagrams and charts.

High level instructions: what is this for and how do I get started. How does it work at the level I need to think about. The rest you can point your own agents to and get more detail as you need it.

Let’s not become an afterthought in our own repos!