Claude AI Tutorial #6: CLAUDE.md — Project Instructions That Make Claude Smarter

Claude Code is smart. But it does not know your project. It does not know your coding style, your build commands, or your project structure. That is what CLAUDE.md fixes.

This is Article 6 in the Claude AI — From Zero to Power User series. You should have completed Article 3: Claude Code CLI before this article.

By the end of this article, you will know how to write CLAUDE.md files that make Claude Code work like a teammate who already knows your codebase.

What is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude Code reads automatically when it starts a session. It contains project-specific instructions — your tech stack, build commands, coding conventions, and anything else Claude should know.

Think of it like an onboarding document for a new developer. But instead of a person reading it, Claude reads it.

Without CLAUDE.md, Claude Code guesses based on what it sees in your files. With CLAUDE.md, Claude Code follows your exact rules from the first command.

How Claude Code Reads CLAUDE.md

Claude Code looks for CLAUDE.md files in three locations, in this order:

1. Global: ~/.claude/CLAUDE.md — applies to all your projects
2. Project root: ./CLAUDE.md — applies to this project
3. Subdirectories: ./src/CLAUDE.md, ./api/CLAUDE.md — applies to that folder

All three levels combine. If there is a conflict, the more specific file wins. A rule in ./src/CLAUDE.md overrides the same rule in the project root.

Example Hierarchy

~/.claude/CLAUDE.md          # "Always use TypeScript strict mode"
project/CLAUDE.md            # "This is a Next.js 15 project"
project/api/CLAUDE.md        # "API routes use Hono framework"
project/frontend/CLAUDE.md   # "Frontend uses Tailwind CSS v4"

When Claude Code works on a file in project/api/, it reads all four files. When it works on a file in project/frontend/, it reads the global, project, and frontend files — but not the API one.

The /init Command

The fastest way to create a CLAUDE.md is the /init command:

# In Claude Code, type:
/init

Claude Code analyzes your project and generates a starter CLAUDE.md. It looks at your:

• Package manager (npm, pnpm, yarn, pip, cargo)
• Framework (Next.js, FastAPI, Django, etc.)
• Build files (package.json, pyproject.toml, Makefile)
• Config files (tsconfig.json, .eslintrc, etc.)
• Existing documentation (README.md)

The generated file is a starting point. You should review it and add your specific rules.

What to Include in CLAUDE.md

A good CLAUDE.md has five sections:

1. Project Overview

One or two sentences about what the project is.

# My Project

REST API for user management. Built with FastAPI and PostgreSQL.

2. Tech Stack

List the key technologies and versions.

## Tech Stack

- Python 3.12
- FastAPI 0.115
- PostgreSQL 16
- SQLAlchemy 2.0 (async)
- Alembic for migrations
- pytest for testing

3. Commands

The commands Claude needs to build, test, and run the project.

## Commands

- Install: `pip install -e ".[dev]"`
- Run: `uvicorn app.main:app --reload`
- Test: `pytest`
- Test single: `pytest tests/test_users.py -k test_create_user`
- Lint: `ruff check .`
- Format: `ruff format .`
- Migrate: `alembic upgrade head`

4. Coding Rules

Your project-specific conventions.

## Rules

- All API endpoints must have type hints for request and response
- Use async/await for all database operations
- Every new endpoint needs a test in tests/
- Use Pydantic v2 models for all request/response schemas
- Error responses follow RFC 7807 (Problem Details)
- Never commit .env files

5. Project Structure

Help Claude understand where things go.

## Structure

- `app/` — main application code
- `app/routers/` — API route handlers (one file per resource)
- `app/models/` — SQLAlchemy models
- `app/schemas/` — Pydantic request/response schemas
- `app/services/` — business logic
- `tests/` — pytest test files (mirror app/ structure)
- `alembic/` — database migrations

What NOT to Include

Do Not Make It Too Long

Keep CLAUDE.md under 300 lines. Claude Code reads the entire file at session start, and long files waste context tokens.

If you need more detail, use the import syntax to split into multiple files:

## Detailed Guidelines

For API conventions, see @docs/api-conventions.md
For database patterns, see @docs/database-patterns.md

The @path/to/file syntax tells Claude Code to read that file when it needs the information, instead of loading it all upfront.

Do Not Repeat What Is Obvious

Claude Code can already read your package.json, tsconfig.json, and other config files. Do not copy their contents into CLAUDE.md. Focus on things Claude cannot figure out by reading your code:

• Good: “Run integration tests with docker compose up -d first”
• Bad: “We use TypeScript” (Claude can see the tsconfig.json)

Do Not Include Secrets

Never put API keys, passwords, or tokens in CLAUDE.md. This file should be committed to git.

Progressive Disclosure

The best CLAUDE.md files tell Claude how to find information, not all the information.

Bad: Everything Upfront

## API Endpoints

POST /users — creates a user. Requires name (string, 1-100 chars),
email (string, valid email format), role (enum: admin, user, viewer).
Returns 201 with user object. Returns 400 if email already exists.
Returns 422 if validation fails...

[500 more lines of endpoint documentation]

This wastes context tokens on every session, even when Claude is not working on the API.

Good: Point to the Source

## API Documentation

- API specs are in `docs/openapi.yaml`
- Each router file in `app/routers/` has docstrings explaining its endpoints
- See @docs/api-conventions.md for our API design rules

Claude reads the detailed docs only when it needs them.

Real-World Examples

Node.js / TypeScript Project

# E-Commerce API

Online store backend. TypeScript, Express, Prisma, PostgreSQL.

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Test watch: `pnpm test:watch`
- Lint: `pnpm lint`
- DB migrate: `pnpm prisma migrate dev`
- DB seed: `pnpm prisma db seed`

## Rules

- Use Zod for all input validation
- All handlers must be async
- Use the Result pattern (no throwing in service layer)
- Logging via pino — structured JSON, never console.log
- All money values in cents (integer), never floating point
- Date/time always in UTC, use dayjs for formatting

## Structure

- `src/routes/` — Express route handlers
- `src/services/` — business logic (no HTTP concerns)
- `src/middleware/` — auth, error handling, logging
- `prisma/schema.prisma` — database schema
- See @docs/architecture.md for design decisions

Python / FastAPI Project

# Task Queue Service

Background job processor. Python, FastAPI, Celery, Redis.

## Commands

- Install: `pip install -e ".[dev]"`
- Run API: `uvicorn app.main:app --reload --port 8000`
- Run worker: `celery -A app.worker worker --loglevel=info`
- Test: `pytest -x --tb=short`
- Type check: `mypy app/`

## Rules

- Type hints on all function signatures
- Docstrings on all public functions (Google style)
- Use dependency injection for database and cache connections
- Tasks must be idempotent (safe to retry)
- All task payloads must be JSON-serializable
- Max task execution time: 5 minutes (configure in decorator)

## Structure

- `app/api/` — FastAPI routes
- `app/tasks/` — Celery task definitions
- `app/models/` — SQLAlchemy models
- `app/core/` — config, dependencies, exceptions
- See @docs/task-patterns.md for task design rules

Monorepo

# Platform Monorepo

Turborepo monorepo with web app, API, and shared packages.

## Commands

- Install: `pnpm install` (from root)
- Dev all: `pnpm dev`
- Build all: `pnpm build`
- Test all: `pnpm test`
- Test one package: `pnpm --filter @platform/api test`

## Packages

- `apps/web` — Next.js frontend (@platform/web)
- `apps/api` — Hono API server (@platform/api)
- `packages/shared` — shared types and utils (@platform/shared)
- `packages/db` — Drizzle ORM schema and client (@platform/db)
- `packages/ui` — shared React components (@platform/ui)

## Rules

- Shared types go in @platform/shared, never duplicate
- Each package has its own CLAUDE.md with package-specific rules
- Import from packages using @platform/* aliases
- Never import directly from another app (apps/web cannot import from apps/api)

AGENTS.md vs CLAUDE.md

You might have seen AGENTS.md files in some projects. Here is the difference:

If your team only uses Claude Code, use CLAUDE.md. If your team uses multiple AI tools (Claude Code, Cursor, GitHub Copilot), use AGENTS.md — most tools now support it.

You can use both. Claude Code reads both files. Put Claude-specific instructions in CLAUDE.md and general instructions in AGENTS.md.

Version Control

Always commit CLAUDE.md to git. This way:

• Every team member gets the same Claude Code behavior
• Instructions evolve with the project
• You can review changes in pull requests
• New team members get instant project context

Add it to your repository like any other config file:

git add CLAUDE.md
git commit -m "Add CLAUDE.md with project instructions"

Maintaining CLAUDE.md

CLAUDE.md is a living document. Update it when:

• You add a new technology or framework
• You change build or test commands
• You establish new coding conventions
• You find Claude Code making the same mistake repeatedly

Prune regularly. Remove instructions that are no longer relevant. A shorter, accurate CLAUDE.md is better than a long, outdated one.

Test your changes. After updating CLAUDE.md, start a new Claude Code session and check that the instructions take effect. Ask Claude to summarize what it knows about your project.

Custom Instructions vs CLAUDE.md

Claude has custom instructions in the web interface (claude.ai). These are different from CLAUDE.md:

Use custom instructions for personal preferences (“I prefer Python”, “I am a backend developer”). Use CLAUDE.md for project-specific rules (“This project uses FastAPI with async SQLAlchemy”).

Tips for Better CLAUDE.md Files

1. Start with /init — Let Claude Code generate the first draft, then edit it
2. Be specific — “Use ruff for linting” is better than “Follow best practices”
3. Give examples — “Error responses look like: {"error": "message", "code": 400}”
4. Use bullet points — Claude Code parses structured text more reliably than paragraphs
5. Test with new sessions — Start a fresh Claude Code session to verify instructions work
6. Keep it under 300 lines — Use @path/to/file imports for detailed docs
7. Update after failures — When Claude Code makes a mistake, add a rule to prevent it

Summary

CLAUDE.md is the single most effective way to make Claude Code better at your specific project. A well-written CLAUDE.md can save hours of repeated explanations.

What’s Next?

In the next article, we will dive deep into the Claude Messages API — multi-turn conversations, streaming, and token tracking.

Next: Messages API Deep Dive

Related Articles

• CLAUDE.md and AGENTS.md Guide
• Claude Code Setup Guide
• Claude Code CLI — Installation, Setup, and First Commands
• Prompt Engineering Basics
• What is Claude? AI Models, Capabilities, and Use Cases