Context Awareness

Claude Code is smarter when it understands your project. The CLAUDE.md file tells Claude what it needs to know.

What is CLAUDE.md?

A CLAUDE.md file is a markdown file that Claude reads when it starts. Think of it as a briefing document for your AI pair programmer.

your-project/
├── CLAUDE.md        ← Claude reads this first
├── src/
├── tests/
└── ...

Tip

Claude automatically looks for CLAUDE.md in your project root. No configuration needed—just create the file and Claude reads it.

Why CLAUDE.md Matters

Without CLAUDE.md, Claude has to guess:

• What commands to run
• What coding style to follow
• What patterns you use
• What to avoid touching

With CLAUDE.md, Claude knows your project from the start.

Your First CLAUDE.md

Create a CLAUDE.md in your project root:

# Project: My Awesome App

## Overview
A Flask web application for managing user subscriptions.

## Tech Stack
- Python 3.11
- Flask 2.x
- SQLAlchemy + PostgreSQL
- Pytest for testing
- Redis for caching

## Key Commands
- `make dev` - Start development server
- `make test` - Run tests
- `make lint` - Run linters

## Project Structure
- `app/` - Main application code
- `app/models/` - SQLAlchemy models
- `app/routes/` - API endpoints
- `tests/` - Test suite

## Coding Conventions
- Use type hints everywhere
- Docstrings in Google style
- Max line length: 100 characters

That’s it! Claude now understands:

• What your project does
• How to run things
• Where code lives
• What style to follow

What to Include

Focus on information Claude can’t easily discover:

Essential (Always Include)

Section	Why	Example
Overview	What the project does	”Backend API for user subscriptions”
Tech Stack	Tools and frameworks	”Python 3.11, Flask, PostgreSQL”
Key Commands	How to run things	”make test - Run tests”
Project Structure	Where code lives	”app/models/ - Database models”

Helpful (Include If Applicable)

Section	Why	Example
Coding Conventions	Style preferences	”Use type hints everywhere”
Critical Rules	Things to never do	”Never modify core/auth.py without review”
Known Issues	Current problems	”Rate limiting fails under load (#234)“

Quick Examples

Minimal CLAUDE.md (Enough to Get Started)

# MyProject

Python Flask API for task management.

Tech: Python 3.11, Flask, PostgreSQL, Redis

Commands:
- `make dev` - Start server
- `make test` - Run tests

Structure:
- `api/` - API routes
- `models/` - Database models
- `services/` - Business logic

Better CLAUDE.md (With Context)

# MyProject

Python Flask API for task management.

Tech: Python 3.11, Flask 2.x, PostgreSQL 15, Redis

Commands:
- `make dev` - Start dev server (port 5000)
- `make test` - Run pytest
- `make lint` - Run ruff + mypy

Structure:
- `api/routes/` - API endpoints
- `api/models/` - SQLAlchemy models
- `api/services/` - Business logic (keep routes thin)
- `tests/` - Tests mirror api/ structure

Conventions:
- Type hints required
- Google-style docstrings
- Routes are thin, logic in services/

Rules:
- Always use transactions for multi-step DB ops
- All API errors: {"error": "msg", "code": "ERROR_CODE"}

How Claude Uses CLAUDE.md

When Claude starts:

1. ✓ Reads CLAUDE.md from project root
2. ✓ Incorporates it into context
3. ✓ Uses it to inform all responses

Claude will:

• Follow your coding conventions
• Use your preferred commands
• Understand your architecture
• Respect your rules and constraints

Note

CLAUDE.md is read at the start of each session. Changes take effect the next time you run claude.

Best Practices

Do ✓

# Good: Actionable and specific

## Commands
- `npm run dev` - Start dev server on :3000
- `npm test` - Run Jest tests

## Rules
- Never commit .env files
- All prices stored as integers (cents)

Don’t ✗

# Bad: Too vague or obvious

## Commands
- Run the appropriate development commands

## Rules
- Write good code
- Don't make mistakes

Keep It Concise

CLAUDE.md is always in Claude’s context. Every word counts:

Too long: 5-page document with project history, team bios, every config option Just right: 1-2 pages with essential project context Too short: “Python project. Figure it out.”

Caution

If CLAUDE.md is longer than 2 pages, Claude spends more tokens reading it and has less room for actual coding. Be concise.

Testing Your CLAUDE.md

After creating CLAUDE.md, verify it helps:

# Test 1: Does Claude use your commands?
claude
> run the tests
# Should use the command from CLAUDE.md

# Test 2: Does Claude follow your conventions?
> add a new function
# Should follow naming/style from CLAUDE.md

# Test 3: Does Claude understand structure?
> where is the user authentication code?
# Should correctly identify files based on CLAUDE.md structure

When to Update CLAUDE.md

Update when:

• ✓ Architecture changes
• ✓ New conventions adopted
• ✓ Commands change
• ✓ Critical rules added

Don’t update for:

• ✗ Minor implementation details
• ✗ Temporary experimental code
• ✗ Every small change

Next Steps

Now that you understand the basics, explore advanced CLAUDE.md patterns:

• Advanced CLAUDE.md Patterns - Nested files, dynamic content, team configurations