Every developer using Claude Code eventually hits the same wall: you fix a mistake, then three sessions later, Claude makes the exact same error. It's like working with someone who has amnesia.

Boris Cherny's team at Anthropic solved this with a single file called CLAUDE.md. It lives in your repository root, and it transforms Claude from a forgetful assistant into a team member who actually learns.

Here's how to build one that works.

What CLAUDE.md Actually Does

Large language models don't remember previous sessions. Every time you start a new Claude Code session, it's a fresh slate. Your CLAUDE.md file provides the context that would otherwise be lost.

Think of it as onboarding documentation—but for an AI that needs to be onboarded every single time it starts work.

When Claude Code launches, it reads this file automatically. Everything you put there becomes part of Claude's working knowledge for that session.

The Minimum Viable CLAUDE.md

Start simple. You can always add more later.

# Project: [Your Project Name]

## Overview
[One paragraph describing what this project does]

## Tech Stack
- Frontend: [e.g., Next.js, React]
- Backend: [e.g., Supabase, Node]
- Deployment: [e.g., Vercel]

## Commands
- `npm run dev`: Start development server
- `npm test`: Run test suite
- `npm run build`: Production build

## Code Style
- Use TypeScript strict mode
- Prefer async/await over .then()
- Use named exports

## Known Issues
[Add these as you discover them]

This takes five minutes to create and immediately improves every Claude session.

The Four Sections That Matter Most

1. Project Context

Claude works better when it understands why the code exists, not just what it does.

## Project Context

This is an Excel add-in that helps users automate repetitive tasks.
Target users are Excel power users who aren't programmers.
The UI should be simple—assume users don't know technical terms.
We prioritize reliability over features. Crashes destroy user trust.

This context shapes every decision Claude makes. Without it, you'll get generic solutions that don't fit your actual users.

2. Architecture Decisions

Document the choices you've already made so Claude doesn't suggest alternatives.

## Architecture Decisions

- State management: We use Zustand, not Redux. Don't suggest Redux.
- Styling: Tailwind CSS only. No CSS modules or styled-components.
- API calls: All API calls go through /lib/api.ts. Never call fetch directly.
- Database: Supabase. Queries use the JS client, not raw SQL.

Every undocumented decision is an opportunity for Claude to waste your time suggesting something you've already rejected.

3. Patterns and Anti-Patterns

This is where the real learning happens. Every time Claude does something wrong, add it here.

## Patterns We Use

- Early returns over nested if statements
- Custom hooks for shared logic (put in /hooks)
- Error boundaries around all async operations
- Descriptive variable names over comments

## Anti-Patterns (Don't Do These)

- Don't use `any` type—always define proper types
- Don't put business logic in components—use hooks or utils
- Don't catch errors silently—always log or display them
- Don't hardcode URLs—use environment variables

This section grows over time. After a month, you'll have a comprehensive style guide that Claude follows automatically.

4. Common Commands and Workflows

Save time by documenting the commands Claude will need.

## Development Workflow

Starting work:
1. Pull latest: `git pull origin main`
2. Install deps: `pnpm install`
3. Start dev: `pnpm dev`

Before committing:
1. Run tests: `pnpm test`
2. Run lint: `pnpm lint`
3. Run type check: `pnpm typecheck`

Database changes:
- Generate migration: `pnpm supabase migration new [name]`
- Apply migration: `pnpm supabase db push`

Real Examples From Different Project Types

For a Next.js Marketing Site

# CLAUDE.md - KuduTek Website

## Overview
Marketing site for KuduTek built with Next.js 14 and deployed on Vercel.
Content comes from MDX files in /content directory.

## Key Directories
- /app - Next.js app router pages
- /components - React components
- /content - MDX blog posts and pages
- /lib - Utility functions

## Content Guidelines
- Blog posts go in /content/blog/[slug].mdx
- Use frontmatter for title, date, description
- Images go in /public/images/blog/

## SEO Requirements
- Every page needs metadata export
- All images need alt text
- URLs use trailing slashes (Next.js config handles this)

## Don't Do
- Don't use client components unless necessary
- Don't import images directly—use next/image
- Don't hardcode links—use constants from /lib/constants

For an API Project

# CLAUDE.md - Analytics API

## Overview
REST API for analytics data. Node.js + Express + PostgreSQL.

## API Conventions
- All routes return JSON
- Success: { data: ... }
- Error: { error: { message, code } }
- Use HTTP status codes correctly (don't return 200 for errors)

## Database
- Migrations in /db/migrations
- Always create a migration for schema changes
- Never modify production data directly

## Authentication
- JWT tokens in Authorization header
- Token validation middleware in /middleware/auth.js
- User ID available as req.userId after auth middleware

## Testing
- Unit tests: `npm test`
- Integration tests: `npm run test:integration`
- Tests must pass before merging to main

For a Chrome Extension

# CLAUDE.md - Tab Manager Extension

## Overview
Chrome extension for managing browser tabs. Manifest V3.

## Architecture
- /src/background - Service worker (no DOM access)
- /src/popup - Popup UI (React)
- /src/content - Content scripts (injected into pages)

## Chrome API Notes
- Use chrome.storage.local, not localStorage
- Service worker can't use window object
- Content scripts are isolated—use message passing

## Common Mistakes to Avoid
- Don't use alert() in background scripts
- Don't assume tabs exist—always check for undefined
- Don't forget to add permissions to manifest.json

The Team Workflow

Boris's team treats CLAUDE.md as living documentation:

  1. Everyone contributes — Multiple updates per week from different team members
  2. Tag @claude in PRs — When reviewing code, tag Claude to add learnings
  3. Review changes — CLAUDE.md updates get reviewed like any other code change
  4. Mistakes compound into knowledge — Every bug becomes a lesson

If you're working solo, the same principle applies. Every time you catch Claude making an error, take 30 seconds to add it to your anti-patterns list.

Maintenance Tips

Keep it focused. A 500-line CLAUDE.md is too long. Claude will miss important details buried in noise. Aim for under 200 lines.

Use clear headers. Claude parses markdown structure. Good headers make information findable.

Update, don't just add. Outdated information is worse than no information. Review your CLAUDE.md monthly and remove anything no longer relevant.

Be specific. "Write good code" is useless. "Use early returns to reduce nesting" is actionable.

Start Today

You don't need a perfect CLAUDE.md to start. Create the minimum viable version now:

  1. Create CLAUDE.md in your project root
  2. Add your project overview (one paragraph)
  3. List your tech stack
  4. Add three common commands
  5. Add one code style rule you care about

That's it. You now have a CLAUDE.md file. It will grow naturally as you work. Every time Claude does something you don't like, add a note.

In a month, you'll wonder how you ever worked without it.

Claude Code Workflow Series

Official Resources

Have a CLAUDE.md pattern that works well for your project? I'd love to see examples from different tech stacks and project types.