Working with README.md files

A README (or index) file is a short note at the top of a folder that explains what the folder is for and where things live. CLAUDE.md and AGENTS.md do this for the whole workspace; a folder README does it one level down, for a single folder.

Why folder READMEs help

• Agents read the nearest README when they work inside a folder, so they need less explaining each time.
• 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

READMEs work best when every folder has one, all the way down. Here is a slice of a go-to-market workspace. Each folder explains itself, and a parent README points to what is below it.

gtm-workspace/
├── README.md                  # what this workspace is
├── foundations/
│   ├── README.md              # what you know: brand, market, strategy
│   ├── brand/
│   │   └── README.md          # voice, messaging, positioning
│   ├── market/
│   │   └── README.md          # your ICP and competitors
│   └── strategy/
│       └── README.md          # where you're going and why
└── accounts/
    ├── README.md              # one folder per customer
    ├── acme-corp/
    │   └── README.md          # the Acme account context
    └── globex/
        └── README.md          # the Globex account context