# CLAUDE.md Configuration Guide

`CLAUDE.md` is Claude Code's **project-level configuration file**. Every time Claude Code starts, it automatically reads the project's `CLAUDE.md` to learn about the project architecture, coding conventions, and special agreements, enabling it to understand your project more accurately.

## Why You Need CLAUDE.md

Without CLAUDE.md, you may need to repeatedly explain in every conversation:
- "This project uses pnpm, not npm"
- "The test command is `yarn test:unit`, not `npm test`"
- "All components use TypeScript — no `any` types"

Write this information into CLAUDE.md and Claude will read it automatically on every startup, so you never have to repeat yourself.

## File Hierarchy

Claude Code reads and merges CLAUDE.md files from multiple levels:

| Location | Scope |
|----------|-------|
| `~/.claude/CLAUDE.md` | Global configuration, applies to all projects |
| `<project root>/CLAUDE.md` | Project configuration, committed to Git for team sharing |
| `.claude/CLAUDE.md` | Private project configuration, can be added to `.gitignore` |
| `CLAUDE.md` in a subdirectory | Only read when Claude is operating in that directory |

## Quick Setup

Use the `/init` command to generate one automatically:

```
/init
```

Claude will analyze the current project structure and auto-generate a CLAUDE.md populated with project information.

## Basic Structure

```markdown
# Project Name

## Overview
Brief description of the project's purpose and tech stack.

## Tech Stack
- Runtime: Node.js 20
- Framework: Next.js 15
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma

## Common Commands
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
- Lint code: `npm run lint`

## Coding Conventions
- Use TypeScript; no `any` types allowed
- Components use functional style
- Styling with Tailwind only — no inline styles
- Commit message format: `feat:` / `fix:` / `docs:` prefixes, etc.

## Project Structure
- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utility functions
- `prisma/` — Database schema and migrations

## Notes
- Do not modify `prisma/migrations/` — only create new migrations
- All API routes are under `src/app/api/`
- Image assets go in `public/images/`
```

## Practical Tips

### 1. Specify the Package Manager

```markdown
## Package Management
Use pnpm — do not use npm or yarn.
Install dependencies: `pnpm install`
Add a dependency: `pnpm add <package>`
```

### 2. Document Testing Conventions

```markdown
## Testing
- Unit tests: `vitest`, files end in `.test.ts`
- E2E tests: `playwright`, located in `tests/e2e/`
- Run unit tests: `pnpm test:unit`
- Run E2E: `pnpm test:e2e`
- New features must include tests
```

### 3. Specify Prohibited Actions

```markdown
## Prohibited Actions
- Do not use `console.log` — use the project's `logger` module instead
- Do not modify `package-lock.json` directly
- Do not commit directly to `main` — use feature branches
```

### 4. Provide Architectural Context

```markdown
## Architecture Overview
This project follows Hexagonal Architecture:
- `domain/` — Business logic, no external framework dependencies
- `application/` — Use cases, coordinating domain and infrastructure
- `infrastructure/` — External adapters for databases, HTTP, etc.
- `interfaces/` — Entry points such as web controllers and CLI

New features should follow this layering — do not introduce external dependencies in the domain layer.
```

### 5. Reference Other Documents

```markdown
## Further Reading
- API documentation: `docs/api.md`
- Deployment process: `docs/deploy.md`
- Database schema: `prisma/schema.prisma`
```

## CLAUDE.md and Context Management

The contents of CLAUDE.md consume context space. Recommendations:
- Keep CLAUDE.md concise and focused on the most important information
- For detailed architecture documentation, provide file path references in CLAUDE.md rather than copying content directly
- In long sessions, CLAUDE.md always remains visible (it will not be removed by `/compact`)

## Project Templates

The structures below are battle-tested CLAUDE.md starting points for common project types. Copy the one that matches your stack and adapt the details.

### Template 1: React + TypeScript Frontend

```markdown
# MyApp Frontend

## Tech Stack
- React 19 + TypeScript 5.x
- Build tool: Vite 6
- Styling: Tailwind CSS v4 (utility-first, no inline styles)
- State management: Zustand (global), TanStack Query (server state)
- Routing: React Router v7
- Testing: Vitest + Testing Library + MSW

## Commands
- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test` (Vitest watch mode)
- Single run: `pnpm test:run`
- Build: `pnpm build`
- Lint: `pnpm lint` (ESLint + Prettier)
- Type check: `pnpm typecheck`

## Coding Conventions
- Components: functional components + Hooks, no class components
- Props: define with `interface` (not `type`)
- File names: components in PascalCase (UserProfile.tsx), utilities in camelCase (formatDate.ts)
- Import order: React → third-party → internal → styles
- No `any` type; explicit type annotations are required
- Async work goes through TanStack Query, not direct `useEffect` + `fetch`

## Project Structure
- src/components/ — reusable UI components
- src/pages/ — route pages
- src/hooks/ — custom Hooks
- src/api/ — API request wrappers (TanStack Query queryFn)
- src/stores/ — Zustand stores
- src/lib/ — utility functions
- src/types/ — global type definitions

## Notes
- Package manager: pnpm (not npm or yarn)
- Node.js 22+
- All API requests go through src/api/client.ts (with interceptors)
- Images live in public/images/, referenced via the /images/ path
```

### Template 2: Python + FastAPI Backend

```markdown
# MyApp Backend

## Tech Stack
- Python 3.12 + FastAPI
- ORM: SQLAlchemy 2.0 (async) + Alembic migrations
- Database: PostgreSQL 16
- Cache: Redis 7
- Testing: pytest + httpx + factory_boy

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `pytest -xvs`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy app/`

## Coding Conventions
- Type hints: all function parameters and return values must have type hints
- async/await: all I/O operations use async
- Pydantic v2: request/response schemas use Pydantic BaseModel
- Dependency injection: inject database connections, auth, etc. via FastAPI Depends()
- Error handling: business exceptions inherit from app.exceptions.AppError

## Project Structure
- app/main.py — application entry point
- app/api/ — routes (one file per resource)
- app/models/ — SQLAlchemy models
- app/schemas/ — Pydantic schemas
- app/services/ — business logic
- app/core/ — config, database, security, and other core modules
- tests/ — test files (mirror the app/ structure)
- alembic/ — database migrations

## Notes
- Do not modify existing migration files under alembic/versions/
- The .env file is not committed to Git; it is loaded via the Settings class in app/core/config.py
- Virtual environment: `python -m venv venv && source venv/bin/activate`
```

### Template 3: Go Microservice

```markdown
# MyService

## Tech Stack
- Go 1.23
- HTTP framework: Echo v4
- Database: PostgreSQL + sqlc (type-safe SQL)
- Message queue: NATS JetStream
- Containerization: Docker + docker-compose

## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
- Generate sqlc: `sqlc generate`
- Lint: `golangci-lint run`

## Coding Conventions
- Error handling: always check err, never ignore it with _
- Interface naming: single-method interfaces take the -er suffix (Reader, Writer)
- Package naming: lowercase words, no underscores
- Logging: use slog for structured logging
- Context: pass context.Context as the first parameter of every function

## Project Structure (standard Go layout)
- cmd/server/ — main program entry point
- internal/handler/ — HTTP handlers
- internal/service/ — business logic
- internal/repository/ — data access layer
- internal/model/ — data models
- sql/ — SQL query files (used by sqlc)
```

### Template 4: Monorepo (Turborepo)

```markdown
# MyPlatform Monorepo

## Tech Stack
- Package management: pnpm workspace
- Build system: Turborepo
- Language: TypeScript across the stack

## Commands
- Global dev: `pnpm dev`
- Global test: `pnpm test`
- Global build: `pnpm build`
- Single-package dev: `pnpm --filter @myplatform/web dev`
- Add a dependency: `pnpm --filter @myplatform/api add express`

## Package Structure
- apps/web/ — Next.js frontend
- apps/api/ — Express backend
- apps/admin/ — admin dashboard
- packages/ui/ — shared UI component library
- packages/config/ — shared config (eslint, tsconfig)
- packages/types/ — shared type definitions

## Notes
- Shared code goes in packages/; do not import directly between apps
- When creating a new package, follow the format of packages/ui/package.json
- Turborepo cache: build artifacts are cached in node_modules/.cache/turbo
```

### Template 5: Data Science / ML Project

```markdown
# ML Pipeline

## Tech Stack
- Python 3.12
- Framework: PyTorch 2.5 + Lightning
- Data processing: Polars (not Pandas)
- Experiment tracking: MLflow
- Dependency management: uv

## Commands
- Train: `python -m src.train --config configs/experiment.yaml`
- Evaluate: `python -m src.evaluate --checkpoint runs/latest`
- Preprocess data: `python -m src.preprocess --data-dir data/raw`
- Jupyter: `jupyter lab`
- Test: `pytest tests/`

## Coding Conventions
- Use YAML for configuration (do not hard-code hyperparameters)
- Use Polars for data processing (faster than Pandas, type-safe)
- All experiments must be logged to MLflow
- Notebooks are for exploration only; production code must live in src/

## Project Structure
- configs/ — experiment configuration YAML
- data/raw/ — raw data (not committed to Git, managed with DVC)
- data/processed/ — processed data
- src/ — core code (model, data, train, evaluate)
- notebooks/ — exploratory analysis
- runs/ — training outputs (checkpoints, logs)
```

## Team Collaboration Best Practices

### Git strategy

```
CLAUDE.md          → commit to Git (shared by the team)
.claude/CLAUDE.md  → add to .gitignore (personal configuration)
```

Add this to `.gitignore`:

```gitignore
# Personal Claude Code configuration
.claude/CLAUDE.md
.claude/settings.local.json
```

### Code review checklist

On every PR review, check:
- Was CLAUDE.md updated when a new technology was introduced?
- Was the "Project Structure" section updated when the layout changed?
- Was the "Commands" section updated when an important command was added?

### Onboarding guide

CLAUDE.md doubles as the best onboarding document for a project:
1. After cloning, a new developer reads CLAUDE.md to get the big picture
2. They run `claude` → Claude already knows every project convention
3. They start exploring with `> help me understand this project`

---

## Advanced Tips

### Reference, don't inline

CLAUDE.md should not grow too long. For detailed documents, reference the path instead of inlining the content:

```markdown
## Architecture
Detailed architecture doc: `docs/architecture.md`.
API design conventions: `docs/api-design.md`.
Database schema: `prisma/schema.prisma`.
```

Claude reads those files automatically when it needs them.

### Relationship with AGENTS.md

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| Tool | Claude Code | Codex CLI |
| Format | Markdown | Markdown |
| Content | 80%+ can be reused | 80%+ can be reused |

If you use both Claude Code and Codex, the two files can coexist:
- **Shared content**: tech stack, commands, coding standards, project structure
- **Tool-specific**: Claude's `/model` and `/plan` guidance goes in CLAUDE.md; Codex's approval mode configuration goes in AGENTS.md

> See the [AGENTS.md Guide](/docs/usage/agents-md).

### Controlling context usage

The content of CLAUDE.md is always in the context (`/compact` never removes it). Recommendations:

- **Keep the total under 500 lines**
- Reference paths instead of inlining detailed documents
- Don't put frequently changing information there (such as current progress)
- Don't put code examples there (Claude can read the source itself)

---

## Common Mistakes and Debugging

### CLAUDE.md is not being read

```bash
# Confirm the file is in the project root
ls -la CLAUDE.md

# Confirm Claude sees it
claude
> Do you see CLAUDE.md? What tech stack does it describe?
```

### It is too long and starves the context

```bash
# Check the line count
wc -l CLAUDE.md
# Over 500 lines: trim it

# Check context usage
/cost
```

### Team members behave differently

Everyone's global `~/.claude/CLAUDE.md` differs. If the team sees inconsistent behaviour, check:
1. Is the project-root CLAUDE.md specific enough?
2. Has someone overridden the team rules in `.claude/CLAUDE.md`?

---

## CLAUDE.md vs AGENTS.md — How to Choose

Claude Code reads `CLAUDE.md` natively (along with its memory files and path-scoped rules). Most **other** tools — Cursor, Codex, GitHub Copilot, Cline, Gemini / Antigravity, Aider, Zed, and more — read `AGENTS.md` instead. Which file you maintain depends on how many tools your team uses.

| Scenario | Recommendation |
|----------|----------------|
| **Single tool (Claude Code only)** | `CLAUDE.md` is enough — no need for AGENTS.md |
| **Multi-tool team** | Keep `AGENTS.md` as the shared source of truth, plus a thin `CLAUDE.md` that imports it |

### Single tool: just CLAUDE.md

If everyone on the team uses Claude Code, put everything in `CLAUDE.md`. There is nothing to gain from a second file.

### Multi-tool: AGENTS.md as the source of truth

When the team mixes Claude Code with Cursor, Codex, Copilot, or others, keep the shared rules — tech stack, commands, coding conventions, project structure — in `AGENTS.md`, then make `CLAUDE.md` a thin file that imports it and adds Claude-only extras:

```markdown
# Project Rules

@AGENTS.md

## Claude Code specifics
- Use /model to switch to Opus 4.8 for large refactors
- Reference docs/architecture.md instead of pasting it
```

The `@AGENTS.md` line pulls the shared content into Claude Code's context, so Claude gets the team rules **plus** its Claude-only additions. **Avoid maintaining two divergent copies** of the same rules — that is the main pitfall, because the two files inevitably drift out of sync.

> For details on the AGENTS.md format and its tooling, see [AGENTS.md Configuration Guide](/docs/usage/agents-md).

## Next Steps

- Learn about [Context Management](/docs/usage/context-management) — master techniques for managing the context window
- Learn about [Permission Configuration](/docs/usage/permissions) — control which operations Claude is allowed to perform
- Learn about [Workflow Tips](/docs/usage/workflow-tips) — establish an efficient Claude Code workflow