HUMANS.md: robots.txt, but for the humans

Every repo I work in now has a file called HUMANS.md: a checklist of the things only a person can do, kept by the AI agents that do everything else.

I build Canopy Run, a small fox platformer, mostly alone. "Alone" now means me plus a dozen agents: a level designer, a music producer, an iOS developer, a web developer and more, often five running at once. They write code, render art, compose music and test builds. What they can't do is sign a contract, enter a password, plug in a phone or decide whether a song sounds right.

My claim: if you run coding agents, your repo needs this file too. The work only a human can do is the slowest part of the system, and right now nothing tracks it. Here's the case, and a spec short enough to adopt in two minutes.

The problem: the human is the bottleneck, and nobody writes it down

With several agents working in parallel, the requests for me arrived as one line at the end of a long report. "The App Store needs a support URL." "Turn off the IDFA explainer in AdMob." "Please listen to the Skyglade choir at 0:40." By the next report, the last request had scrolled away.

The cost was real. One afternoon a device build sat for about an hour on a macOS keychain prompt that only I could answer. The agent was waiting on me, and I didn't know.

Agents are good at their own task lists. What was missing was a list kept for the one participant who can't be parallelised.

The spec

The whole convention is six rules.

1. One file, at the repo root: HUMANS.md, next to README.md. Plain Markdown, so the checkboxes tick in any editor or on GitHub.
2. Only human-only work goes in: accounts and money, sign-ins and secrets, physical hardware, taste calls, and approvals for anything public or hard to undo. If an agent could do it, it doesn't belong.
3. Every item is a checkbox with exact values. Not "set up the in-app purchase" but "Product ID com.canopy-run.game.removeads, non-consumable, about $2.99". The human should never need a follow-up question.
4. Group items by what they unblock, so the most blocking work sits at the top.
5. Agents write to the file and never act on it. An agent that needs a password or a payment writes it down and stops. It doesn't look for a workaround.
6. Tick it, date it, pass it on. When the human finishes an item, the agent session ticks the box, adds the date and hands off whatever it unblocked.

To make agents follow it, every agent definition in my repo ends with the same paragraph:

## HUMANS.md
Anything only the user can do (accounts, payments, sign-ins, the phone,
taste calls, approvals) goes in `HUMANS.md` at the repo root as a checkbox
item under the right section, with exact values and steps. Also mention it
in your report. Never do those things yourself.

If you run a single agent, put that paragraph in your CLAUDE.md or AGENTS.md instead.

Why not issues, TODOs or AGENTS.md?

Every obvious alternative fails in a specific way.

• An issue tracker is for work that anyone could pick up. HUMANS.md is the opposite: work that only one person can do. Issues also live outside the repo the agents are already reading and editing. A file in the working tree is free for every agent to write to, without API tokens or new permissions.
• TODO comments are scattered through the code and invisible until you grep for them. They describe code work, not "sign the Paid Apps agreement".
• AGENTS.md and CLAUDE.md are written by humans for machines. HUMANS.md runs the other way: machines write it, a human reads it. Mixing the two directions in one file is how a request ends up buried in instructions.
• The chat is where requests went to die. A report ends with "please approve the deploy", then the next report pushes it off screen.

The file also works as a boundary, not just a list. An agent with a clear place to say "I need a human for this" has less reason to improvise around a password prompt or a payment screen.

What it looked like on Canopy Run

In one day the file collected items from almost every agent. A sample, with the agent that added it:

The last row shows the file earning its keep. An audit found the site was running analytics that the privacy page said it didn't have. The agent didn't quietly fix it either way. It wrote the choice down, I picked "keep it and disclose it", and the privacy page was updated that afternoon.

HUMANS.md also became my status page. Its last section is a table of branches and what each one is waiting on. Most rows point back at a section of the same file.

What it isn't

• Not a security control. "Never do those things yourself" is an instruction, and instructions can be ignored or overridden by a prompt injection. Keep your real guardrails: permission prompts, scoped tokens, no secrets in the repo. HUMANS.md makes the honest path easy; it doesn't make the dishonest one impossible.
• Not a project manager. It doesn't prioritise across humans, assign owners or track estimates. For a team you'd want an owner per item, or a real tracker that the file links to.
• Not self-cleaning. Items go stale if nobody ticks them. In practice the agents tick items when I report something done, and the status table at the bottom exposes anything that has sat too long.

It's one file and one paragraph. That's the point: low enough cost that there's no reason not to try it.

Why the name: robots.txt in reverse

robots.txt is a file humans write to tell machines what not to do. HUMANS.md is a file machines write to tell humans what only they can do.

The file started as YOUR-TASKS.md, became HUMAN.md, and settled as HUMANS.md, plural like robots.txt. The .md matters too: it's Markdown, so the checkboxes tick in any editor or on GitHub.

Right now it isn't committed. I'm the only human on this codebase, so the file is a personal inbox rather than a team document. With collaborators, I'd commit it and give each item an owner.

Try it

Create HUMANS.md at your repo root, then add the convention paragraph above to every agent's instructions, or to your CLAUDE.md or AGENTS.md. A starting skeleton:

# HUMANS.md

Like robots.txt, but for the humans: the things on this project only a person can do.

## Blocking work right now
- [ ] (item, exact values, and what it unblocks)

## Accounts, money and sign-ins

## Taste calls

## Approvals (deploys, pushes, anything public)

## Where things stand
| Branch | What | Waiting on |
| --- | --- | --- |

Agents already ask for help. HUMANS.md gives the asking a place to land, and gives you one place to look when you sit down to work.

robots.txt worked because it was a dumb, obvious file in a predictable place that everyone agreed to respect. The same can be true going the other way. If your agents write a HUMANS.md, I'd like to hear what ends up in it.