How to write CLAUDE.md — instructions for Claude Code

Claude Code starts every session with a clean context and doesn't remember your stack, how to run tests, or what must never be touched in the project. CLAUDE.md solves that: it's a file of persistent instructions the agent loads at the start of every session. Below: where it lives, what to put in it, what to avoid, and what extra text in it costs.

What CLAUDE.md is and where it lives

CLAUDE.md is a plain markdown file. Claude Code reads it at launch and keeps its contents in context for the whole session. According to the Claude Code documentation, there are several levels:

Important: the files don't override each other, they stack. Claude Code loads every CLAUDE.md it finds in the current folder and the folders above it, and loads files from subfolders when it starts working with files there. If your repository already has an AGENTS.md, Claude Code can read it too.

The quick start is the /init command in a session: Claude Code studies the repository and proposes a CLAUDE.md draft. Edit the files with /memory, and check what actually loaded with /context (the Memory files section).

What to put in CLAUDE.md

Write down what you would otherwise have to explain to the agent again: build commands, conventions, project layout, "always do X" rules. A good signal to add a line: the agent makes the same mistake a second time.

Instructions should be verifiable: "use 2-space indentation" instead of "format code properly", "run npm test before committing" instead of "test your changes".

Stack and commands

## Tech Stack
- Python 3.11, FastAPI, PostgreSQL
- Package manager: poetry

## Build & Test
- Install: `poetry install`
- Run: `poetry run uvicorn src.main:app --reload`
- Test: `poetry run pytest tests/` — must pass before commit
- Lint: `ruff check src/ && mypy src/`

Style and structure

## Code Style
- Type hints required for all functions
- Google-style docstrings for public APIs
- Max line length: 100

## Project Structure
- `src/api/routes/` — HTTP handlers
- `src/models/` — SQLAlchemy models
- `migrations/` — Alembic migrations

Rules and key context

## Rules
- Never edit existing migrations, only add new ones
- Never commit `.env` or credentials
- Multi-tenant app: every query must filter by tenant_id
- DB access is async: use `async_session()`

Keep in mind: CLAUDE.md is context, not enforced configuration. If an action must be blocked for sure, Claude Code has permission rules and hooks for that.

What not to include

• Secrets. No keys, passwords, or tokens: the project CLAUDE.md lives in git, and its text is sent to the model with every request.
• The whole project wiki. Don't paste documentation wholesale. Point to the path: "architecture is described in docs/ARCHITECTURE.md" — the agent will read the file when it needs it.
• Long code samples. One or two lines as an example, not full scripts.
• Project history. Who started the project and when doesn't help the agent work.
• Contradictions. If two rules conflict, the agent may pick either one. Prune outdated rules periodically.

A note on imports: a line like @docs/guide.md in CLAUDE.md pulls the whole file in at launch. It helps with organization but doesn't save context. If a file is needed only occasionally, mention its path in backticks without @. For rules that apply only to part of the code, the Claude Code docs describe a .claude/rules/ folder with path scoping — those rules load only when the agent works with matching files. And HTML comments <!-- ... --> are stripped before the content reaches the model, so you can use them for notes to humans.

Why a short file costs less

The contents of CLAUDE.md are part of the context of every model call, and the agent makes many such calls per task. The Claude Code docs recommend keeping the file under 200 lines: a long file takes up context and is followed less reliably.

Example with Zukko prices for claude-sonnet-5 ($0.30 per 1M input tokens), 100 model calls per day:

The difference is about $4 a month on this file alone. With Anthropic's official API, repeated context is partly billed at the cache-read price (around 10% of the input price), while in Zukko cached tokens cost the same as regular input tokens. So when you work through Zukko, the size of CLAUDE.md affects the bill more directly, and keeping it concise pays off.

Starter template

## Project: MyApp
FastAPI backend for an internal CRM.

## Tech Stack
- Python 3.11, FastAPI, PostgreSQL 14, poetry

## Commands
- Install: `poetry install`
- Run: `poetry run uvicorn src.main:app --reload`
- Test: `poetry run pytest` — must pass before commit
- Lint: `ruff check . && mypy src/`

## Code Style
- Type hints required, Google-style docstrings, line length 100

That's enough for the agent to stop guessing about commands and rules.

Connecting Claude Code to Zukko

Claude Code works through Zukko with the same CLAUDE.md files. You only need two variables in the env block of ~/.claude/settings.json: ANTHROPIC_BASE_URL = https://api.zukko.pro (no /v1) and ANTHROPIC_AUTH_TOKEN = your fetch_... key. Create the key on the API keys page↗; the full setup is in the Claude Code guide↗.

FAQ

Do I need CLAUDE.md if I have a README?

Yes, they serve different purposes. The README explains the project to people; CLAUDE.md gives the agent short working rules: commands, prohibitions, conventions. You can reference the README from CLAUDE.md, but don't copy it.

Who can see CLAUDE.md?

The project CLAUDE.md is an ordinary file in the repository: anyone with access to the code can see it, and it is sent to the model as part of the context. Keep personal project notes in CLAUDE.local.md and add it to .gitignore.

Can I link to external pages?

You can, but the agent will have to fetch the page separately (if you allow it), which is an extra step and extra tokens. It's more reliable to put the essentials into a local file and point to its path.

Does CLAUDE.md work in the VS Code extension?

Yes. The extension runs the same Claude Code, so CLAUDE.md, ~/.claude/CLAUDE.md, and CLAUDE.local.md load the same way as in the terminal.