Third time this week, you’re telling your AI assistant the same thing. That you write in Polish. That the folder holds material nothing may change without asking. That you want short headings in tables, not sentences.

All of it can be said once and written into a place Claude Code looks at whenever a chat starts. The file is called CLAUDE.md, it’s plain text – and you won’t be writing it by hand. Claude Code will, after a short conversation with you. The rest of this lesson is checking that CLAUDE.md actually works, because the file merely existing gives you no certainty at all.

Nothing needs to be learned beforehand. There’s no syntax to memorize and nothing here that can be typed wrongly and break something.

If you use claude.ai, ChatGPT or Perplexity, you may know the field for telling the AI about yourself – “custom instructions”, “personalization”, “about me”. CLAUDE.md works on the same principle, it just sits in your folder instead of in a service’s settings. If you already have instructions written somewhere, you can simply copy them into CLAUDE.md and they’ll work. We’ll still go through building one from scratch here, because it’s worth seeing once where every line in that file comes from.

Why this file exists at all

At the start of every chat, Claude Code holds no data from earlier conversations. It doesn’t know what was explained to it yesterday, or that the conversation happened at all. Every chat starts from nothing.

CLAUDE.md is the answer to that limit. It’s the file Claude Code reads first thing when a chat starts. Everything in it enters the conversation before you write a word.

One thing up front, to save disappointment later: this is an instruction, not a system setting. Claude Code reads the file and goes by it, but it isn’t a technical block that forbids anything. The more concretely you write something, the more reliably it gets applied – and we’ll come back to that.

Memory documentation

Let Claude write this file

Don’t open an editor. Go to the folder you work in, run claude, and ask for the file – together with a request for an interview:

Create a CLAUDE.md file in this folder. Before you write it, ask me a few questions about who I am, what I do, and how I want to work with you.

Claude Code will start asking, one question at a time. Answer briefly, in ordinary sentences – the way you’d talk to a person who’s about to become your new assistant and has just started their first day. Worth getting out of that conversation:

  1. Who you are and what you do – “I run a small accounting practice”, “I make graphics for clients”.
  2. What language you want to work in – if it’s Polish, say so outright.
  3. What’s in this folder and what may not be touched without asking.
  4. What you don’t know and don’t intend to learn – “I’m not a programmer, explain technical things in plain language” is one of the most useful things you can tell it.
  5. How it should write – worth cutting two habits here straight away, the ones that give AI text away from a distance: too many emoji, and long dashes in the middle of a sentence. “No emoji” and “no long dashes” do the job.

If Claude asks something you don’t have an answer to, say so. This isn’t a test and there are no wrong answers.

When Claude Code is done asking, it writes the file itself and tells you it’s ready. Format, ordering, headings – its business. It’s writing a file it will read every day, so it will lay it out in the shape that suits it best.

Look inside, it’s just plain text

Now the most important part of this lesson: see for yourself that there’s no magic in it.

Open the file in a basic text editor – Notepad on Windows, TextEdit on macOS. You’ll see ordinary sentences, roughly like this:

# About me and this work

- My name is Anna and I run a small accounting practice.
- Let's talk in Polish.
- This folder holds letter templates and document boilerplate.
- I'm not a programmer. Explain technical things in plain language.

CLAUDE.md is nothing encrypted, nothing you couldn’t read. You can go through it whenever you feel like it – it’s yours.

The file has to be called exactly CLAUDE.md: capitals, with the md extension. Claude Code won’t read anything else. So watch out when saving from Notepad, which likes to append its own extension and turn it into CLAUDE.md.txt – the file stays on disk, but Claude Code won’t find it. In the conversation itself that precision isn’t needed: type “edit claude md” and Claude will work out what you mean.

Note what isn’t in the file: a list of files, which Claude Code sees for itself when it looks in the folder. What belongs in there is what can’t be read off the directory’s contents – your preferences, your context, your boundaries. Folder structure is the useful exception: when the folders are called 01_current and 02_templates, one sentence about what lives where saves the AI from guessing.

Short beats long. The documentation suggests staying under two hundred lines, and that isn’t arbitrary: the longer the file, the more room it takes up in the conversation’s memory and the less closely Claude Code sticks to it.

The file sits directly in the project folder, and that’s where we’ll leave it today. There’s also a personal version, ~/.claude/CLAUDE.md, applying across all your projects at once – but start with one project, so you see the effect on something small.

Memory documentation

Add one instruction, a concrete one

Now the most important part of the exercise. Add one instruction to the file that Claude Code should always follow – phrased so you can check whether it was applied.

A good instruction differs from a bad one in how specific it is:

  • Weak: “write properly”, “maintain quality”, “be thorough”.
  • Good: “always write dates as DD.MM.YYYY”, “answer in five sentences at most unless I ask for more”.

An instruction from the first group doesn’t tell the AI what to do differently. One from the second does – and you can see with your own eyes whether it worked.

Avoid instructions phrased as a prohibition. “Never look into the archive folder” sounds firm, but it works the opposite way round to how it reads: the sentence itself brings that folder into the conversation, and Claude has to keep it in view the whole time in order to avoid it. Try, for a moment, not to think about a pink elephant – and you already know what the problem is. Write what Claude Code should do instead of what it shouldn’t: “work only on files in the current folder”.

For this lesson, pick something easily visible. A date format works beautifully. Type this into the chat in your terminal:

Add this instruction to CLAUDE.md: always write dates as DD.MM.YYYY.

Check that Claude Code really sees it

Verifying is the step most people skip, and without it you don’t know whether anything works.

Start with a new chat: close Claude Code and run claude again. This isn’t a formality, for two reasons. In the previous conversation Claude Code knew what was in the file because it had just written it – that proves nothing about it being read. And CLAUDE.md is read only at the start of a chat: go back to a conversation opened earlier and the old version of the file still applies there, even with the new one saved on disk.

In the new chat, ask something that forces your instruction into play:

Write one sentence containing today's date.

If the date arrives as DD.MM.YYYY, the file is working. You can also ask outright:

What do you know about me from the CLAUDE.md file?

And now the best proof that it really is this file steering the answers: change the date format in it to YYYY-MM-DD, open another new chat, and ask the same date question. The format should change. If it does, you know the file is read afresh every time rather than memorized once and for all.

When an instruction gets ignored

It happens, and it doesn’t mean you did something wrong.

Before you fix anything, do the thing that pays off in every conversation with AI, not just with this file: ask why it did that.

Why did you write the date in this format when CLAUDE.md says otherwise?

Getting annoyed at the AI achieves nothing, while that question usually leads straight to the cause – and the cause is most often how the instruction was worded. What you get back is something concrete: that the file wasn’t in the folder the conversation was launched from, that two instructions say different things, or that this one could be read differently than it was meant.

Two causes come up most often in that answer:

  1. The instruction isn’t concrete – “be concise” is a wish; “five sentences at most” is an instruction, because only the second one lets you see with your own eyes whether it was applied.
  2. Two instructions contradict each other – when the file holds conflicting orders, Claude Code applies one of them and you won’t know which.

Fix the file, open a new chat, and check again. That’s the normal working cycle with this file, not a sign of failure: our own first version is almost never the last one either.

Memory documentation

One more thing worth knowing, though you don’t need it today: the /init command. With it, Claude Code goes through the folder’s contents and writes CLAUDE.md itself, based on what it finds there – without asking you anything. It’s useful when the folder already holds a lot of material and you want Claude Code to describe it. A separate lesson walks through that.

Today this file came out of a conversation, and that was a deliberate choice: everything in it came from you, and Claude Code only gave it a shape.

Tasks

Tick these off as you go. The state is remembered in your browser, so you can come back to this list tomorrow.

  • Claude Code ran the interview and wrote CLAUDE.md
  • File contents looked at in a basic text editor
  • One concrete instruction added that I can check
  • New chat opened, check question asked
  • Date format changed and verified in another chat
  • I know I can ask outright why an answer came out wrong