Optional cookies help us improve Palette. Cookie policy

Skip to main contentAnnouncing our €3M pre-seed
Book a founder callDownload

Working with README.md files

Last updated:

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 can instruct supported agents across the workspace; a folder README is a reference for one folder.

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.

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

A folder README can list its sub-folders, so an agent or a teammate finds the right one fast:

# Foundations

What you're built on: the reference material that rarely changes. Ask agents
to read this before work that depends on the company's foundations.

## Subfolders

- **brand/:** voice, messaging, positioning. How you present yourself.
- **market/:** your ICP and competitors. Who you sell to and what you're up against.
- **strategy/:** where you're going and why.

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.

Go through this workspace and add a short README.md to every folder that
doesn't have one, starting at the top level and working into the main
sub-folders. Each README should say, in a few lines: what the folder is for,
what lives in it and how it's organized, any conventions specific to it, and
where to go next. When a folder has sub-folders, list them with a one-line
description each. Keep them scannable and match the style of the parent
folder's README. Guidance: https://palette.team/docs/palette-desktop-readme-and-index-files

To cover folders outside this workspace, add them as references first, then name them in the prompt.

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