Your Project's Brain
How CLAUDE.md gives your project memory — and why it’s your most important file.
The Problem: Claude Forgets Everything
Every time you start a new Claude Code session, Claude starts fresh. It doesn’t remember your last conversation. It doesn’t know what you built yesterday, what colors you chose, or what framework you’re using.
Without context, the first few minutes of every session become re-explaining. “This is a React app.” “I’m using Tailwind.” “The primary color is blue-600.” “We already built the sidebar.” Over and over.
CLAUDE.md fixes this.
It’s a markdown file that sits in the root of your project. Claude reads it automatically at the start of every session. Think of it as a design brief — except it’s for your AI collaborator instead of your team.
What Goes in a CLAUDE.md
Keep it simple. You’re writing for Claude, not for a stakeholder presentation. Here’s what matters:
- What the project is — one sentence. What are you building?
- Tech stack — what language, framework, and tools you’re using
- Design conventions — colors, fonts, spacing, tone. The decisions you’ve already made
- Current state — what’s built, what’s in progress, what’s next
- Rules — anything Claude should always (or never) do
You don’t need all of these on day one. Start with what you know and add more as you go.
Real Examples
Simple Web Page
# My Portfolio
Personal portfolio site. HTML, CSS, vanilla JS.
Dark theme, Inter font, minimal layout.
Currently: home page done, need to add projects section.Four lines. That’s enough for Claude to understand your project, match your aesthetic, and pick up where you left off.
Web App
# WeatherDash
Weather dashboard using Open-Meteo API. React + Tailwind.
Design: clean cards, blue/gray palette, SF Pro Display.
Responsive — mobile-first, breakpoint at 768px.
Status: fetching data works, need 5-day forecast and location search.
Convention: all components in src/components/, one per file.More detail because the project is more complex. Notice the convention at the bottom — that tells Claude how to organize new files so your project stays consistent.
Full App
# FocusTimer
macOS menu bar app for focused work sessions. Swift, SwiftUI, AppKit.
## Design System
- Font: SF Pro, 13pt body, 11pt caption
- Colors: Indigo-500 primary, gray-800 background, gray-200 text
- Corner radius: 8px
- Spacing: 8px base unit
## Structure
- Views/ — all SwiftUI views, one per file
- Models/ — data types
- Services/ — timers, notifications, persistence
## Current State
- Timer view working with start/pause/reset
- Menu bar icon toggles popover
- Next: add session history and daily stats
## Rules
- No external dependencies — use only Apple frameworks
- Always use SF Symbols for icons
- Keep the popover width at 280px
## Skill Files
See .claude/skills/ for reusable patterns:
- accessibility.md — VoiceOver and keyboard nav standards
- animation.md — spring animation preferencesThis is a project with real structure. The design system section means Claude won’t guess at your spacing or colors. The rules section prevents it from adding libraries you don’t want. And the skill file references point Claude to detailed knowledge that would clutter the main file.
How to Evolve It
Your CLAUDE.md should grow with your project. It’s a living document, not something you write once and forget.
After each session, take 30 seconds to update it:
- Add decisions you’ve made. Chose a color? Added a page? Write it down.
- Record what works. If Claude nailed an animation or layout pattern, note it so it repeats the approach.
- Flag what to avoid. If something broke or looked wrong, add a rule: “Don’t use absolute positioning for the nav.”
- Update the current state. What’s done? What’s next? This saves you from re-explaining progress.
The best CLAUDE.md files read like a running log of the project. Not verbose — just enough that Claude (or you, in two weeks) can pick up exactly where things stand.
Connection to Skill Files
Your CLAUDE.md is project-specific. But some knowledge applies across projects — your accessibility standards, animation preferences, responsive breakpoints, how you like forms to behave.
That’s what skill files are for. They’re reusable markdown files that live in .claude/skills/ and contain design knowledge Claude can reference from any project. Your CLAUDE.md points to them; they handle the details.
For the full breakdown, see Skill Files.
Start Now
If you don’t have a CLAUDE.md yet, create one before your next session. Even three lines will save you time:
# Project Name
What it is. What stack. What's next.Then grow it from there. Every session gets a little better when Claude already knows the project.