The CLAUDE.md File: What Goes In, What the Docs Say, and What Broke in 29 of Ours

What is a CLAUDE.md file, and where does it load from?

Claude Code's memory documentation, read on 26 September 2026, defines it as “markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization”, read “at the start of every session”. The docs' test for what belongs in it is short: “Treat CLAUDE.md as the place you write down what you'd otherwise re-explain.” Four locations, in the order they load:

Two mechanics matter more than they look. Files are “concatenated into context rather than overriding each other”, so a rule in a parent folder and a contradicting rule in the project both reach Claude, and the docs warn that “if two rules contradict each other, Claude may pick one arbitrarily”. And an @path line imports another file at launch, which is how one AGENTS.md can serve Claude Code and Cursor at once; our Cursor rules guide compares the two systems side by side.

What should go in, and how long should it be?

The docs give a number and a reason: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” The cost page repeats it from the billing side, “Aim to keep CLAUDE.md under 200 lines by including only essentials”, and says where the rest goes: skills, which “load on-demand only when invoked”. Anthropic's post on the file (25 November 2025) adds the one exclusion everyone needs: “Don't include sensitive information, API keys, credentials, database connection strings, or detailed security vulnerability information”.

The best practices page turns the number into a test you can apply line by line: “For each line, ask: ‘Would removing this cause Claude to make mistakes?’ If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!” Its include column is bash commands Claude cannot guess, style rules that differ from defaults, test runners, repository etiquette, project architectural decisions, environment quirks and gotchas; its exclude column starts with “Anything Claude can figure out by reading code” and ends with “File-by-file descriptions of the codebase”. For a checked-in file, /doctor “proposes cuts for content it can derive from the codebase”.

The last two rows come from outside the docs and matter most. Evaluating AGENTS.md (Gloaguen et al., ETH Zurich, revised June 2026) tested context files across coding agents and models and found they “do not generally improve task success rates, while increasing inference cost by over 20% on average”; instructions “are well followed”, overviews are not helpful, and the files “are useful for specifying non-standard coding practices”. Write the rules Claude cannot infer. Skip the tour.

What do 29 CLAUDE.md files look like after a year?

The studio behind this site runs every venture and every agency client from one workspace, with a CLAUDE.md per folder and the portfolio root file loading above all of them. We counted every file on 26 September 2026: 29 files, 4 over the 200-line guidance, 3 that are a single @AGENTS.md import, and no .claude/rules/ directory anywhere, which is the finding.

The shape is the lesson. Files grow by accretion: every correction gets a line, the line never leaves, and a 414-line file is what a year of “Claude makes the same mistake a second time” looks like when nothing is ever moved out. The docs' relocation rule, procedures to skills and folder rules to path-scoped rules, is the maintenance step we skipped. Our commands guide counts the 25 skills that did get extracted.

What does this site's own CLAUDE.md contain?

Fifty-one lines, of which the ones that do work are the hard rules. Abridged, with the sections that only describe the folder left out:

# Lovable Prompts (lovable-prompts.com)

ProtoBites venture. Prompt library + AI prompt generator for Lovable builders. Marco is sole founder.

## Folder layout
- product/ - the Next.js app (source of truth)
- legacy/ - clone of the original Lovable-built SPA. Reference only. Never edit; never deploy.

## Hard rules
- Every link that sends a person to Lovable uses the affiliate link. In code, import
  lovableAffiliateUrl() from product/src/lib/affiliate.ts; never paste the URL.
- URLs are frozen. Do not add, rename, or restructure URL paths without Marco.
- Pricing: one product only. Never restate the price, a count or a quota in a copy
  string; import from src/data/bundle.ts and src/lib/planLimits.ts.
- Global voice rules apply: no em dashes, no AI-sounding verbs, no unsourced numbers.

Every rule in it is the docs' kind of rule: “concrete enough to verify”. And each one has a verifier outside the file, because the file is advice: the URL rule has a script that fails the build on any drift from the frozen list, the pricing rule is enforced by importing constants so a literal price cannot compile, and the voice rule is a grep that runs before every push. The Lovable SEO guide shows what the URL and sitemap rules protected.

What broke, and what fixed it?

1. The memory index outgrew its budget. Claude Code's auto memory keeps a one-line index that loads every session. Ours reached 31,234 bytes against a 24,400-byte limit, so the session warned that 20 lines were cut off, and the 398 memory files behind them were partly unreachable. Fix: one line per memory, under 200 characters, detail in the topic file. The same law applies to CLAUDE.md.
2. Stale facts in the root file. The portfolio CLAUDE.md still named a sale deadline four months past and a framing a shared repository had superseded. Claude followed it, because instructions “are well followed”. Fix, so far: the section that supersedes the old framing says so in the file, in those words. The periodic review the docs prescribe, to “remove outdated or conflicting instructions”, is the part we still owe, and the stale deadline is still there as this is written.
3. Rules that Claude could not see. Skills symlinked in from a shared repository were invisible until the session restarted, so six sat unreachable for weeks while the CLAUDE.md that referenced them assumed they were there. Fix: the file now says a new skill needs a symlink and a restart, in those words.
4. A rule with no gate. The banned-word rule lived in CLAUDE.md and was checked with a grep whose word-boundary syntax the shell silently ignored, so twelve banned words shipped in one day while the rule was in context the whole time. Fix: the check moved to a script with a known-good grep, and the rule in the file now names the script.

Sources

All checked on 26 September 2026. The file inventory is in src/data/claudeMdInventory.ts; this site's own CLAUDE.md is in the repository root.

• Claude Code docs: How Claude remembers your project
• Claude Code docs: Manage costs effectively
• Claude Code docs: Best practices for Claude Code
• Claude blog: Using CLAUDE.md files (25 November 2025)
• Gloaguen et al., Evaluating AGENTS.md (arXiv 2602.11988)