🧠 Module 4 of 10 18 min read Phase 2: Core Skills

The Memory System

Teaching Claude Code Your Codebase and Preferences

▶

Video Lesson Coming Soon

A video walkthrough for this module is in production. For now, dive into the written content below.

What You'll Learn

✓ Why memory matters for consistency
✓ The three memory layers
✓ Writing a great CLAUDE.md
✓ What to include (and what to skip)
✓ User memory and personal preferences
✓ Auto-memory and the /memory command
✓ The .claude/rules/ directory for teams

In this module 6 sections

Why Memory Matters

Without memory, every Claude Code session starts from zero. It does not know your project uses TypeScript. It does not know you prefer functional components. It does not know your tests run with Vitest. It does not know you hate semicolons.

With CLAUDE.md, Claude Code knows all of this before you type a single word. Every conversation starts smarter. Every suggestion matches your style. Every command it runs uses your preferred tools.

CLAUDE.md is a plain markdown file that lives in your project root. Claude Code reads it at the start of every session and uses it as a reference throughout the conversation. It is the single highest-impact thing you can do to improve your Claude Code experience.

The Three Memory Layers

Project Memory — CLAUDE.md in your project root

This is where you put conventions for this specific project. Tech stack, coding style, test commands, file structure, naming patterns. Every developer who uses Claude Code on this project gets the same instructions. Check this file into git so the whole team benefits.

User Memory — ~/.claude/CLAUDE.md

This is where you put your personal preferences that apply across all projects. Things like "I prefer concise explanations" or "Always show the full function when editing, not just the changed lines." These preferences follow you everywhere.

Team Rules — .claude/rules/ directory

For larger teams, you can organize rules into topic-specific files inside .claude/rules/. For example: testing.md for test conventions, security.md for security requirements, api.md for API design patterns. Rules can even target specific file paths using YAML frontmatter.

🧠

Memory Hierarchy

Memory is hierarchical. Project-level rules take priority over user-level rules. This means a project can enforce its own conventions even if your personal preferences differ. The order is: Enterprise/managed policy > Project CLAUDE.md > User CLAUDE.md.

Writing a Great CLAUDE.md

A good CLAUDE.md is short, specific, and actionable. It is not a novel about your project — it is a cheat sheet. Aim for under 200 lines. Include only what Claude Code cannot figure out by reading your code.

CLAUDE.md — Example

# Project: My Web App

## Tech Stack
- Framework: Next.js 14 with App Router
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- Testing: Vitest + React Testing Library
- Package manager: pnpm

## Code Style
- Use functional components, never class components
- Prefer named exports over default exports
- Use const arrow functions for components
- No semicolons
- Single quotes for strings

## Commands
- Run tests: `pnpm test`
- Run dev server: `pnpm dev`
- Lint: `pnpm lint`
- Type check: `pnpm tsc --noEmit`
- Build: `pnpm build`

## File Structure
- API routes: src/app/api/
- Shared components: src/components/
- Utilities: src/lib/
- Types: src/types/

## Important Rules
- Always add error boundaries around async components
- Never import from @internal packages in public APIs
- All API endpoints must validate input with Zod

What to Include in CLAUDE.md

✓ Tech stack and versions — frameworks, languages, package managers

✓ Common commands — how to test, build, lint, deploy

✓ Code style rules — formatting, naming, import conventions

✓ File structure — where components, utilities, and tests live

✓ Naming conventions — how files, functions, and variables should be named

✓ Testing patterns — which test runner, how to write tests, minimum coverage

✓ Things to avoid — anti-patterns, deprecated APIs, forbidden packages

✓ Project-specific terminology — domain terms that Claude Code might not know

💡

What NOT to Include

Do not put things in CLAUDE.md that Claude Code can figure out by reading your code. It can already see your package.json, your tsconfig.json, and your file structure. Only include things that are not obvious from the code itself — like your team's preferred patterns or explicit rules about what to avoid.

Auto-Memory and the /memory Command

Claude Code can automatically save things to memory during your conversations. When you say something like "remember that we use pnpm" or "save this: always run lint before committing," Claude Code stores it for future sessions.

These auto-memories are saved in ~/.claude/projects//memory/. The /memory command lets you view and edit them.

Auto-memory is useful for things that come up during work — conventions you discover, debugging insights, architecture notes. But for important, permanent rules, put them directly in CLAUDE.md where they are visible and version-controlled.

The .claude/rules/ Directory

For teams with many conventions, a single CLAUDE.md can get unwieldy. The .claude/rules/ directory lets you split rules into modular, topic-specific files.

.claude/rules/testing.md

---
paths:
  - src/**/*.test.ts
  - src/**/*.spec.ts
---

# Testing Rules

- Use Vitest for all tests
- Use React Testing Library for component tests
- Mock external APIs, never hit real endpoints in tests
- Each test file must have at least one describe block
- Use meaningful test names: "should [expected behavior] when [condition]"

ℹ️

Path-Specific Rules

Notice the paths: frontmatter in the example above. This means these rules only load when Claude Code is working with test files. This saves context space — Claude Code does not need to think about testing rules when it is editing a configuration file.

Key Takeaways

CLAUDE.md is the single most impactful file in your Claude Code workflow — it makes every session start with full project awareness

Three memory layers (project, user, team rules) create a hierarchy where project-specific rules take priority

A good CLAUDE.md is under 200 lines and includes tech stack, commands, code style, file structure, and rules

Auto-memory saves conventions discovered during work; .claude/rules/ lets teams organize rules by topic

📝 My Notes▼

← Essential Commands Plan Mode →