What Is CLAUDE.md: And How Claude Reads It

CLAUDE.md is a plain text file you place in your project folder.

The name is not flexible. It must be written exactly as CLAUDE.md with all letters uppercase followed by .md. Not claude.md, not Claude.md, not CLAUDE.MD. Claude Code looks for this exact name. If the capitalisation is different, it will not be found and it will not be read.

What happens when Claude sees it

Every time you open a Claude Code session inside a project folder, Claude automatically looks for a CLAUDE.md file. If it finds one, it reads the entire file before the session begins, before you have typed anything at all.

The contents get loaded directly into Claude's working context at session start. It is not a separate step you need to take. You do not have to paste it in or remind Claude it exists. Claude finds it and reads it automatically every single time.

The contractor analogy

Think about what happens when you hire a contractor for a renovation job.

If you hand them a proper brief before they arrive, covering what the project is, your preferences, what has already been done, what mistakes to avoid, and your budget and timeline, they can make good decisions from the very first hour. They do not need to ask basic questions. They already know.

If you hand them nothing, the first morning is spent figuring out what they are even doing.

CLAUDE.md is that brief. You write it once and every future session with Claude starts with Claude already fully informed.

What it looks like

A CLAUDE.md file is just plain text with some basic formatting. Here is an example showing the format. Use this as a reference for structure only. Your own file should contain your real project details, not these placeholder ones.

My Portfolio Website

About This Project:

• This is a personal portfolio website for a freelance photographer.
• Target audience: potential clients in Dubai looking for event photography.

What Has Been Built:

• Homepage with hero section and about section.
• Gallery page with 12 photos.
• Contact form (currently not connected to anything).

Design Preferences:

• Dark background, clean and minimal.
• Font: system fonts only, no Google Fonts.
• Colour: deep navy with white text and gold accents.

How I Like to Work:

• Keep code simple. I am not a developer.
• No JavaScript unless absolutely necessary.
• Ask me before adding any new files or libraries.
• Never delete anything without telling me first.

What Not to Do:

• Never use external CSS frameworks like Bootstrap or Tailwind.
• Never add animations unless I specifically ask.

This is the entire file. Plain text, short sentences, clear sections. No programming knowledge required to write it.

You do not need to know Markdown

CLAUDE.md uses Markdown formatting where headings use a hash symbol and bullet points use a dash. But you do not need to know Markdown to write one. Plain sentences work fine. Bullet points are helpful. Short paragraphs work. If you can write a document, you can write a CLAUDE.md.

Your action right now

Open the project folder you built in the Foundations course. Confirm you know exactly where the root folder is. That is where your CLAUDE.md file will live in the next lesson.

Move to the next lesson. We are going to look at the two levels of memory and what goes where.

Questions? Post in the community and tag Yar Malik.