GUIDE

How to write a CLAUDE.md file

CLAUDE.md is the file Claude Code reads at the start of every session to learn your project: how to build and test it, how the code is organized and the rules it should follow. A good one saves you from explaining the same things in every conversation.

This guide follows Anthropic’s own documentation, checked on September 26, 2026, and ends with a way to write yours from a project description or a public README.

Create my CLAUDE.md Describe your project or paste its README. Free to start, no account needed.

Updated

What a CLAUDE.md file is

A CLAUDE.md is a plain Markdown file of standing instructions. Claude Code loads it into its context when a session starts, so everything in it applies to every task in that project. Anthropic describes it as context rather than enforced configuration: specific, concise instructions are followed most consistently.

Anthropic suggests adding to it when Claude makes the same mistake twice, when a code review catches something Claude should have known, or when you find yourself typing the same correction again.

Where the file goes

  • Project instructions, shared with your team through version control: CLAUDE.md or .claude/CLAUDE.md in the repository root.
  • Personal instructions for every project: ~/.claude/CLAUDE.md in your home folder.
  • Personal notes for one project that should not be committed: CLAUDE.local.md in the project root, added to .gitignore.
  • A CLAUDE.md in a subfolder loads when Claude works with files in that folder.

Running /init in Claude Code generates a starting file from your codebase. Refine it with what Claude cannot discover on its own.

What to put in it

  1. A one-line overview. A sentence or two on what the project is. Skip what the code already shows: Anthropic’s own check for these files trims directory layouts, dependency lists and architecture overviews.
  2. Commands. The exact commands to install, build, test, lint and run it, in backticks.
  3. Code style. Conventions that are concrete enough to check, such as “use 2-space indentation”, not “format code properly”.
  4. What the code does not show. Generated files not to edit by hand, folders to leave alone, and where the project departs from its framework’s defaults.
  5. Workflow. Branch and commit conventions, and what to run before calling a task done.
  6. Things to avoid. Files not to touch, commands not to run and the mistakes Claude has made before.

How long, and how to write it

  • Anthropic’s target is under 200 lines per file: longer files take up more context and are followed less reliably.
  • Use Markdown headings and bullet points rather than paragraphs.
  • Remove rules that contradict each other; Claude may pick one of them arbitrarily.
  • Move long procedures into a skill, and rules for one part of the code into a path-scoped rule under .claude/rules/.
  • Split a large file with imports: a line such as @docs/testing.md pulls that file in.
  • HTML comments in a CLAUDE.md are stripped before it reaches Claude, so they can hold notes for people at no cost in context.

An example CLAUDE.md

Example: CLAUDE.md for a small web app
# [Project name]

## Overview
A web app for [who it serves] that lets them [what it does]. Front end in [framework], API in [framework], data in [database].

## Commands
- Install: `[install command]`
- Dev server: `[dev command]`
- Test: `[test command]`
- Lint and types: `[lint command]`

## Code style
- [Language] with strict types; no `any`.
- Use 2-space indentation and named exports.

## Project structure
- `[client folder]`: the front end
- `[server folder]`: API routes and database access

## Workflow
- Work on a branch; never commit to main.
- Before finishing, run `[test command]` and `[lint command]` and fix what fails.

## Avoid
- Editing generated files in `[generated folder]`.
- Adding a dependency without saying why.

An illustrative example, written by hand. Replace each part in brackets with your project’s own details, and leave out anything that does not apply.

For real ones, see 10 CLAUDE.md files from open-source projects, graded and shown whole.

Write yours from your README

In LoopTypes, choose CLAUDE.md under Agent file, describe your project or paste its README or a public GitHub link, and create. You get a complete CLAUDE.md in the sections above, built only from what you supplied, with anything it does not know left as a [placeholder] to fill in. Download it under its own name and commit it.

Already have one? Grade my file scores it on six ingredients and gives you an improved version.

Questions

Is CLAUDE.md the same as AGENTS.md?

They do the same job for different tools. Claude Code can read an AGENTS.md directly, or you can import one into your CLAUDE.md with a line that reads @AGENTS.md. See what AGENTS.md is.

How do I check that Claude loaded my file?

Anthropic’s documentation suggests running /context in a session and looking for the file under Memory files.

Should I put secrets in CLAUDE.md?

No. A project CLAUDE.md is committed with your code, so keep passwords, keys and personal details out of it.

Sources