CLAUDE.md generator

How to use this CLAUDE.md generator

• Pick the file. Project (./CLAUDE.md), local (./CLAUDE.local.md), or user (~/.claude/CLAUDE.md) — the header, hints, and save path follow your choice.
• Pick a stack preset. Next.js, React + Vite, Django, FastAPI, Rails, Go, Rust, a Node API, or a pnpm monorepo pre-fill real commands (dev, build, lint, typecheck, and a single-test command) plus conventions. Edit anything.
• Shape the sections. Toggle, rename, and reorder them; add, remove, and reorder rules; mark the one rule Claude keeps skipping as important; paste tree output and the repo map drops node_modules, build output, and lockfiles.
• Watch the meter. The output updates live with a length meter against the ~200-line target and lint hints for vague rules, over-used emphasis, duplicates, contradictions, and secrets.
• Ship it. Copy it, download it as CLAUDE.md, or save it as AGENTS.md for other coding agents. Already have one? Switch to "Improve an existing one", paste it, and get the same lint report with line numbers — then load it into the builder to rework it.

What is a CLAUDE.md file?

Every Claude Code session starts with a fresh context window. A CLAUDE.md file is how you carry knowledge across sessions: a Markdown file of instructions that Claude reads at the start of every conversation — the commands, conventions, and rules you'd otherwise re-explain each time. The official docs put it simply: treat CLAUDE.md as the place you write down what you'd otherwise re-explain.

Add to it when Claude makes the same mistake a second time, when a code review catches something Claude should have known about the codebase, or when you type the same correction you typed last session. Keep it to facts Claude needs in every session; a multi-step procedure belongs in a skill, and a rule that only applies to part of the codebase belongs in a path-scoped rule under .claude/rules/.

One thing a CLAUDE.md is not: enforcement. Its content arrives as context (a user message after the system prompt), so Claude follows it well but not with a guarantee. Anything that must happen every time — formatting after each edit, blocking writes to a folder — belongs in a hook or in permission settings.

Claude Code memory: where CLAUDE.md files live

CLAUDE.md files can live in four places. Claude Code loads them from broadest to most specific, so a project instruction appears in context after a user instruction:

CLAUDE.local.md: personal notes for one project

CLAUDE.local.md sits next to the project CLAUDE.md and holds what's yours alone — your sandbox URLs, preferred test data, local quirks. It loads alongside the project file (after it, at the same level), so add it to .gitignore. Because a gitignored file only exists in the worktree where you created it, people who juggle several git worktrees can import a file from their home directory instead.

How CLAUDE.md files load

• Claude Code loads CLAUDE.md and CLAUDE.local.md from the directory you launch it in and every directory above it. Launch in foo/bar/ and both foo/CLAUDE.md and foo/bar/CLAUDE.md load.
• Files are concatenated, not overridden: root first, your working directory last, and within a directory CLAUDE.local.md comes after CLAUDE.md. If two files contradict each other, Claude may pick either — keep them consistent.
• CLAUDE.md files in subdirectories load on demand, when Claude reads files in that subdirectory — ideal for per-package rules in a monorepo. The claudeMdExcludes setting skips files from other teams.
• Block-level HTML comments (<!-- like this -->) are stripped before the file reaches Claude, so notes for human maintainers cost no context.
• The project-root CLAUDE.md survives /compact: Claude re-reads it from disk afterwards. Run /context to see which memory files loaded, and /memory to open and edit them.

What to put in a CLAUDE.md file

The docs' rule of thumb: include what Claude can't infer from the code, and leave out what it can.

A complete CLAUDE.md example

About 45 lines for a real Next.js app — every line is something Claude would otherwise get wrong. Load a preset above to start from something similar.

# acme-dashboard

Internal dashboard for the support team: Next.js App Router + Postgres (Drizzle). Server components by default.

## Commands

- `pnpm dev` — dev server on localhost:3000
- `pnpm test` — all tests (Vitest)
- `pnpm vitest run src/lib/billing.test.ts` — one file; prefer this while iterating
- `pnpm lint && pnpm typecheck` — must pass before a task is done
- `pnpm db:migrate` — apply Drizzle migrations

## Code style

- TypeScript strict; no `any` — use `unknown` and narrow
- Server components by default; "use client" only for state or browser APIs
- Import from `@/…`, never `../../..`
- Money is integer cents everywhere; format only in the UI

## Testing

- Tests sit next to the code as `*.test.ts`
- Every bug fix gets a regression test

## Repo map

```text
src/
├── app/          # routes
├── components/   # shared ui
├── db/           # drizzle schema + migrations
└── lib/          # server logic
```

## Workflow

- IMPORTANT: never commit directly to `main`; branch as `feat/…` / `fix/…`
- Don't commit or push unless asked

## Gotchas

- `.env.local` isn't committed — copy `.env.example`
- The billing webhook test needs `STRIPE_WEBHOOK_SECRET` set; it's skipped otherwise

## References

- Architecture decisions: @docs/architecture.md

CLAUDE.md best practices

• Keep it under 200 lines. It loads into context every session, and bloated files make Claude ignore the rules that matter. For each line, ask: would removing this cause Claude to make mistakes?
• Be specific enough to verify. "Use 2-space indentation" beats "format code properly"; "run npm test before committing" beats "test your changes"; "API handlers live in src/api/handlers/" beats "keep files organized".
• Use headings and bullets. Claude scans structure the way a reader does; grouped bullets are easier to follow than dense paragraphs.
• Emphasize sparingly. If Claude keeps skipping one instruction, add IMPORTANT to that line alone. Emphasize many lines and none of them stands out.
• Remove contradictions. Review the root file, nested files, and .claude/rules/ together; conflicting rules get resolved arbitrarily.
• Treat it like code. Commit it so the team can contribute, review it when Claude misbehaves, and prune it regularly. If Claude asks questions the file already answers, the phrasing is ambiguous.
• Start with /init. It analyzes your codebase and writes a starter file (or suggests improvements to an existing one). Refine it with what Claude couldn't discover on its own.

CLAUDE.md imports: the @path syntax

A CLAUDE.md can pull in other files with @path/to/file — for example see @README.md for the overview or a bullet like - git workflow: @docs/git-instructions.md. The rules, per the docs:

• Relative paths resolve from the file that contains the import, not the working directory; absolute and ~/ paths work too.
• Imported files can import others, up to four hops deep.
• Imports inside code spans and fenced code blocks are ignored, so wrapping a path in backticks keeps it literal.
• The first time a project imports a file outside the repo, Claude Code asks you to approve it.
• Imports help organization but don't save context — imported files load at launch with the file that references them. To load instructions only when relevant, use path-scoped rules or skills.
• A neat use: @~/.claude/my-project-instructions.md in a project file shares personal notes across git worktrees, where a gitignored CLAUDE.local.md would only exist in one.

Claude Code auto memory vs CLAUDE.md

Claude Code has a second, complementary kind of persistent memory. Auto memory is written by Claude itself as it works — your preferences, corrections you give it, project context it can't derive from the code — and stored per repository in ~/.claude/projects/<project>/memory/. A MEMORY.md index there loads each session (its first 200 lines or 25KB), and topic files are read on demand.

• CLAUDE.md: you write it, it holds instructions and rules, and it can be shared with your team through git.
• Auto memory: Claude writes it, it holds learnings and patterns, and it stays on your machine (shared across worktrees of the same repo).
• Asking Claude to "remember" something saves it to auto memory; to put it in CLAUDE.md, say "add this to CLAUDE.md" or edit the file via /memory.
• Auto memory is on by default. Toggle it in /memory, per project with autoMemoryEnabled, or with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

CLAUDE.md vs AGENTS.md

AGENTS.md is the shared instruction file many coding agents read. Current Claude Code (v2.1.277 and later) reads it too — but by default only when your project has no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above. When both exist, Claude reads the CLAUDE.md files only, unless you set project instructions in /config to read both.

The portable setup the docs recommend: keep the shared rules in AGENTS.md and add a tiny CLAUDE.md that imports it, with Claude-specific notes below the import. This generator can save either file — pick AGENTS.md as the format, and it shows the two-line bridge file to copy.

# CLAUDE.md
@AGENTS.md

## Claude Code

- Use plan mode for changes under src/billing/

A symlink (ln -s AGENTS.md CLAUDE.md) also works if you don't need Claude-specific content, but git checks symlinks out as plain text files on Windows unless symlinks are enabled — prefer the import if anyone on the team uses Windows. Claude doesn't read AGENTS.local.md, AGENTS.override.md, or anything under .agents/.

CLAUDE.md examples, including the Karpathy CLAUDE.md

Plenty of developers publish their CLAUDE.md files on GitHub, and reading a few is a good way to calibrate. The most famous is the "Karpathy CLAUDE.md" — a short community file by developer Forrest Chang, distilled from Andrej Karpathy's public observations on how LLM coding agents fail. Karpathy didn't write it himself, and it's behavioral guidance (simplicity first, surgical changes, goal-driven execution) rather than facts about a project.

That distinction matters when you copy one. General behavior rules fit your user-level ~/.claude/CLAUDE.md, where they apply everywhere; the project file should stay about this repo — its commands, its conventions, its gotchas. A borrowed rule set never replaces the single-test command only your project has.

Common CLAUDE.md mistakes

• The novel. Hundreds of lines of architecture essays. The rule that matters gets lost, and the docs' /doctor check will propose cutting what Claude can derive from the code.
• The platitudes. "Write good code", "follow best practices", "be careful". Claude already tries; say what good means here.
• The directory dump. A full tree listing. Claude can explore the tree itself — name only the dirs that aren't obvious.
• Everything is IMPORTANT. When every rule shouts, none stands out.
• Conflicting rules. "Use npm" in one place, pnpm install in another. Claude picks one arbitrarily.
• Secrets in the file. CLAUDE.md is plain text and usually committed. Reference env var names, never values.
• Relying on it for guarantees. Instructions shape behavior; hooks and permissions enforce it.

Frequently asked questions