How to organize Claude MD and Agents MD files
Claude MD and Agents MD files are used to help an AI agent recover important project context. There are three main setup choices.
One approach keeps a single Claude MD file at the project root with broad instructions. Another adds Claude MD files inside folders, so each part of the project can explain its own details, while the root file points to them.
A third approach keeps a separate docs folder where important decisions and session context are added over time. The best setup may depend on the size of the repo and how complicated its structure is.
Key points
- Claude MD and Agents MD files help an AI agent recover project context.
- A single root file is simple, but may not cover folder-level details.
- Folder-level files can explain local rules for different parts of a repo.
- A separate docs folder can store decisions and context from past sessions.
- Larger repos may need more structure, but extra context can increase token use.
Quick term guide
- Claude MD
- A file used to give Claude or related tools project rules and working instructions.
- Agents MD
- A file used to give AI agents instructions they should follow while working.
- AI agent
- An AI program that can inspect information and suggest what to do next.
- project context
- The background an AI tool needs, such as the goal, files, decisions, and current task.
- takeaway
- The main practical lesson to remember or act on.
- Context Files
- Files or folders you give to the assistant so it can read and use them in a chat.
- context file
- A file that gives the AI background information or rules to follow.
- sessions
- Separate work threads or task runs inside a tool.