Lesson 1.2 · 35 minProject memory: CLAUDE.md

What you will have

The project has a short CLAUDE.md file at its root, committed to Git, and the student has proved that a brand-new session answers from it without being told anything.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 1 — Why Claude forgets

What is the name of the business this project is for, and where do I keep practice files?

Do along

Work on your own project and pause the video where the steps say.

1. Pause after Part 1. In your project folder, start claude and ask the Part 1 question. Note how Claude answers without a memory file.
2. Pause after Part 2. Run /init. Approve creating CLAUDE.md if asked. Open the file in your editor and read what was generated.

3. Pause after Part 4. Edit the file by hand so it has the five sections: Purpose, Stack, Commands, Conventions, Rules. You may start from the lesson's version. Adapt:

   • Purpose: if you already know your own business, you may write it here. Otherwise keep Brightside Cleaning; you will revise this in lesson 2.1.
   • Rules: keep the three rules from the lesson and add one of your own that could be checked. For example: "Write all page text in British English."
   • Keep the "checkpoint please" rule exactly; later lessons use it.
4. Save the file. Check its length: it should fit on one screen.
5. After Part 5. Exit Claude Code and start a new session. Run /context and find CLAUDE.md under "Memory files".
6. Ask the Part 5 question. Then test the rule you added with a question only that rule can answer.
7. Type checkpoint please. Claude should run git status, describe the changes (the new CLAUDE.md), and wait. Reply:

OK. Commit with the message "Lesson 1.2: add CLAUDE.md" and push.

Check your work

1. Run ls (macOS) or dir (Windows) in the project folder. Expected: CLAUDE.md is listed at the top level, spelled in capitals.
2. Start a new session and run /context. Expected: CLAUDE.md appears under "Memory files".
3. In that new session, before anything else, ask: Where do practice files go, and what happens when I say "checkpoint please"? Expected: the correct answer, with no file searching first.
4. Run git log --oneline -3. Expected: the top commit is "Lesson 1.2: add CLAUDE.md".
5. Open the repository on GitHub. Expected: CLAUDE.md is visible there.

Common problems

• The new session does not know the rules. → The file is misnamed (claude.md, Claude.md.txt), in the wrong folder, or you started claude from a different folder. → Run /context and look under "Memory files". Rename or move the file to the project's top level and start a new session from that folder.
• You edited the file but Claude still uses the old version. → The session started before your edit. → Start a new session.
• /init wrote a long file full of obvious things. → It describes what it found. → Delete what Claude could work out by reading the files, and keep what only you know.
• /init asks a series of setup questions instead of writing a file. → The interactive flow is switched on in your setup. → Choose the CLAUDE.md option and continue, or write the file by hand from the lesson's version. Both give the same result.
• Claude follows a rule sometimes and ignores it other times. → The rule is vague, or the file is too long. → Rewrite the rule so it can be checked, and cut lines that do not prevent mistakes.
• Two rules contradict each other. → Claude may pick either. → Remove one. Check your personal ~/.claude/CLAUDE.md as well, if you have one.
• You put a password or key in the file. → Remove it, commit, and change that password or key at its provider, because Git keeps history.

Homework

About 20 minutes, after the lesson. Nothing later depends on it. Notes go in practice/homework/1.2/; at the end, commit with checkpoint please and the message "Homework 1.2" (no tag).

1. Vague to checkable. In rules.md, rewrite these four vague rules so each could be checked on a finished page: "Be careful with content." "Make it look professional." "Keep it short." "Use good English." Then add two rules your own business would need. Leave them out of CLAUDE.md for now; your business is settled in lesson 2.1. Done when: for all six, a stranger could look at a page and say "followed" or "broken".
2. The delete test. Go through your CLAUDE.md line by line. In delete-test.md, write "keep" or "cut" for each line, and why. Then cut only what /init generated and Claude could work out from the files. Keep the Conventions and the Rules, above all "checkpoint please". Done when: every line has a verdict, and step 3 of Check your work still passes in a new session.
3. A personal file. Ask Claude to create ~/.claude/CLAUDE.md with two or three preferences about how it talks to you, for example "Explain in plain language and define each technical term." Nothing about the project, and nothing that contradicts the project file. It lives outside the project, so there is nothing to commit. Done when: a new session, asked "Which personal preferences of mine do you know?", lists them.