3.2

Creating a Claude.md File

Your project's persistent memory

📄 Hands-On⏱️ ~15 minutes

Claude Code looks for a special file called Claude.md (or CLAUDE.md) in your project folder. If it exists, Claude reads it automatically at the start of every session. This is your project's persistent memory.

📄

Claude.md Starter Template

Ready-to-use markdown template for your projects

📄 Preview PDF
Download PDF

🎯 Why Claude.md Matters

Without Claude.md:

  • Every session starts with "Let me look at your project..."
  • You re-explain decisions and patterns each time
  • Claude might forget important context or constraints
  • You waste 5-10 minutes at the start of every session

With Claude.md:

  • Claude reads context automatically before you say anything
  • Sessions start with shared understanding
  • Patterns and decisions are remembered
  • You can start building immediately

✨ Automatic Context

The magic of Claude.md: every new session, Claude reads it first. You don't have to re-explain your project. Claude already knows the context, patterns, and preferences.

📄 What Goes in Claude.md

A Claude.md file typically includes:

  • Project overview: What this project is and does
  • Tech stack: Languages, frameworks, tools being used
  • Patterns: Code conventions and approaches used
  • Important decisions: Why things are done certain ways
  • Current status: What's working, what's in progress
  • Instructions: Your preferences for how Claude should work

📝 A Starter Template

Here's a simple template you can use:

# Project: [Name] ## Overview [One paragraph describing what this project does] ## Tech Stack - [Language/Framework] - [Libraries] - [Tools] ## Project Structure - `index.html` - Main page - `styles.css` - Styling - `app.js` - Application logic ## Patterns & Conventions - [How files are organized] - [Naming conventions] - [Code style preferences] ## Current Status - ✅ [Completed feature] - 🚧 [In progress] - 📋 [Planned] ## Notes for Claude - [Any preferences or instructions] - [Things to remember] - [Gotchas or known issues]

📚 Real Examples

Let's see what actual Claude.md files look like:

Example 1: Learning Activity Timer

# Project: Learning Activity Timer

## Overview
Simple timer to track time spent on e-learning development tasks. Helps identify where time goes during course creation.

## Tech Stack
- Vanilla JavaScript (no frameworks)
- localStorage for persistence
- Single HTML file for simplicity

## Project Structure
- `index.html` - Timer interface
- `timer.js` - Timer logic, storage
- `styles.css` - Clean, minimal styling

## Patterns
- Use localStorage with JSON.stringify/parse
- Always confirm before clearing data
- Format time as HH:MM:SS

## Current Status
✅ Phase 1: Basic start/stop timer
✅ Phase 2: Task naming and history
🚧 Phase 3: Visual time breakdown (in progress)

## Notes for Claude
- Keep it simple - no external dependencies
- Always add confirmation for destructive actions
- Test localStorage persistence after changes

Example 2: Stakeholder Feedback Tracker

# Project: Feedback Tracker

## Overview
Centralizes stakeholder feedback from emails, Slack, meetings into one trackable list.

## Tech Stack
- HTML/CSS/JS
- localStorage (no backend yet)
- PapaParse for CSV export (future)

## Data Model
Feedback object: { id, text, source, date, section, status }
Status values: "open", "addressed", "wontfix"

## Important Decisions
- Using UUID for feedback IDs (not auto-increment)
- Sections map to course modules ("Module 1", "Module 2", etc.)
- Date stored as ISO string for sorting

## Current Status
✅ Phase 1: Add feedback items
✅ Phase 2: Tag by section, filter view
📋 Next: Export to CSV, edit existing items

⚡ Pro Tip: Start Small, Add as Needed

Your first Claude.md can be just 5 bullet points. As you encounter questions or patterns, add them. It grows organically with your project.

✅ What to Include

Good Additions to Claude.md

Project purpose: Why this exists, what problem it solves
Tech choices: Languages, frameworks, why you chose them
File organization: What each file does, how they relate
Data structures: How you're modeling information
Patterns: Code conventions you want Claude to follow
Decisions: Why you did X instead of Y (saves re-explaining)
Known issues: Bugs or limitations to work around
What's next: Planned features or improvements

❌ What NOT to Include

  • Actual code: Claude can read your code files. Don't duplicate code in Claude.md
  • Obvious stuff: "This is a web app" - Claude can figure that out
  • Everything about every detail: Focus on what Claude needs to work effectively
  • Your diary: "Today I felt frustrated..." - keep it project-focused

🚀 Creating Your First Claude.md

Let's create one. In your project folder, ask Claude:

"Create a Claude.md file for this project. Look at the existing files and structure, then document: - What the project is - What technologies we're using - How the files are organized - Any patterns you notice"

Claude will analyze your project and create a starting Claude.md. Review it, then refine.

✏️ Activity: Create Your Claude.md

If you have a project started, create its Claude.md now:

🎯 Build Your Project Memory

Start in your project folder:
Open Claude Code in your project directory. If you don't have a project yet, that's okay—read through and apply this when you do.
Ask Claude to create Claude.md:
"Create a Claude.md file for this project. Look at the existing files and structure, then document: what the project is, what technologies we're using, how files are organized, and any patterns you notice."
Review what Claude wrote:
Read through the generated Claude.md. Is anything missing? Is anything wrong?
Add your context:
Claude can't know everything. Add:
• Why you made certain decisions
• Patterns you want to follow
• Things to remember for next time
• Known issues or constraints
Test it:
Start a new Claude Code session. Does Claude reference the Claude.md context? You should see it "remember" things without you explaining them.

✅ Success Check

You'll know your Claude.md is working when: you start a new session and Claude already understands your project structure and patterns without you explaining anything.

✨ Living Document

Claude.md isn't "set and forget." It evolves. After each session where you learn something important or establish a pattern, update Claude.md. That's the "Compound" step.

🔄 Keeping It Updated

Claude.md should evolve with your project. At the end of significant sessions:

"Update Claude.md to reflect what we just built and any new patterns we established."

This is part of the "Compound" step in the 4-step loop.

Good times to update Claude.md:

  • After adding a major feature: Document what was added and any new patterns
  • After making an important decision: "We chose X over Y because..."
  • After discovering a gotcha: "Remember: localStorage has a 5MB limit"
  • After changing direction: "We switched from approach A to B"
  • When starting a new phase: Update "Current Status" section

⚡ Pro Tip: Let Claude Update It

At the end of sessions: "Update Claude.md to reflect what we built today and any patterns we established." Claude can write the updates—you just review and approve.

💡 Don't Overthink It

Your Claude.md doesn't need to be perfect. Even a few bullet points help. You can always add more detail as the project grows.

📚 Resources & Further Reading

💭 Pause & Reflect

Before moving on, take a moment to consider:

  • If you have a project, what's one thing that would be valuable to document in Claude.md?
  • What typically gets forgotten between sessions that Claude.md could remember?
  • How is this different from comments in your code?

🎯 Claude.md Created

You know how to give your project persistent memory. Next: what to document and when.

Topic 3.2 Complete • Up Next: 3.3 – Documenting Learnings