README.md is not a universal agent-instruction filename. Link important READMEs from CLAUDE.md or AGENTS.md, or point the agent to the relevant file in your prompt.
Why folder READMEs help
- Agents can use the relevant README when you link or point them to it, so you need less explaining.
- New teammates get oriented without asking.
- The folder documents itself, so it stays useful as it grows.
What to put in a folder README
- What this folder is for, in a sentence.
- What lives here and how it is organized.
- Any conventions specific to this folder.
- Where to go next.
Example
Add READMEs where a folder needs explanation. Here is a slice of a go-to-market workspace in which parent READMEs point to what is below them.Set it up across your workspace
You do not have to write these by hand. Give your agent a prompt like this, and it will do the whole tree in one pass while you review before it saves.Keeping them current
Ask your agent to update the README when the folder changes, the same way you keep CLAUDE.md and AGENTS.md sharp.Related
- Working with CLAUDE.md and AGENTS.md, the same idea for the whole workspace
- Structuring your workspace, how the folders fit together
