Building Your CLAUDE.md Over Time: The Right Way

There is a mistake almost everyone makes with CLAUDE.md.

They sit down before starting a project and try to write a perfect, comprehensive file. They plan every preference, every rule, every instruction they might ever need. The file becomes long. It becomes theoretical. It does not match how they actually work.

Then a week later, they never update it because they set it and forgot it.

The better way is to start simple and grow through friction.

The principle

Your CLAUDE.md should grow from real problems, not imagined ones.

Every time Claude does something wrong that it keeps doing, that is a signal. Every time you have to correct Claude and then repeat that same correction in the next session, that is a signal. Every time you fix a painful problem that took hours to solve, that is a signal.

Each of those signals becomes one line in your CLAUDE.md.

Over time, your file becomes a record of everything Claude needs to know to work well with you, built from actual experience rather than theory.

The workflow

Step 1: Start with the basics.

In the previous lesson you wrote the six sections. That is your foundation. You have the essential context: what the project is, what has been built, what tools you are using, and your main preferences. That is enough to start building.

Step 2: Add when you have to repeat yourself.

Pay attention to moments when you say the same thing twice. If Claude adds Bootstrap and you remove it, then in the next session Claude adds Bootstrap again, that is not bad luck. That is a missing rule.

Add it to your CLAUDE.md: "Never use Bootstrap or any CSS framework."

Step 3: Add after painful debugging sessions.

When something breaks and takes two hours to fix, do not just fix it and move on. Document it.

For example: "When linking pages, always use relative file paths such as ./about.html, not absolute paths. Absolute paths break when the site is opened from a local folder."

Add it to your CLAUDE.md. The next time Claude works on your project, it will not make the same mistake.

Step 4: Ask Claude to update CLAUDE.md for you.

You do not have to open the file and edit it yourself. You can ask Claude directly.

Prompt:

• Add this to my CLAUDE.md: always use relative file paths when linking between pages. Absolute paths break when running the site locally.
• Claude will open the file and add the line. You described the rule and Claude did the writing.

How to view and edit your memory files

At any point in a session, type /memory and press Enter. Claude will show you a summary of all the memory files currently loaded including your global CLAUDE.md, your project CLAUDE.md, and any others. You can see exactly what Claude knows at that moment.

You can also use /memory to open and edit your memory files directly from within the session without leaving Claude Code to find the file manually.

What to do when you finish a difficult session

After any session where you ran into repeated corrections, unexpected mistakes, or painful back-and-forth, do this before you close.

Prompt:

What would you add to my CLAUDE.md based on what we ran into today?

Claude will suggest additions. Review them. Add the ones that make sense. Then start the next session smarter.

This is how your CLAUDE.md gets better with every build without any deliberate effort on your part.

The one thing to avoid

Do not let your CLAUDE.md become stale.

If you change your design direction, update the colours section. If you start using a different tool, update the tech section. If something you wrote three months ago no longer applies, remove it.

A CLAUDE.md that references outdated decisions or tools is worse than no file at all. It actively misleads Claude about what you want.

Review your CLAUDE.md every few projects and keep it current.

A quick check

Your CLAUDE.md is working well if Claude rarely has to ask you to clarify something it has already been told, if each new session feels like continuing with someone who already knows your project, if you rarely have to undo something Claude did because of a misunderstanding, and if the first response Claude gives you is already close to what you wanted without corrections.

If these things are not happening, your CLAUDE.md needs more specificity. Go back to the six sections and fill in the gaps.

Your action right now

Start a new Claude Code session in your project. Ask Claude to build one small new thing, whether that is a section, a page, or a feature.

Before the session ends, use this prompt:

Prompt:

• Based on this session, what would you add to my CLAUDE.md?
• Then add the suggestions that make sense to you.
• Move to the next lesson. We are going to cover sub-agents.
• Something not working as expected? Post in the community and tag Yar Malik.