This lesson's interactive features are locked, please to keep using them
AGENTS vs. README
Should you put your project info in AGENTS.md or README.md?
The answer is "both"... but please don't repeat yourself. The files can simply reference each other!
README Is for Humans
Your README.md is documentation for humans. Sometimes that's other maintainers, but sometimes it's just users! In many projects it doubles as a landing page on GitHub.
It can be long, include narrative, have badges, screenshots, installation steps, a changelog link – whatever humans want to know at a glance about the project.
An agent can read it, but you should only instruct it to read it on an as-needed basis.
AGENTS Is for Clankers
AGENTS.md is loaded into the system prompt in every single session. Every token in it has a recurring cost, and it competes with your actual prompt for attention, so keep it tightly scoped.
| Content | README | AGENTS | Other |
|---|---|---|---|
"Always use slog, never fmt.Println" |
X | ||
"Run tests with go test ./..." |
X | ||
"NEVER USE .then OVER await YOU CRAZY BOT" |
X | ||
| Setup instructions for new human devs | X | ||
| "To install this program locally..." | X | ||
| API endpoint documentation | docs/api.md |