Custom CLAUDE.md Files: Teaching AI Agents Your Conventions

Every time I started a new Claude Code session, I spent five minutes re-explaining my coding conventions. Use FastAPI not Flask. Use Pydantic for validation. Never use em dashes. Then I discovered CLAUDE.md and those five minutes disappeared.

What CLAUDE.md Is

CLAUDE.md is a configuration file that lives in your project root. When Claude Code starts a session, it reads this file first and treats its contents as persistent instructions. Everything in CLAUDE.md applies to every conversation in that project.

A Real CLAUDE.md

Here is a simplified version of what I use:

# Project Instructions
 
## Tech Stack
- Backend: FastAPI + DynamoDB (boto3)
- Frontend: Next.js 15 + React 19 + Tailwind v4
- Admin: Separate Next.js app at admin.peaklight.ai
 
## Code Conventions
- Python: type hints, 4-space indent, Pydantic for all models
- TypeScript: strict mode, ES modules, functional components
- Never use em dashes in any content or output
- Run linting/type checks before committing
 
## API Patterns
- All endpoints follow existing patterns in src/routers/
- Pydantic models in src/models.py
- Return 201 for creation, 404 for not found, 409 for conflict
 
## Git
- Conventional commits: feat, fix, test, refactor, docs, chore
- Scope format: (phase-plan) e.g., feat(00.4-02): description

What to Include

Include things the AI needs to know for every interaction:

1. Tech stack: What frameworks and libraries are in use
2. Code conventions: Naming, formatting, import organization
3. Architecture patterns: How the project is structured and why
4. Things to avoid: Common mistakes the AI should not make
5. Verification steps: What to check before declaring something done

What NOT to Include

Do not include:

• Task-specific instructions (those go in your prompts)
• Secrets or API keys (CLAUDE.md is committed to git)
• Lengthy documentation (keep it under 100 lines)
• Redundant information that the AI can infer from the codebase

The Layered Approach

CLAUDE.md supports multiple levels:

~/.claude/CLAUDE.md           # Personal conventions (all projects)
project/.claude/CLAUDE.md     # Project conventions
project/src/.claude/CLAUDE.md # Directory-specific conventions

I use the global file for personal preferences (explain simply, no jargon, verify before declaring done). I use the project file for tech stack and patterns specific to that codebase.

The Payoff

After setting up CLAUDE.md, every Claude Code session starts with full context. The agent knows the tech stack, follows the conventions, and avoids known pitfalls. No repetition. No re-explaining. Just productive work from the first prompt.

See the Claude Code project configuration docs for the complete CLAUDE.md specification.