Security and Configuration

CLAUDE.md and Memory: Giving Claude Code Persistent Project Context

CLAUDE.md is the single most important file you'll create for Claude Code. Learn what to put in it, how memory works, and how to build a project context layer that makes every session dramatically more effective.

Why Persistent Context Matters

Without CLAUDE.md, every Claude Code session starts from scratch. Claude Code knows your filesystem but nothing about your team's conventions, your preferred libraries, your testing requirements, or the constraints that govern this particular project.

CLAUDE.md changes this. It's a Markdown file in your project root that Claude Code reads automatically at the start of every session. Everything in it becomes persistent context — active in every session without requiring you to re-state it.

What CLAUDE.md Should Contain

A strong CLAUDE.md has six categories of information:

1. Tech Stack

Be specific about versions and which libraries are canonical for each concern. This prevents Claude Code from introducing alternative libraries you don't use.

markdown
## Tech Stack
- React 18.3 + TypeScript 5 (strict mode)
- Vite 5 for builds
- Tailwind CSS v3 — utility classes only, no custom CSS
- TanStack Query v5 for server state
- React Router v6 for navigation
- Supabase (@supabase/supabase-js v2) for database and auth
- Vitest + React Testing Library for tests
- Lucide React for icons — no other icon library

2. Coding Conventions

Rules that govern how code is written in this project. These are the decisions that get re-litigated every time a new engineer (or AI) touches the codebase.

markdown
## Conventions
- One component per file, PascalCase filename
- Custom hooks in src/hooks/, prefixed with "use"
- All Supabase calls in src/services/, never in components
- No any or unknown TypeScript types — use proper interfaces
- Imports: external packages first, then internal modules, alphabetical within groups
- No default exports from utility files (named exports only)
- Tailwind classes in JSX, never inline style attributes

3. Project Structure

A directory map with brief descriptions. This helps Claude Code place new files correctly without asking.

markdown
## Project Structure
src/
  components/    # Shared UI, organized by category (layout/, ui/, forms/)
  pages/         # Route-level components, named [Name]Page.tsx
  services/      # All data fetching and mutation (supabase calls)
  hooks/         # Custom React hooks
  types/         # TypeScript interfaces and enums
  lib/           # Pure utility functions, no React
  context/       # React context providers

4. Commands

The specific commands Claude Code should run for this project — especially test and typecheck commands that may not be the npm defaults.

markdown
## Commands
- Test: npm run test (or npx vitest run for single pass)
- Typecheck: npm run typecheck (runs tsc --noEmit)
- Lint: npm run lint
- Build: npm run build
- Before committing: npm run typecheck && npm run test

5. Workflow Instructions

What Claude Code should do before making changes, how to verify work, and any process requirements.

markdown
## Workflow
- Always run typecheck before reporting a task complete
- Run affected tests after modifying a component or service
- If tests fail, fix them before proceeding — do not leave failing tests
- For new components, create a .test.tsx file alongside the component
- Report any files you're uncertain about modifying before touching them

6. Out of Scope / Constraints

Explicit list of things Claude Code should NOT do in this project.

markdown
## Constraints
- Do not add new npm packages without explicit permission
- Do not modify any files in src/legacy/ — this code is frozen
- Do not change the Supabase schema or RLS policies
- Do not refactor files unrelated to the current task
- Never use console.log in production code — use the project's logger utility

Generating CLAUDE.md Automatically

If you're starting with an existing project:

bash
claude
> /init

Claude Code analyzes your project structure, package.json, tsconfig, and existing code to generate an initial CLAUDE.md. Review the output carefully — it gets the structure right but may miss conventions that aren't evident from code alone.

Alternatively, from outside the session:

bash
claude -p "Analyze this project and create a comprehensive CLAUDE.md with tech stack, conventions, project structure, and commands. Base it on what you observe in the codebase."

Memory: Cross-Session Persistence

Beyond CLAUDE.md, Claude Code has a memory system accessible via the /memory command. Memory stores notes that persist across sessions and across projects — personal preferences, reminders, or cross-project conventions.

text
/memory
> Add: Always use named exports. Never default exports for utilities.
> Add: When I say "clean this up" I mean fix types and add missing tests — not refactor structure.

Memory is project-agnostic. Use it for your personal development conventions. Use CLAUDE.md for project-specific ones.

Hierarchical CLAUDE.md Files

Claude Code supports CLAUDE.md files at multiple directory levels:

  • /CLAUDE.md — Project root: applies to the whole project
  • /src/components/CLAUDE.md — Applies only when working in this directory
  • /src/services/CLAUDE.md — Service-specific rules (e.g., "all queries must include error handling")

This lets you add context at the right level of specificity rather than cluttering the root CLAUDE.md with implementation-detail rules.

Keeping CLAUDE.md Current

CLAUDE.md is a living document. When the team makes a new architectural decision, adds a library, or changes a convention, update CLAUDE.md. Treat it as the onboarding document for AI coding tools — and maintain it with the same discipline you'd maintain any architectural documentation.

Key Takeaways

  • CLAUDE.md is automatically read every session — it's your primary tool for persistent project context
  • Cover six areas: tech stack, conventions, project structure, commands, workflow instructions, and constraints
  • Use /init to generate an initial CLAUDE.md, then refine it manually
  • Memory (/memory) stores personal cross-project preferences; CLAUDE.md stores project-specific rules
  • Subdirectory CLAUDE.md files add targeted context for specific parts of the codebase

---

Try It Yourself: Write a CLAUDE.md for your current project from scratch — without using /init. Force yourself to articulate your actual conventions, structure, and constraints. Then compare it against what /init generates. The differences reveal what about your project isn't obvious from the code alone.