So far you've always given instructions and context directly in conversation. That works well for one-off requests - but for rules that should apply to an entire project on an ongoing basis, there's a much better way: the CLAUDE.md file.

What is CLAUDE.md?

CLAUDE.md is a perfectly normal Markdown text file that lives in a project's root directory. When you start Claude Code inside that project, the content of this file is automatically read in and is then available as background knowledge for the whole session - so you don't need to repeat that information in every new conversation.

That makes CLAUDE.md the project-wide counterpart to the project-level background information you saw with Claude.ai projects in chapter 2 - just stored directly inside the project itself, versioned together with the rest of the code.

What typically belongs in a CLAUDE.md

• The tech stack used (programming language, framework, database, frontend technology).
• Coding standards and preferred patterns (e.g. "Always use TypeScript interfaces instead of any").
• How to run tests, build the code, or start the project locally.
• Project-specific conventions (naming schemes, folder structure, commit message format).
• Things to deliberately avoid ("Don't add a new dependency without checking first").

a-simple-example

# Project Rules

## Tech Stack
- Node.js with Express
- Plain JSON file as storage, no database
- Tests with the built-in Node test runner (`node --test`)

## Conventions
- Always use meaningful variable names in English
- New functions get a short comment describing what they do
- After every change: run `npm test` before considering the change done

If you start Claude Code in a project with this CLAUDE.md, it knows from the very first message that it shouldn't suggest a database, for example, and should stick with the plain JSON file instead - without you having to repeat that every time.

Letting Claude Code create a CLAUDE.md itself

You don't have to write a CLAUDE.md entirely by hand: in an existing project, Claude Code can analyse the project and propose a first draft of a fitting CLAUDE.md, which you then adjust and extend as needed.

Why it's worth it

Without CLAUDE.md you'd need to mention recurring requirements ("always use this test strategy", "stick to this naming scheme") again in every new conversation - that's tedious and easy to forget. With CLAUDE.md, those requirements apply automatically, stored in one place that other people on the team can also view and maintain. Chapter 25 covers this in more detail when it comes to teamwork.

Starting with the next block, CLAUDE.md becomes practically relevant: you'll build your own example project there, the recipe planner, and set up its own CLAUDE.md right at the start.