# Write a CLAUDE.md

> Create a CLAUDE.md file so Claude Code knows your project's commands, structure and rules at the start of every session.

Source: https://viralistic.nl/help/claude/write-a-claude-md

Every Claude Code session starts with a blank slate. `CLAUDE.md` is a plain Markdown file in your project that Claude Code reads at the start of each session, so it knows how the project works without you explaining it again. This article covers where the file goes, what to put in it and how to keep it useful.

## Where CLAUDE.md files live

You can have more than one. Claude Code loads them all and combines them.

| File                                                     | Scope                             | Shared with                       |
| -------------------------------------------------------- | --------------------------------- | --------------------------------- |
| `CLAUDE.md` or `.claude/CLAUDE.md` in the project folder | This project                      | Everyone, through Git             |
| `CLAUDE.local.md` in the project folder                  | This project, your personal notes | Only you (add it to `.gitignore`) |
| `~/.claude/CLAUDE.md` in your home folder                | All your projects                 | Only you                          |

Most teams start with one `CLAUDE.md` in the root of the repository and commit it.

## Create a starter file

The quickest start is to let Claude write the first version.

1. Open the project in Claude Code (terminal, desktop app or VS Code).
2. Run `/init`.
3. Claude scans the project and writes a `CLAUDE.md` with the commands, structure and conventions it finds.
4. Read it, delete what is wrong or obvious, and add what Claude could not know.

If a `CLAUDE.md` already exists, `/init` suggests improvements instead of overwriting it.

## What to put in it

Write down what you would otherwise repeat in every session, or what a new teammate would need on day one.

- **What the project is**, in two or three sentences.
- **Commands**: how to install, start the dev server, build and test.
- **Structure**: where the important things live.
- **Conventions**: naming, styling, language, formatting.
- **Rules**: things Claude must always or never do.
- **How to check work**: which command proves a change is correct.

## An example

Here is a compact `CLAUDE.md` for an Astro website:

```md
# Project: company website

Marketing site built with Astro and Tailwind. Content is Markdown in
src/content/. Deployed on Netlify from the main branch.

## Commands

- Install: npm install
- Dev server: npm run dev (http://localhost:4321)
- Build: npm run build (must pass before you say a task is done)

## Structure

- src/content/pages/: one Markdown file per page
- src/components/: reusable UI components
- src/layouts/: page layouts
- public/images/: images, referenced as /images/...

## Conventions

- Write UI text in Dutch unless the file is under src/content/pages/en/.
- Use existing components before creating new ones.
- Tailwind classes only, no new CSS files.
- File names in kebab-case.

## Rules

- Never edit files in dist/ or node_modules/.
- Never commit .env files or API keys.
- Ask before adding a new npm package.
- Do not push to main. Work on a branch and tell me when it is ready.
```

## Write instructions Claude can follow

Claude treats `CLAUDE.md` as guidance, so clear wording matters.

| Vague                          | Concrete                                                             |
| ------------------------------ | -------------------------------------------------------------------- |
| "Keep the code clean"          | "Use 2-space indentation and run `npm run lint` before finishing"    |
| "Test your changes"            | "Run `npm run build` and fix all errors before you say you are done" |
| "Put files in the right place" | "Page content goes in `src/content/pages/`"                          |

> **Tip:** Explain the reason behind a surprising rule. "Do not rename files in src/content/pages/, because the file name is the page URL" works better than "do not rename files".

## Keep it short

Aim for under about 200 lines. A long file uses more of Claude's working memory and makes each rule less likely to be followed.

- Leave out things Claude can see for itself, such as every dependency in `package.json`.
- Move long procedures (for example "how to add a new page type") into a [skill](https://viralistic.nl/help/claude/what-is-a-skill). Skills only load when needed.
- Point to longer documents instead of copying them. You can import a file by writing `@` and its path, for example `@docs/brand-guidelines.md`. Imported files still load at the start of every session, so use this sparingly.

> **Warning:** Never put passwords, API keys or customer data in `CLAUDE.md`. The project file is usually committed to Git and visible to everyone with access to the repository.

## Maintain it

`CLAUDE.md` gets better through use.

1. When Claude makes the same mistake twice, add a rule.
2. When you correct Claude in chat with something that will always be true, ask: "Add that to CLAUDE.md."
3. Every month or so, remove rules that are outdated or contradict each other.
4. To check which memory files a session loaded, run `/context`.

Changes to `CLAUDE.md` go through Git like any other file, so the whole team benefits from each improvement.

## Next steps

- [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code)
- [Create a skill](https://viralistic.nl/help/claude/create-a-skill)
- [How a Viralistic Astro site is organised](https://viralistic.nl/help/astro/project-structure)
- [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code)