Think of CLAUDE.md as your project's personalized README for Claude. This markdown file, located at the root of your project, serves as a comprehensive guide that Claude reads at the start of every session. It outlines your project's architecture, coding conventions, and critical rules, ensuring that Claude's actions align with your specific requirements.

Example: With and Without CLAUDE.md

You: "Add a new API route for user profiles"
Claude: *creates a generic Express.js route with console.log*

You: "Add a new API route for user profiles"
Claude: *creates a Next.js API route using Clerk auth, Convex queries, and lib/logger.ts—matching your exact stack*

With CLAUDE.md, Claude tailors its actions to your tech stack, authentication methods, and logging practices.

A well-crafted CLAUDE.md should include:

1. Tech Stack and Architecture: Specify frameworks, databases, and authentication providers.
2. Code Conventions: Define naming conventions, file structures, and import patterns.
3. Critical Rules: Highlight non-negotiable practices, such as avoiding console.log in production.
4. Common Tasks: Describe deployment processes, testing protocols, and feature addition guidelines.

Real-World Example from vybecoding.ai

```markdown

• Database Queries: Use npm run convex:prod (NEVER export CONVEX_DEPLOYMENT=...)
• Logging: Use lib/logger.ts not console.log in production code
• Content: ONLY use /content command for content operations
• Testing: Always run npm run playwright:cleanup after tests

As your project grows, so should your CLAUDE.md. Organize it with clear sections and a quick-reference header to ensure essential rules are easily accessible:

```markdown

Claude Code Development Guide

• Platform: vybecoding.ai (always lowercase)
• Branch: main (single branch workflow)
• Database: modest-lobster-37

[details]

[details]

[details]

```

Memory files are stored at ~/.claude/projects//memory/ and provide conversation-level context that persists across sessions. Unlike CLAUDE.md, which is project-wide, memory files capture personal and project-specific nuances that Claude recalls automatically.

Example: With and Without Memory

Session 1: "I'm a backend engineer, new to React"
Session 2: "How do I add a component?"
Claude: *explains from scratch, doesn't know your background*

Session 1: "I'm a backend engineer, new to React"
Claude: *saves to memory: user is backend engineer, new to React*
Session 2: "How do I add a component?"
Claude: *explains React components using backend analogies, skips basics they'd already know*

Claude supports several memory types, each serving a unique purpose:

• User Memory: Captures your role, preferences, and expertise level.
• Feedback Memory: Records corrections and confirmed approaches.
• Project Memory: Maintains ongoing work context.
• Reference Memory: Points to external resources.

Each memory file includes frontmatter for clarity:

---
name: user_role
description: User's role and technical background
type: user
---

Backend engineer with 10 years of Go experience.
New to React and this project's frontend.
Frame frontend explanations using backend analogies.

All memories are indexed in MEMORY.md, which Claude uses to decide which memories to load:

```markdown

Project Memory Index

• user_role.md -- Backend engineer, new to React

• feedback_testing.md -- Use real DB in integration tests, not mocks

• project_sprint.md -- Sprint 7 completed, merge freeze Mar 5

``

Keep MEMORY.md` concise, ideally under 200 lines, with each entry succinctly described.

Slash commands are markdown files located in .claude/commands/ that function as reusable prompt templates. They allow you to execute complex instructions with a simple command, streamlining repetitive tasks.

Example: With and Without Slash Commands

You: "Check all TypeScript files for console.log statements, verify no any types exist, run the linter, check for security issues, then summarize findings in a table..."

You: /code-review
Claude: *runs the full review workflow automatically*

To create a command, save a markdown file in .claude/commands/:

# Code Review

Review the current changes for quality issues:

1. Run `npx tsc --noEmit` and report errors
2. Search for `console.log` in modified files
3. Search for `: any` type annotations
4. Check for hardcoded secrets or API keys
5. Verify error handling in new functions

Output a summary table:
| Check | Status | Details |
|-------|--------|---------|

Invoke it with /code-review in any session.

Commands can be parameterized, reference other files, and chain together for more complex workflows:

# Deploy

Deploy changes to production:
1. Run `npm run typecheck`
2. Run `npm run test:safe`
3. Commit with descriptive message
4. Push to main
5. Verify deployment at $1 (URL argument)

Invoke with: /deploy https://vybecoding.ai

# Sprint Status

Read `docs/sprints/current-sprint.md` and report:
- Stories completed vs total
- Blocked items and reasons
- Estimated completion

• Each session starts from scratch.
• Repetitive instructions are necessary.
• Claude may repeat mistakes.
• Workflows are inconsistent.

• Claude understands your project from the outset.
• Preferences persist across sessions.
• Mistakes are corrected once and remembered.
• Workflows are standardized and repeatable.

The investment in creating these documents is minimal, yet the benefits are substantial. Every interaction with Claude becomes more efficient and tailored to your needs.

1. Create a CLAUDE.md at your project root with your tech stack and top 5 rules.
2. In your next Claude Code session, share something about yourself to initiate memory storage.
3. Identify a frequently repeated workflow and convert it into a .claude/commands/ file.
4. Continuously iterate and refine your context documents based on real-world usage.

By leveraging these tools, you empower Claude to become a more effective collaborator, streamlining your development process and enhancing productivity.

The Full Memory Stack: Beyond Three Documents

The three-document model (CLAUDE.md, Skills, memory files) is the foundation. But Claude Code in 2026 has a fuller memory stack — and understanding all five layers helps you build agents that maintain meaningful context across sessions, across projects, and across time.

The Five-Layer Memory Stack

Loaded into every context window for the project. Covers constraints, commands, conventions, and tooling patterns. Scoped to the project directory.

• Optimal size: 1,000–3,000 words
• Decay rate: Low (review quarterly)
• Audience: Claude working in this specific project

Structured workflows in .claude/skills//SKILL.md. Loaded on demand via /skill-name. Covers multi-step procedures, tool sequences, decision trees.

• Optimal size: 200–800 words per skill
• Decay rate: Medium (update when workflow changes)
• Audience: Claude executing a specific type of task

Files in ~/.claude/projects//memory/. Written by Claude during sessions when you say "remember this." Recalled at session start. Covers user preferences, project state, recurring facts.

• Optimal size: Unlimited (but prune regularly)
• Decay rate: Variable — actively prune stale entries
• Audience: Claude across all sessions for this project

Direct memory management via /memory in the Claude Code CLI. Lists current memories, shows what's loaded, lets you delete or edit entries.

/memory list          # Show all active memories
/memory delete    # Remove a specific memory
/memory search RAG    # Find memories mentioning RAG

Use /memory list before starting a complex task to confirm Claude has the right context. Use /memory delete to remove stale or incorrect memories that might bias Claude's behavior.

Claude Code can resume a previous session with full context. Use claude --resume or /resume in the CLI. Session context includes the full conversation history, tool outputs, and file state from the previous run.

• Use case: Long research tasks, multi-day implementation work
• Limit: Sessions expire after 30 days of inactivity
• Gotcha: Resuming a session bypasses auto-memory loading (session memory supersedes)

Auto-Memory in Practice

Auto-memory is the most powerful layer for building agents that improve over time. When Claude learns something useful about your project, workflow, or preferences during a session, it can save that as a memory file.

• User preferences ("user prefers TypeScript over JavaScript")
• Project patterns ("this project uses 0-based indexing for module orders")
• Recurring facts ("the production DB ID is modest-lobster-37")

• Non-obvious decisions ("we decided to use soft-delete instead of hard-delete because of the audit requirement")
• Debugging solutions that aren't obvious from code ("if the Convex deploy fails with this error, run npx convex codegen first")
• External system mappings ("the Linear project INGEST is where pipeline bugs are tracked")

"Remember this for future sessions: [fact]"
"Save this to memory: [decision + reasoning]"
"Keep this context: [project state]"

Claude writes the memory to a structured file with metadata and updates the MEMORY.md index. You can verify with /memory list.

Avoiding Memory Bloat

Memory files accumulate over time. Bloated memory slows context loading and can introduce conflicting information.

• Run /memory list to see all entries
• Delete memories that are project-specific and the project is done
• Delete memories that conflict with current code state
• Consolidate multiple related memories into one

• Date-stamp important project-state memories ("as of April 2026, the schema uses...")
• Include a "why" for non-obvious decisions
• Don't save things that are evident from code (code is always fresher than memory)

The Session Resume Pattern for Long Tasks

For multi-day implementation tasks:

claude "Design and implement the database schema for the billing system"

claude --resume  "Continue from where we left off — implement the API layer on top of the schema"

Session resume is more reliable than re-establishing context via a fresh session for tasks with complex intermediate state. Use it for tasks that span more than 2 hours or involve more than 20 files.

The /memory Command Deep Dive

# See what's loaded in your current context
/memory list

# Search for specific memories
/memory search "production database"

# Edit a memory (opens in $EDITOR)
/memory edit 

# Delete stale memories
/memory delete 

# Export memories for sharing or backup
/memory export > project-memories-2026-04.md

# Import memories (e.g., from a teammate)
/memory import teammate-memories.md

The /memory command is your control plane for the auto-memory layer. Checking it before starting complex tasks ensures Claude has the right foundational context — and isn't working from outdated information that memory files might contain.