All Guides Book a Call
Beginner

Paste this guide into Claude Code and it will walk you through every step interactively.

Understanding CLAUDE.md

What this gives you: An AI that already knows your business before you say a word. Your tools, your clients, your preferences, your rules - all loaded automatically every time you start a session. No more repeating yourself.

CLAUDE.md is the single most important file in your Claude Code setup. It is the instruction manual that Claude reads at the start of every session - your opportunity to teach it who you are, how you work, and what mistakes to never repeat.

What CLAUDE.md Is and Why It Matters

When you start a Claude Code session, the first thing Claude does is look for a CLAUDE.md file. If it finds one, it reads the entire file and uses it as persistent context for the entire session. Think of it as a briefing document that you hand to a new team member on their first day.

Without a CLAUDE.md, Claude Code starts every session with zero institutional knowledge. It doesn't know your tech stack, your preferences, your clients, or the mistakes it made last week. With a well-written CLAUDE.md, it walks in already knowing:

The difference between a Claude Code setup with no CLAUDE.md and one with a detailed CLAUDE.md is the difference between a new hire and a senior employee who's been with you for two years.

Global vs Project-Level CLAUDE.md

There are two places you can put a CLAUDE.md file, and Claude reads both:

Global CLAUDE.md - ~/.claude/CLAUDE.md

This file applies to every Claude Code session on your machine, regardless of what directory you're in. This is where you put things that are true across all your work:

Project-Level CLAUDE.md - ./CLAUDE.md

This file sits at the root of a specific project and applies only when Claude is working in that project. Use it for:

When both files exist, Claude reads the global one first, then the project-level one. The project-level file can override or extend anything in the global file.

Tip: Start with just a global CLAUDE.md. Add project-level files as projects get complex enough to need them. A 50-line global file beats no file at all.

The 5 Essential Sections

A great CLAUDE.md is structured around five areas. Here is what each one does and why it belongs there.

1. Security Rules

The first thing Claude should read. Non-negotiable rules about secrets, credentials, and sensitive data. This section prevents the most costly mistakes.

# Security Rules - NEVER write API keys, passwords, or tokens in plaintext to any file - ALL secrets live in .env files - never hardcode them - .env files MUST be in .gitignore - never commit them - Before committing, check for accidentally staged .env files - When reading secrets for API calls, load from the .env file

2. Capabilities

Tell Claude what tools, integrations, and skills are available to it. If you've connected MCP servers or built custom skills, list them here. Claude cannot use tools it doesn't know about.

# Capabilities ## MCP Servers Connected - **Google Calendar** - Read/write events, check free/busy - **Notion** - Pages, databases, blocks, search - **Stripe** - Customers, payments, invoices, balance - **Trello** - Boards, lists, cards, attachments ## Skills Available (invoke via /skill-name) - /google-docs - Create/update Google Docs from markdown - /md-to-pdf - Convert markdown to professional PDFs - /video-extract - Transcribe any video (YouTube, Loom, local)

3. Known Failures and Learnings

This is the section that compounds over time. Every time Claude makes a mistake - or you discover something that doesn't work the way you expected - you log it here. Future sessions start with that knowledge already loaded.

# Known Failures & Learnings ## Auto-Logging Rule When you make a mistake, AUTOMATICALLY add it here. ## Development - Prisma v7 requires driver adapters - use Prisma v5 for SQLite - Port 3000 on this Mac is often used by Remotion Studio - Always audit package.json before npm install (hallucinated packages) - After pushing to Vercel repos, verify auto-deploy triggered ## API / Integrations - When using a non-trivial API for the first time, READ THE DOCS first - Supabase RLS is OFF by default - always enable before deploying

4. Workflow Preferences

How you like to work. Communication style, parallelization preferences, quality standards. This shapes how Claude communicates and prioritizes throughout every session.

# Workflow Preferences ## How I Work - Prefer parallel execution over serial - dispatch multiple tasks at once - Concise, direct communication - no fluff, no unnecessary explanation - When building: plan first, then execute, then compile learnings - Always push code to remote after changes so Vercel auto-deploys ## Quality Standards - Always verify deployments work (check HTTP status) before claiming success - Always run tests before claiming code works - After building a system, check if memory files need updating

5. Session Protocol

Explicit instructions for what to do at the start and end of every session. This is what turns Claude Code from a reactive tool into a proactive assistant with continuity.

# Session Protocol ## Session Start 1. Check MEMORY.md and HISTORY.md for recent context 2. Read claude-progress.md in the project directory if it exists 3. Before Trello tasks: check board state first 4. Before client calls: check Fireflies for recent meeting context ## Session End 1. Append entry to HISTORY.md (date, what was built, key files) 2. Update claude-progress.md with current state and pending work 3. Update CLAUDE.md if any new learnings should be captured permanently

Want help building your CLAUDE.md?

A 30-minute call is enough to map out the full structure for your specific workflow and tech stack.

Book a Call

Full Example CLAUDE.md

Here is a complete, production-ready CLAUDE.md you can adapt for your own setup:

# Security Rules - NEVER write API keys, passwords, tokens, or credentials in plaintext - ALL secrets live in .env files: locally at ~/.env or project .env - .env files MUST be in .gitignore - never commit them - Run a security audit periodically or after adding new integrations --- # Capabilities ## MCP Servers Connected - **Google Calendar** - Read/write events, check free/busy, manage accounts - **Notion** - Pages, databases, blocks, comments, search - **Stripe** - Customers, payments, subscriptions, invoices - **Trello** - Boards, lists, cards, attachments ## Skills Available (invoke via /skill-name) - /google-docs - Create/update Google Docs from markdown - /md-to-pdf - Convert markdown to professional PDFs - /video-extract - Transcribe any video (YouTube, Loom, local) ## What I CAN Do - Execute shell commands, read/write files, search codebases - SSH into VPS and run commands there - Deploy to Vercel by pushing to git (auto-deploy) - Generate images with fal.ai and attach to Trello cards --- # Known Failures & Learnings ## Auto-Logging Rule When you make a mistake, AUTOMATICALLY add it here. Don't wait to be asked. ## Development - Port 3000 is often occupied by other processes - check before starting dev server - Always verify Vercel auto-deploy triggered after pushing ## API / Integrations - Read docs before using any non-trivial API for the first time - Supabase RLS is OFF by default - always enable before deploying - Audit package.json for hallucinated packages before npm install --- # Workflow Preferences ## How I Work - Prefer parallel execution over serial - Concise, direct communication - no fluff - Plan first, execute, then compile learnings ## Quality Standards - Verify deployments work before claiming success - Run tests before claiming code works - Check if memory files need updating after building systems --- # Session Protocol 1. Check MEMORY.md for recent context 2. Read project claude-progress.md if it exists 3. [End of session] Append to HISTORY.md 4. [End of session] Update claude-progress.md with current state

Adding MCP Servers to Capabilities

MCP (Model Context Protocol) servers give Claude Code access to external APIs and tools. Once you've configured an MCP server in your Claude settings, you tell Claude about it in the Capabilities section of CLAUDE.md so it knows the server is available and what it can do.

## MCP Servers Connected - **Google Calendar** - Read/write events, check free/busy, manage multiple accounts - **GitHub** - Read repos, create PRs, manage issues, view file contents - **Slack** - Read channels, search messages, post to channels - **Linear** - Create issues, update status, manage projects

The description next to each server matters. It tells Claude what each server is capable of, which helps it decide when to use each one without you having to remind it every session.

Adding Skills to Capabilities

Skills are reusable instruction files stored in ~/.claude/skills/. They're invoked with a slash command and give Claude a detailed playbook for complex, repeatable tasks. List them in CLAUDE.md so Claude knows they exist:

## Skills Available (invoke via /skill-name) - /deploy - Full deployment checklist for this stack - /review - Code review protocol with quality standards - /daily-brief - Pull data from Stripe, Notion, Calendar for morning brief - /new-client - Onboarding checklist for new client projects

The "Known Failures" Auto-Logging Pattern

This is the highest-leverage section in your CLAUDE.md. The rule is simple: whenever Claude makes a mistake - or you discover something that doesn't work as expected - it gets logged immediately. Not at the end of the session. Right now.

Why this is powerful:

Real example of what this looks like in practice:

## Known Failures - Added 2026-03-15 - Prisma v7 generates ESM that doesn't work with tsx for seed scripts -> Use Prisma v5 for simple SQLite projects, or switch to Drizzle - Vercel preview URLs sometimes take 3-4 minutes to propagate -> Don't test preview URL immediately after deploy, wait 3 minutes - npm install with --legacy-peer-deps masks real dependency conflicts -> Fix the actual conflict instead of suppressing the error

Session Protocol: Start and End Rituals

Most people use Claude Code reactively - they open a session, ask questions, close it. The session protocol pattern makes it proactive.

At the start of each session, Claude checks your memory files and loads recent context before you say anything. At the end of each session, it writes a brief log of what was built and what the current state is. Over time, this creates a persistent working memory that means you never have to re-explain your project from scratch.

## Session Start 1. Check MEMORY.md for recent context and active projects 2. If working on a specific project, read claude-progress.md first 3. Check HISTORY.md for what was done in the last session ## Session End 1. Append to HISTORY.md: - Date - What was built or changed - Key file paths affected - Any new learnings 2. Update claude-progress.md: - Current state of the project - What is working - What is pending - Next steps
Tip: The combination of MEMORY.md (persistent facts), HISTORY.md (chronological log), and claude-progress.md (per-project state) gives you a three-layer memory system. Start with just MEMORY.md if you want to keep it simple.
Next Guide
The Mental Model