Lesson 20: Rules & Memory

Day 20 of 50 · ~7 min read · Phase 3: Customization

The Opening Question

You've been working with Claude Code across several conversations and projects. Each time Claude starts a new conversation, it begins fresh — it doesn't "remember" what you told it before.

This is mostly good (privacy, cleanliness). But it also means you have to re-explain your project's patterns, conventions, and preferences every time.

Here's the question: How does Claude learn from experience across sessions?

And more practically: How can you teach Claude about your project so it gets smarter over time?

Discovery

Let's explore how memory and learning work in Claude Code.

Question 1: What's the difference between remembering and learning?

There are two related but different things here.

Remembering is about recalling specific details: "You told me this project uses Tailwind CSS instead of Bootstrap. Remember that."

Learning is about inferring patterns: "I see you consistently use async/await instead of callbacks. I'll do that too."

Claude Code handles both, but in different ways.

Pause and think: If Claude had to be told everything about your project every session, what information would be most painful to repeat?

For many developers, it's things like:

• Code style and conventions
• Project structure and where things go
• Technology choices and preferences
• Testing patterns and where test files live
• Debugging techniques for your specific stack
• Common build commands and what they mean

These are patterns, not one-off decisions. Telling Claude once and having it stick would be powerful.

Question 2: What are rules, and how do they differ from CLAUDE.md?

You've learned about CLAUDE.md (Lesson 17) — a global file that documents your project's conventions for Claude.

Rules are similar but scoped differently.

CLAUDE.md is global to your entire codebase. It says: "For any work in this project, here's what you need to know."

Rules are path-scoped. They live in .claude/rules/ and apply only to specific directories. They say: "For work in this directory, here are the special conventions."

For example:

.claude/rules/
├── api/
│   └── api.rules.md        # Rules specific to /api directory
├── components/
│   └── components.rules.md # Rules specific to /components directory
└── tests/
    └── tests.rules.md      # Rules specific to /tests directory

The file .claude/rules/api/api.rules.md might say:

# API Directory Rules

## Code style
- Use async/await for all database calls
- Always validate input with zod schemas
- Return error responses as { error: string }

## Testing
- Every endpoint needs a test
- Mock the database connection
- Test both success and error cases

Now, when Claude works in the /api directory, it reads these rules automatically. It doesn't apply them when working elsewhere.

Why does path-scoping matter?

Because different parts of your project might have different conventions. Your frontend components might follow React-specific patterns. Your backend might follow Node.js patterns. Your database migrations might follow yet another pattern.

Path-scoped rules let Claude adapt to each context.

Question 3: How does auto-memory work?

Beyond rules you explicitly write, Claude Code also learns automatically.

There's a .claude/memory directory where Claude records patterns it observes. For example:

• "In this project, tests are in __tests__ directories, not test/"
• "Build commands are: npm run build, npm run test, npm run dev"
• "The main entry point is in src/index.ts, and the output is in dist/"
• "When I see an error about ENOENT, it's usually a path issue"

Claude builds this memory over time as it works on your project. It's cumulative — across sessions, Claude gets better at understanding your specific setup.

You don't explicitly write this memory. Claude creates it. But you can inspect it and guide it.

For example, if Claude gets something wrong repeatedly, you might add to .claude/memory:

# Debugging Patterns

## Issue: Import errors with absolute paths
When I see "Cannot find module '@/utils'", check:
1. tsconfig.json paths configuration
2. Build output location
3. Whether the build is fresh

The solution is usually: `npm run build` then `npm run dev`

Now Claude won't make that mistake again.

Question 4: When do you use rules vs. memory vs. CLAUDE.md?

This is practical: when should you write what?

Use CLAUDE.md when:

• The information applies to the entire project
• It's a policy or convention everyone should follow
• It's foundational knowledge about the project
• Example: "We use TypeScript. All code is type-safe. No any types."

Use rules when:

• The information applies only to a specific directory or feature
• Different parts of the project have different conventions
• You want to keep the documentation close to the code
• Example: "The /api directory uses these validation patterns"

Use memory when:

• Claude has learned a pattern and you want to reinforce or correct it
• You're documenting a solution to a problem Claude encounters repeatedly
• You want to teach Claude about your specific debugging patterns
• Example: "When deployment fails, always check the environment variables file"

Pause and think: What's in your head about this project that Claude doesn't know? Which category does it fall into?

The Insight

Here's the core idea:

Claude Code learns from every conversation you have, building cumulative knowledge about your project's patterns, conventions, and debugging techniques. You can guide this learning by writing explicit rules for different directories, documenting patterns in memory, and providing global context in CLAUDE.md. Over time, Claude becomes better at understanding your specific codebase without needing to be told the same things repeatedly.

The mental model: Rules and memory work like institutional knowledge. When someone joins a team, the senior developers tell them: "Here's how we do things in this company" (CLAUDE.md), "Here's how we do things in this department" (rules), and "Here's what we've learned the hard way about debugging our systems" (memory). Claude accumulates this same knowledge, getting smarter and more effective over time.

Try It

Let's set up rules and memory for your project.

1. Create the rules directory:

   mkdir -p .claude/rules
   

2. Write rules for your main directory. Pick a directory (like /src or /app) and create:

   cat > .claude/rules/src.rules.md << 'EOF'
   # /src Directory Rules
   
   ## Code style
   - [Write your style conventions here]
   - Example: "Functions use camelCase"
   - Example: "Import statements sorted alphabetically"
   
   ## Testing
   - [Where tests live and how to write them]
   
   ## Common patterns
   - [Patterns you see repeatedly]
   EOF
   

3. Create a memory file for your project:

   mkdir -p .claude/memory
   cat > .claude/memory/debugging-patterns.md << 'EOF'
   # Debugging Patterns
   
   ## Common errors and fixes
   - [Error pattern]: [What to check]
   - Example: "Module not found → check build output is fresh"
   
   ## Build steps
   - Describe the build process
   - What commands do what
   EOF
   

4. Test it. Start a conversation and ask Claude to work in the directory where you added rules:

   claude
   

   Then ask Claude to make a change. Watch how it references the rules automatically.

5. Guide Claude's learning. If Claude makes the same mistake twice, add it to memory:

   echo "## Issue: [What Claude did wrong]" >> .claude/memory/debugging-patterns.md
   echo "Solution: [The fix]" >> .claude/memory/debugging-patterns.md
   

Key Concepts Introduced

Bridge to Lesson 21

You've now taught Claude about your project through rules and memory. But here's a bigger question:

What if you could package these learnings — rules, commands, memory — into a reusable bundle that you could share with your team or use in other projects?

Tomorrow's question: What if your best prompts and workflows could be saved and shared?

We'll explore skills — reusable packages of knowledge and instructions that you can create, refine, and share.

← Back to Curriculum · Lesson 21 →