Auto-Generating a Claude.md File for Any Codebase

You dropped Claude Code into a repo and it wrote code that ignores your test runner, your import style, and the fact that you moved off REST months ago. The fix is not a longer prompt. It is a CLAUDE.md file at the root of the repo that tells the model how this specific codebase works before it touches a single line. This guide shows you how to generate one for any codebase, whether you hand-write it, run the built-in scaffold, or ask the model to draft it from the code itself.

The catch nobody mentions: a generated CLAUDE.md is only accurate the day you generate it. The moment you swap a library, rename a command, or change a convention, it starts lying to your AI. We will cover the generation step and the harder part, keeping it true.

Key takeaways

• A CLAUDE.md file is a plain-Markdown context file Claude Code reads on startup; it holds build commands, conventions, and architecture notes so the model stops guessing.
• The fastest way to generate one is the /init command inside Claude Code, which scans your repo and drafts a first pass you then edit down.
• You can also generate one by asking the model directly ("read this repo and write a CLAUDE.md") or by starting from a template and filling the gaps.
• Keep it short and specific. A 40-line file the model actually reads beats a 400-line file it treats as noise.
• Generation is a one-time act; accuracy is ongoing. Every CLAUDE.md decays as the code changes, and hand-maintaining it is the real cost.

---

What a Claude.md file actually is

CLAUDE.md is a Markdown file Claude Code looks for and loads into context automatically when it starts working in a directory. There is nothing magic about the format. It is prose and bullet points. The model reads it the way a new engineer would read an onboarding doc, then uses it to make decisions: which package manager to run, how you name things, what not to touch.

Claude Code checks a few locations and merges them:

• The repo root (./CLAUDE.md), committed and shared with your team.
• A personal, git-ignored CLAUDE.local.md for notes you do not want to commit.
• Parent directories up the tree, so a monorepo can have a root file plus per-package files.
• Your home directory (~/.claude/CLAUDE.md) for instructions that apply to every project.

The goal is not to document the whole codebase. It is to close the gap between what the model assumes and what is actually true here. Anything the model can figure out on its own does not need to be in the file. Anything it will get wrong does.

Three ways to generate a Claude.md file

There is no single right method. Pick based on how much the repo already tells you.

Option 1: run the built-in /init command

Inside Claude Code, type /init. It scans the repository, reads the package manifest, the existing docs, the directory layout, and any obvious conventions, then writes a draft CLAUDE.md to the root. This is the fastest start and the one most people should use first.

Treat the output as a draft, not a final file. The scan is good at surface facts (build tool, language, folder names) and weaker at intent (why you structure things a certain way, which paths are load-bearing). Read every line and cut anything generic. A line like "this is a JavaScript project" is wasted space; the model already knows.

Option 2: ask the model to write it from the code

If /init is not available or you want a tighter file, ask directly. Open the repo in your AI tool and give it a plain instruction:

Read this repository. Write a CLAUDE.md that a new contributor could use to run, test, and extend the project. Include the exact build/test/lint commands, the naming and import conventions you can infer, the top-level architecture in three sentences, and anything a newcomer would get wrong. Keep it under 50 lines. Do not include anything you are guessing about.

That last sentence matters. Without it, the model pads the file with plausible-sounding conventions it did not verify. With it, you get a shorter, truer draft that you extend by hand.

Option 3: start from a template and fill the gaps

If the codebase is new or thin, generation from code produces little. Start from a skeleton instead and fill it in as you go. A minimal template that covers the high-value slots:

# Project: <name>

## Commands

- Install: <exact command>
- Dev server: <exact command>
- Test: <exact command>
- Lint / format: <exact command>
- Build: <exact command>

## Architecture

<Three sentences: what the app is, the main layers, where the entry point lives.>

## Conventions

- <Naming, e.g. hooks in src/hooks, one component per file>
- <Import style, e.g. absolute imports from @/>
- <Anything the model keeps getting wrong>

## Do not touch

- <Generated files, vendored code, migration files, etc.>

## Gotchas

- <Non-obvious traps, e.g. "the auth token store breaks under multiple workers">

Each line earns its place by preventing a specific mistake. If you cannot name the mistake a line prevents, delete the line.

Which generation method to use

For most real repositories, run /init, then hand it to the model with "cut anything generic and anything you are not sure is true," then do a final human pass. That sequence gets you a usable file in a few minutes.

What to put in it (and what to leave out)

The difference between a CLAUDE.md that helps and one the model ignores is signal density. Every line the model has to read that does not change its behavior makes the useful lines harder to weigh.

Include:

• Exact commands, copy-pasteable. Not "run the tests" but the literal command, including the flag you always forget.
• Conventions the model will otherwise violate: naming, file layout, import style, error-handling patterns.
• A three-sentence architecture summary so the model knows where things live.
• Explicit "do not touch" zones: generated files, vendored code, anything with a footgun.
• Hard-won gotchas, the traps that cost you an afternoon once.

Leave out:

• Anything the model can infer from the code in seconds (the language, obvious folder names).
• Long API references that live better in the code or real docs.
• Aspirational rules nobody follows. If the codebase does not match the rule, the model will trust the code, not your file.
• Secrets, tokens, or internal URLs. This file usually gets committed.

A tight 40-line file the model reads every time beats a 400-line file it skims. When in doubt, cut.

The part generation does not solve: staleness

Here is the trap. You generate a clean CLAUDE.md, the AI gets sharper, and you move on. Three weeks later you switch from one test runner to another, rename a core module, and drop a dependency. The code moved. The file did not. Now your CLAUDE.md confidently tells Claude to run a command that no longer exists and to follow a convention you abandoned.

A stale context file is worse than no context file, because the model trusts it. It will follow your outdated instructions over the current reality of the code and produce work that looks careful and is wrong. This is the same failure mode that makes any static knowledge base rot: it captures a snapshot, and snapshots go out of date the moment the thing they describe changes.

The usual answer is discipline: update the file every time you change a command or a convention. In practice that never holds. Nobody edits a Markdown doc in the same commit that renames a build script, and the drift compounds until the file is quietly ignored.

The deeper version of this problem is not about one repo. Your AI works from context about you and your whole way of building: your stack preferences, the decisions you made and why, the tools you standardized on. That context lives across many projects and it changes constantly. Regenerating one file per repo does not keep any of it current. What keeps it current is a system that updates itself as you work, so the facts your AI reads are the facts as they are now, not as they were the day you last remembered to edit a doc. That is the idea behind giving your AI a memory that actually lasts: the record supersedes itself when a fact changes, and the old version is kept as history instead of silently misleading you.

Keeping a generated file honest

Until the whole thing maintains itself, a few habits keep a hand-managed CLAUDE.md closer to true:

• Edit it in the same commit that changes a command or convention. If the diff touches the build script, it should touch CLAUDE.md.
• Re-run /init every few months and diff the output against your current file to catch drift you missed.
• Keep it small. A shorter file is cheaper to keep accurate, and the model weighs it more heavily.
• Put volatile, personal context (your preferences, cross-project decisions) somewhere that updates on its own rather than hard-coding it into every repo's file. A living second brain your AI reads over MCP does this without you touching a doc, and the same durable facts can travel between projects as a Memory Pack instead of being copy-pasted into a dozen CLAUDE.md files.

The generated file is the floor, not the ceiling. It gets a new repo from "the AI guesses" to "the AI knows the basics." Keeping that knowledge current as the code and your preferences move is the work that actually pays off, and it is the part worth automating.

FAQ

How do I generate a CLAUDE.md file automatically?

The fastest path is the /init command inside Claude Code, which scans your repository and writes a first-draft CLAUDE.md to the root. You can also ask the model directly to read the repo and write one, or start from a template and fill it in. In every case, treat the generated output as a draft and edit it down; the scan tends to include generic facts the model already knows. See how to give your AI a memory that lasts for keeping that context current afterward.

Where does the CLAUDE.md file go?

At the root of your repository as CLAUDE.md, committed so your team shares it. Claude Code also reads a git-ignored CLAUDE.local.md for personal notes, parent-directory files in a monorepo, and a global ~/.claude/CLAUDE.md in your home directory that applies to every project. All matching files get merged into context.

What should a CLAUDE.md file contain?

Exact build, test, and lint commands; the conventions the model would otherwise violate (naming, imports, error handling); a three-sentence architecture summary; explicit "do not touch" zones; and any non-obvious gotchas. Leave out anything the model can infer from the code, long API references, and secrets. Density matters more than length.

How long should a CLAUDE.md file be?

Short enough that the model reads all of it. For most repos that is well under 100 lines, often around 40. A tight file the model weighs on every request beats a long one it skims. If a line does not change how the model behaves, cut it.

Why does my CLAUDE.md stop helping over time?

Because the code changed and the file did not. Once a command, dependency, or convention drifts from what the file says, the model follows your outdated instructions over the current code and produces confident, wrong work. Update the file in the same commit that changes the underlying fact, or move the volatile context into something that updates itself so it cannot go stale. Locul's approach to a self-updating brain supersedes old facts automatically.

Can I share one CLAUDE.md across many projects?

The root file is per-repo by design, but shared, cross-project context (your stack preferences, standard tooling, recurring decisions) is better kept in one place your AI reads everywhere rather than copied into each repo. Locul serves that context to your AI tools over MCP and can bundle it as a Memory Pack you install into your brain, so the same facts stay consistent across projects without manual copy-paste.

---

Generating a CLAUDE.md is a five-minute job. Keeping it, and the rest of the context your AI relies on, true as your code and preferences change is the part that never ends when you do it by hand. Locul builds a second brain from what you already produce and keeps it current so your AI works from your real, up-to-date context instead of a snapshot you last remembered to edit. It runs local-first on your machine and is free to start with 500 memories and local AI, no credit card. Generate the file, then let the context behind it maintain itself.