The CLAUDE.md File — What It Actually Does and How /init Bootstraps It

Every time you start a Claude Code session, it starts fresh — no memory of yesterday's decisions, your naming conventions, or the fact that you never want it to touch the legacy/ folder. CLAUDE.md is how you fix that.

The jargon

CLAUDE.md — A plain Markdown file that Claude Code reads automatically at the start of every session in that project. Think of it as a standing briefing note.

/init — A slash command built into Claude Code that scans your project and writes a first-draft CLAUDE.md for you.

Project root — The folder you opened Claude Code in. CLAUDE.md lives here.

The lesson

CLAUDE.md is not a config file. It is not parsed by code. Claude just reads it as text, the same way it reads anything else — but it reads it first, before your first message, every single session. That means anything in CLAUDE.md shapes every response in that project, automatically, without you having to repeat yourself.

Most people discover it exists, drop in a few notes, and leave it there. The better move is to treat it as a living document you update as you learn what Claude keeps getting wrong.

How it works

Run /init in a project you haven't set up yet:

/init

Claude Code will scan your files — directory structure, package files, existing README, any config it can find — and write a CLAUDE.md that includes:

• What kind of project this appears to be
• Key folders and what they contain
• Any commands it found (build, test, lint)
• Inferred conventions (language, framework, style)

You then edit that file. The parts Claude got right, keep. The parts it got wrong or missed, fix.

A mature CLAUDE.md for a consulting project might look like this:

# Project: Client Reporting Pipeline

## What this is
n8n workflows + Python scripts that pull data from HubSpot and generate PDF reports.

## Key folders
- `workflows/` — exported n8n JSON. Don't edit these manually.
- `scripts/` — Python. Entry point is `run.py`.
- `output/` — generated files. Never commit these.

## Conventions
- British English in all user-facing strings.
- Snake_case for Python variables, kebab-case for file names.
- All dates in ISO 8601 (2026-06-01).

## Do not touch
- `legacy/v1/` — archived. Leave it alone.

Claude reads this before anything else. You don't paste it in. You don't reference it. It just works.

When to reach for it / when not to

Use CLAUDE.md any time you're doing more than one session on a project. It pays back immediately. Skip it for throwaway one-shot tasks where there's no project folder to speak of.

Don't dump your entire README into it. Claude's context window is finite. Keep CLAUDE.md focused on what Claude needs to behave correctly, not what a human needs to understand the project.

Try it

Open a project you've been working on in Claude Code and run /init. Read what it produces. Find one thing it got wrong and one thing it missed. Fix both. That edited file is now more useful than most people's CLAUDE.md ever gets.