CLAUDE.md File Best Practices From a File That Grew From 58 to 223 Lines

A CLAUDE.md file is the instructions file Claude Code reads at the start of every session. The short version of what works for us:

• Put in what the folder is for, a map of where things go, and the “always” and “never” rules you’d otherwise repeat in chat.
• Leave out step-by-step procedures (those are skills or commands), lists of your tools, anything that changes weekly, and secrets.
• Location: one at the root of the project folder, one in each department folder, and your personal preferences in ~/.claude/CLAUDE.md.
• Size: Anthropic’s docs say to target under 200 lines per file. Ours is 223, and the extra lines cost us.
• When to add a line: the second time Claude makes the same mistake.

Everything below is the evidence. Our whole company runs out of one git repository (the company brain), and its root CLAUDE.md has been edited 79 times since March. Most of the people who use it aren’t developers (how that works for them), so the file has to do the explaining a senior teammate would otherwise do.

Where the files live, and when Claude reads them

As of October 11 the repo has 20 CLAUDE.md files. One sits at the root. Each of the 13 top-level folders (sales, finance, marketing, operations, client work and so on) has its own, and 6 more sit in subfolders. They range from 3 lines to 239.

The 3-line ones are my favorite. Our dashboard’s file says “Read README.md for what this dashboard is” and then imports one more file with @AGENTS.md. That’s the whole file. Pointing at a README beats copying it, because the copy goes stale.

According to Anthropic’s memory docs, Claude Code loads every CLAUDE.md from your working folder and the folders above it when the session starts. Files in subfolders load later, once Claude reads, writes or edits a file in that subfolder. So when someone opens Claude Code at the root and asks about an invoice, the root file is loaded from the first message, and the finance file joins the moment Claude touches anything in finance/.

That’s why most of ours are split by department, not by client. A finance rule like how invoices get named applies to every client, so it belongs in finance/, not in each client’s folder. Our root file still says “Each workspace has its own CLAUDE.md. Read it before working in that workspace.” Claude Code loads that file by itself the first time it touches the folder, so the line mostly repeats what the tool already does. It’s harmless, so it stays.

78 lines, then 31, then 223

The root file was created on March 5 at 12:53 with 78 lines. Five hours later we cut it to 31. The commit message says we removed the technical defaults and a lifecycle diagram and “applied progressive disclosure”: the department files would carry the details. By March 8 it was back to 58.

Then it grew, and almost every jump traces back to a commit that explains why. Six of them:

“There is no root pyproject.toml.” Added March 29 in a commit titled “prevent Notion script execution failures.” Each tool has its own Python environment, so a script run from the wrong folder can’t find its dependencies. The rule tells Claude to cd first.

“Do not guess parameter names.” Added April 22, for the Google Workspace command-line tool we use for Gmail, Drive and Calendar. The rule says to check the command’s schema before building one, and the same commit added a reference guide of tested examples.

“Temp files go in scratch/.” Same day. The rule names the offenders: screenshots, exports and working files in the repo root. The same commit added scratch/ to .gitignore.

“Never create a per-workspace plans/ subdir.” Added May 2, right after we consolidated plan folders that had grown separately inside finance, the website and project management. Each one had looked reasonable on its own. Together they meant nobody knew where to look for a plan.

The rule about paid model APIs. On May 30 we added rule 13: work inside a Claude Code session does its reasoning in the session, never through a metered API. On September 28 we rewrote it. Paid APIs are now allowed when they do the job better, but every call site has to fail open, stay advisory at human gates, prove itself against our own past decisions first and report its cost. The rewrite references a ruling ID from our decision log, because the log holds the reasoning and the CLAUDE.md only holds the rule.

“Never tell the user to run gws auth login through !, the callback port dies with it.” Added August 26. Our Google login expires daily, and running the login command through Claude Code’s ! shell prefix kills the port the login needs to call back to. Now a script handles the whole re-login, and the rule points Claude at it.

What I’d cut from ours

Seventy of our 223 lines are an inventory: a tree of every command folder, skill and hook in .claude/, with a comment on each. That section is the reason for most of our maintenance. Of the 79 commits that touched the root file between March 5 and October 11, 11 exist only to fix places where the file had drifted from the folders it describes (“sync CLAUDE.md skills tree with actual directory,” “fix claim drift,” “refresh stale .claude/ inventory claims”).

Claude Code already knows which skills and commands exist. Their descriptions load at startup. Writing the inventory into CLAUDE.md as well means keeping two lists in sync by hand, and we lose that race about once every three weeks. If I deleted that section, the file would be well under Anthropic’s 200-line target.

Since March we’ve shrunk it on purpose once. On May 26 the meeting transcript instructions moved into their own guide and the root file kept a two-line pointer. That’s the move I’d repeat.

CLAUDE.md vs skills vs commands

Anthropic’s docs draw the line cleanly: a CLAUDE.md holds facts Claude needs in every session, and “if an entry is a multi-step procedure or only matters for one part of the codebase,” it belongs in a skill or a path-scoped rule. A skill’s body only loads when it’s used, so a long procedure costs almost nothing until someone runs it. Custom commands have been merged into skills, so a file in .claude/commands/ and one in .claude/skills/ both give you a /command.

The clearest example from our repo is our end-of-day process. By late May the command behind it was 919 lines long (we’ve since split it into smaller pieces). Put that in CLAUDE.md and every session, including someone renaming a file, would pay for it. As a command, it loads when a founder types /strategy:day-end-process and not otherwise.

One more limit: a CLAUDE.md is context. Anthropic’s docs say so directly, and point you to a hook when something must never happen. We learned that in June, when an audit showed our folder rules were being ignored often enough to matter. Now a hook checks every file Claude writes against the folder layout (the full story). The CLAUDE.md explains the rule, and the hook enforces it.

A template to start from

If you’re starting today, start small. This is a generic starting point, not a copy of ours:

# [Company or project name]

[One sentence: what this folder is for and who uses it.]

## Where things go
- clients/[client-name]/   notes, emails and transcripts per client
- finance/                 invoices and receipts, named YYYY-MM-DD_vendor
- drafts/                  anything not ready to send
- scratch/                 throwaway files, never committed

## Always
- Read the README in a folder before changing files in it.
- Name new files with the date first: YYYY-MM-DD_topic.md
- Ask before sending anything to a client.

## Never
- Never edit files in references/. They are the original sources.
- Never put passwords or API keys in a document.

## More detail
- How we write client updates: guides/client-updates.md

That’s under 25 lines. Run it for a week and keep a note of every correction you type twice. Those corrections are your next lines. When a section starts reading like a checklist with steps, move it into a command. When one folder needs its own rules, give that folder its own CLAUDE.md (more on setting up a team).

Writing yours on your own folder

The fastest way to get a good CLAUDE.md is to write it against a real folder and watch where Claude gets confused. That’s what a 45-minute coaching session ($99) is for: bring a folder of your actual documents, you do the typing over screen share, and you leave with your first CLAUDE.md and a recap of what we changed and why.