CLAUDE.md: The Identity File That Makes Every AI Session Start Smart

You open Claude Code. You explain your project structure. The AI gets it. You close the session. Next morning, you're explaining everything again.

This is the loop that drives developers insane.

The solution isn't better memory. It's better identity. CLAUDE.md is a single file that tells your AI who you are, what you're building, and how you work. Every time. No repetition. No context drift.

Analogy: Think of CLAUDE.md as your project's passport. When you cross borders (start new sessions), you don't explain your entire life story. You show the passport. Same information, zero friction.

Table of Contents

1. Why Identity Beats Memory
2. What Actually Goes in CLAUDE.md
3. CONTEXT_TYPE Triggers That Work
4. The Auto Git Pull Pattern
5. File Separation Strategy
6. Privacy and .gitignore Rules
7. Real Example That Ships

Why Identity Beats Memory

Claude Code, Cursor, Windsurf, and every agentic IDE face the same problem. Each session starts cold. The AI doesn't remember yesterday's conversation because it's not supposed to. Stateless sessions are a feature, not a bug.

But your project has an identity. Your coding style, architecture decisions, testing preferences, and deployment patterns don't change session to session. That's what CLAUDE.md captures.

When you put identity in a file instead of relying on memory, three things happen:

Consistency across sessions. Every chat starts with the same foundation. No more "we discussed this yesterday" followed by blank AI stares.

Onboarding speed. New collaborators (human or AI) read one file and understand your world.

Less token waste. You're not burning context window on repetitive explanations. The AI loads your identity once and moves to actual work.

The mistake most developers make is treating CLAUDE.md like a dumping ground. They paste everything: API docs, full file contents, debugging notes, yesterday's chat logs. Then they wonder why Claude ignores half of it.

CLAUDE.md isn't a knowledge base. It's an identity document.

What Actually Goes in CLAUDE.md

Here's what belongs in your root CLAUDE.md:

Project identity. One paragraph. What you're building, who it's for, current stage (prototype, production, scaling).

Tech stack overview. Framework, language version, key libraries. Not a package.json dump. The big picture.

Your coding style. Functional or OOP? Test-first or ship-first? Verbose or terse? Claude needs to match your voice, not impose its own.

Architecture patterns. Are you doing microservices, monolith, serverless? Where does state live? How do services talk?

File organization rules. What goes in /src vs /lib vs /utils? What's your naming convention?

Common tasks. The things you do every session. Run tests. Start dev server. Deploy to staging. Format these as commands the AI can reference.

Here's what does NOT belong:

• API documentation (link to it instead)
• Full file contents (AI can read files)
• Debugging logs (those go in session-specific notes)
• Personal todos (use a task manager)
• Sensitive credentials (never, ever)

Keep CLAUDE.md under 1000 words. If it's longer, you're documenting, not identifying.

CONTEXT_TYPE Triggers That Work

Some agentic IDEs support CONTEXT_TYPE flags that tell the AI how to interpret different sections. The most useful ones:

@architecture for system design explanations. Use this for database schemas, service boundaries, and data flow.

@conventions for style guides and patterns. Naming rules, comment standards, import order.

@workflow for process steps. How you test, how you deploy, how you review code.

@constraints for hard limits. Performance budgets, browser support, API rate limits.

Example structure:

# Project Identity
[One paragraph overview]

## @architecture
- Next.js 14 app router
- PostgreSQL with Prisma ORM
- Redis for session cache
- Deployed on Vercel

## @conventions
- TypeScript strict mode
- Functional components only
- Co-locate tests with source
- Max file length: 250 lines

## @workflow
- Feature branch → PR → staging → prod
- All APIs must have integration tests
- npm run validate before commit

## @constraints
- Lighthouse score 90+
- API response time under 200ms
- No client-side secrets

These triggers help Claude prioritize. When you ask about architecture, it knows where to look. When you ask about style, it references conventions.

The Auto Git Pull Pattern

Here's a pattern that saves massive headaches:

Add this to your CLAUDE.md:

## Session Start Protocol
1. Check current branch
2. Pull latest from origin
3. Review package.json changes
4. Confirm dev dependencies installed
5. Run health check (npm run validate)

Why this matters: AI sessions often break because you're on an old branch or missing dependencies. By making git pull part of the identity, Claude checks automatically.

You can make this even smoother with a bash alias:

alias ai-start='git pull && npm install && npm run validate'

Reference it in CLAUDE.md. Now every session begins with verified clean state.

File Separation Strategy

Not everything belongs in one file. Here's the hierarchy that works:

CLAUDE.md is the passport. Global identity.

AGENTS.md is for multi-agent workflows. If you have specialized agents (code reviewer, test writer, docs generator), their configs go here.

_index.md in a .claude directory is your session scratchpad. Decisions you made today, open questions, temporary notes. This should NOT be committed. It's session state, not identity.

Feature-specific context files live in feature directories. If you're building a payment system, /features/payments/.ai/context.md holds payment-specific architecture notes.

This separation prevents CLAUDE.md bloat. Identity stays lean. Context grows where needed.

Privacy and .gitignore Rules

The biggest CLAUDE.md mistake is committing private information.

Add this to your .gitignore immediately:

# AI session data (private)
.claude/
.cursor/chats/
.ai/sessions/
*_session_notes.md

# OK to commit (public identity)
CLAUDE.md
AGENTS.md
.cursorrules

Session logs often contain:

• API keys you pasted for debugging
• Customer data from production logs
• Internal URLs and endpoints
• Personal notes about team members

None of that belongs in version control.

Your CLAUDE.md should be safe to open-source. If there's anything in it you wouldn't put on GitHub, move it to a local session file.

For teams, you might want a CLAUDE.local.md that's gitignored. Each developer has their own preferences (editor setup, local paths, personal shortcuts). The main CLAUDE.md stays clean and shared.

Real Example That Ships

Here's a production CLAUDE.md from an actual SaaS project:

# Marketing Analytics SaaS

Building a privacy-first analytics platform for content creators. Currently in beta with 200 users. Focus: fast queries, simple UX, no tracking bloat.

## @architecture
- Frontend: Next.js 14, React 18, Tailwind CSS
- Backend: Supabase (PostgreSQL + Auth + Storage)
- Analytics: ClickHouse for event data
- Cache: Redis for dashboard queries
- Hosting: Vercel (frontend), Fly.io (ClickHouse)

## @conventions
- TypeScript everywhere, strict mode
- Functional React components, hooks only
- Server components by default, use client only when needed
- SQL queries in /queries/, not inline
- Test files: [name].test.ts next to source
- Max function length: 50 lines

## @workflow
Development:
- npm run dev (starts Next.js + ClickHouse local)
- npm run test (Vitest)
- npm run validate (lint + type + test)

Deployment:
- main branch → auto-deploy to production
- Preview deploys on every PR
- DB migrations run via Supabase CLI

## @constraints
- Dashboard must load in under 1 second
- No personal data in ClickHouse (only aggregate)
- Support last 2 browser versions
- All API routes need rate limiting

## Common Tasks
- Add new metric: Create table in ClickHouse, add query in /queries/, expose via API route, build chart component
- Deploy migration: supabase db push, test on staging first
- Debug slow query: Check ClickHouse query log, add indexes if needed

This is 250 words. It tells Claude everything about the project without drowning in detail. Every session starts here. No repetition. No drift.

The Takeaway

CLAUDE.md isn't magic. It's just a file. But it's the file that stops you from treating every AI session like meeting a stranger.

Your project has an identity. Your code has patterns. Your workflow has rules. Write them down once. Let the AI read them every time.

Stop explaining. Start shipping.

Create your CLAUDE.md today. Keep it under 1000 words. Commit it to git. Watch your AI sessions go from scattered to smart.

That's the whole trick.