What is a CLAUDE.md? A Markdown file placed in the root of your project. Claude Code reads it at the start of every session and treats it as permanent context. Use it to encode data formats, library preferences, naming conventions, deployment rules, test patterns, and — most importantly — the quirks that would otherwise be rediscovered the hard way. Build it once, update as decisions get made. By month two your AI knows the project before you've typed a word.

Pick a starting preset (optional)

Project basics

Project name (required)

One-sentence purpose

Primary language / runtime Key frameworks / libraries (comma or newline)

Package manager

Test runner

Conventions that would otherwise get re-explained

Code-style preferences (bullet points work) How to run tests How to run the dev server / build How to deploy

Data, external services, and secrets

Primary data model or schema location External services / APIs used Env vars required (do NOT paste the values — just names)

Quirks & hard rules

Anti-patterns Claude should never introduce Known quirks / gotchas in this codebase Review / commit expectations

Generated CLAUDE.md

Drop this file into the root of your repository (same level as package.json / pyproject.toml). Claude Code picks it up automatically on the next session. Nested CLAUDE.md files are also supported — put a second one inside a subdirectory if that subsystem has its own conventions.

Fill out the form above and click Generate CLAUDE.md.

What makes a good CLAUDE.md — and what to leave out

Include. Anything you would otherwise have to re-explain in the first 15 minutes of every session. Data formats. Library preferences. Naming conventions. Test commands. Deploy commands. Anti-patterns. The quirks nobody remembers until they cost an afternoon.

Leave out. Secrets (never paste a key, token, or password — put env-var NAMES only). The full README contents (link to it instead). Historical decisions that are no longer load-bearing. Anything that changes every sprint.

Keep it under ~200 lines. If it grows past that, split it: put subsystem-specific conventions in a nested CLAUDE.md inside the relevant folder.

Update it as decisions get made. A one-line "we chose pnpm over npm because lockfile determinism" line saves the next session from re-litigating.