CLAUDE.md Best Practices: Generate a Lean Memory File From Repo Facts

What CLAUDE.md Best Practices Actually Come Down To

A CLAUDE.md file is a markdown file at the root of a repo that Claude Code reads at the start of every session. It holds the standing context an agent needs: the real build and test commands, the folders that matter, the code style, and the hard boundaries. Applying CLAUDE.md best practices is mostly about two things: keeping it lean, and keeping it true to the repo.

The official Claude Code memory docs lay out the format and tell you to run /init to scaffold a starter file. That's a good start. What the docs don't hand you is a prompt that produces a filled, contract-locked file from your actual repo facts, then keeps it tight on purpose. You still curate it by hand.

That's the gap this post closes. The reference teaches the shape. The work is producing the artifact.

Why Most CLAUDE.md Files Are Too Long and Half-Wrong

The first version is usually decent. Someone writes the commands, lists a few boundaries, commits it. Then entropy wins. The file grows, the repo moves, and the two stop matching.

Three failure modes show up again and again. Files bloat into a 400-line essay the agent skims instead of acting on. They drift, holding a build command that got renamed two sprints ago. And they go vague, because "follow the existing conventions" is faster to type than the conventions themselves. The docs are blunt about the cost: CLAUDE.md loads into context every session, and files over 200 lines "consume more context and reduce adherence." Long isn't thorough here. Long is worse.

A CLAUDE.md That Earns Its Place in Context

A good file is short and checkable. It says pnpm test runs the suite, the API lives in src/api, and the agent never edits anything under generated/. Concrete. Boring, in the right way. Here's the section contract a generator should fill:

• Commands. The exact install, build, test, and lint commands, pulled from package.json scripts or the Makefile. Not npm test when the project runs pnpm vitest run.
• Structure. A short map of the folders that carry meaning, one line each.
• Style. The conventions reviewers actually enforce: formatter, import order, naming. Skip the ones a linter already catches.
• Boundaries. Always / Ask-first / Never. What the agent does freely, what needs a human nod, what's off-limits.
• Testing. When tests are required, how to run a single test, what "green" means before a change counts as done.
• Setup gotchas. The env var nobody remembers, the service that has to be running first. This is the line hand-written files miss most, because it lives in someone's head.

That's six tight sections. Not forty. Each one earns its place because Claude acts on it: the Commands block gets run, the Boundaries get respected, the Structure map saves a search. A section the agent never uses is a section that's costing tokens for nothing.

How to Generate a CLAUDE.md From Your Repo, Step by Step

1. Gather the repo facts

Open package.json, the CI config, and the README. Pull the real commands. Note the directories an agent touches and the ones it shouldn't. Write down the boundaries you'd tell a new hire on day one.

2. Fill the variables

A generator prompt takes those facts as input. The core variable is {{repo_facts}}, the raw dump of commands, folders, style notes, and boundaries. A second variable, {{stack}}, names the language and framework so the output matches your ecosystem.

3. Run it against a locked section contract

The prompt's job is to map your raw facts into those six fixed sections and refuse to pad. No personality instructions, no "be a senior engineer." Just the facts Claude needs in every session.

4. Trim and commit

Read the output. Cut anything Claude could figure out on its own. Commit, and treat the file as living documentation that gets re-derived when the repo changes, not a write-once artifact.

One Opinion: Stop Putting Personality in CLAUDE.md

Here's a stance worth defending. The single most common waste in a CLAUDE.md is behavioral fluff: "act like a senior engineer," "think step by step," "be thorough." None of it prevents a specific mistake, and all of it costs context every turn. The docs make the same point quietly — "personality instructions do not prevent specific mistakes."

Replace every line of personality with a checkable fact. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes." If you can't verify whether Claude followed a line, that line is probably noise. And no, restating "be careful" three times doesn't make the model more careful.

Variables You'll Set

Getting Started

1. Collect your real commands from package.json and CI.
2. List the meaningful folders and the off-limits ones.
3. Write the boundaries in plain language.
4. Feed {{repo_facts}} and {{stack}} to a generator prompt with a fixed section contract.
5. Trim the output under 200 lines and commit it.
6. Re-run the generator whenever the build or structure changes.

For a packaged version of this, the AGENTS.md Generator for Polyglot Monorepos works the same way for CLAUDE.md: it emits a filled, contract-locked file from {{repo_facts}} and {{stack}}, and since Claude Code can import @AGENTS.md, one generated file feeds both tools. If you also want the agent to manage what context loads when, the Context Engineering Harness pairs with it.

The section contract in practice

The reason a contract-locked output beats free-form generation: the model can't quietly drop the Testing section because your {{repo_facts}} didn't mention tests. A locked contract forces it to write "Testing: no test command found — add one" instead of skipping the gap. That visible hole is more useful than a confident omission. Claude honors a fixed ## Section skeleton more reliably than an inline "include testing info if relevant" instruction, so the skeleton belongs in the prompt, not in your hopes.

A CLAUDE.md is the cheapest reliability win in an agent setup, and the most neglected. Keep it short, keep it true, regenerate it when the repo moves. For the sibling config every other tool reads, see how to write an AGENTS.md file with AI, and for the rules layer in Cursor, how to write .cursorrules that actually work.