1. Home
  2. Blog
  3. Technical Founders
  4. CLAUDE.md best practices: tell the agent who your users are
Technical Founders

CLAUDE.md best practices: tell the agent who your users are

Claude reads your code. It can't read your users. What belongs in CLAUDE.md beyond code style, and what belongs in a per-feature brief instead.

CLAUDE.md best practices: tell the agent who your users are
On this page
  1. Start from what the repo can’t tell Claude
  2. Name your users in two or three lines
  3. Say what the product won’t do
  4. Write down product rules and your users’ words
  5. Put the product block at the top
  6. Keep each feature’s context out of the file
  7. Test every line before it stays
  8. Update it when Claude repeats a mistake
  9. Doing this in MindBacklog
  10. Questions

The CLAUDE.md best practice most founders miss is product context: who your users are, what the product won’t do, and the rules you agreed with them. Claude Code reads your code style and folder layout from the repo, so those lines add little. Keep the file to what’s true on every task, and give each feature’s why, metric and must-haves their own brief.

In short
  • Write down only what Claude can’t learn from the code. Your users top that list.
  • Add who the users are, what’s out of scope, product rules and the words users use.
  • Leave out folder layout, linter rules and anything true for only one feature.
  • Keep each feature’s why, metric and must-haves in a per-feature brief.

Start from what the repo can’t tell Claude

Claude Code loads CLAUDE.md at the start of every session, and Anthropic’s memory docs suggest keeping each file under 200 lines. Every line competes for attention on every task. So start with a filter before you reach for a template.

Anthropic’s best practices give that filter as two questions: “Could it find this by reading the code?” and “Would it actually go and look?” If both answers are yes, the line goes.

Run that filter on a typical file and most of it disappears: the framework, the folder tree, the naming style. What survives is knowledge that never made it into the repo. For a founder, the biggest piece of that is the person the product is for.

Name your users in two or three lines

Without a user, Claude designs for a default one. The default user wants settings, options and an admin screen for everything. Your real users usually want one job done with less effort, on a device you know, in a situation you’ve watched.

For example, a founder building a booking tool for solo physiotherapists might rewrite the top of the file like this.

Instead of

This is a Next.js app for booking appointments, using Postgres and Tailwind.

Try

Users are physiotherapists who run a clinic alone. They book and move sessions on a phone between patients. Their patients are mostly over 50 and get reminders by text.

Those three lines change small decisions all over the codebase. Claude sizes tap targets for a phone, keeps forms short, and writes reminder copy an older patient can follow. You never had to ask for any of it.

Say what the product won’t do

Coding agents say yes to plausible scope. Ask for a booking change and you may get a waitlist, a group class option and a calendar sync nobody requested. An out-of-scope list gives Claude a reason to stop.

Keep the list to things Claude might reasonably build. “No blockchain” wastes a line. “No group classes, every booking is one patient and one clinician” prevents real work you’d later delete.

Write down product rules and your users’ words

Some decisions live in support threads and calls, not in code. Others are in the code but easy to break. Both belong in the file, phrased so Claude can act on them.

Kind of lineExampleWhy Claude can’t infer it
Product ruleNever cancel a session automatically. The clinician confirms every cancellation.Users asked for it on calls, and the code allows both
Privacy rulePatients never see another patient’s name, even on a waitlist.Nothing in the schema says so
Users’ wordsUsers say “session”, never “appointment”. Copy follows them.The database table is called appointments
Done meansRun pnpm test and pnpm lint, then show the output.The repo has three test scripts and one is stale

The vocabulary line matters more than it looks. Agents copy names from the code into the interface, so without it your users start seeing “appointment” on buttons and in emails.

Note. Claude treats CLAUDE.md as context rather than enforced configuration, so it follows the file nearly every time. For a rule that can have no exceptions, such as never reading the production env file, Anthropic recommends a hook or a permission deny rule instead.

Put the product block at the top

Here is the whole product section for the physiotherapy example. It’s short on purpose. Commands and gotchas can follow it, and the file still fits on one screen.

# Users
Physiotherapists who run a clinic alone.
They manage bookings on a phone between patients.
Patients are mostly over 50. Reminders go by text.

# Out of scope
- Group classes. One patient, one clinician.
- Insurance billing and claims.

# Product rules
- Never cancel a session automatically.
- Patients never see another patient's name.
- Users say "session", not "appointment".

# Done means
pnpm test and pnpm lint pass. Show the output.

Keep each feature’s context out of the file

The tempting next step is to paste your current feature into CLAUDE.md. That text then rides along on every unrelated bug fix, and it goes stale the day the feature ships.

A feature needs its own brief: why it matters, who it’s for, the metric that should move, and the must-haves with acceptance criteria. MindBacklog calls this a Build Pack, and you can also write one by hand as a spec file. The Build Pack format guide lists each section. Point the session at the brief when you start the feature.

Don’t pull the brief in with an @ import. The docs note that imported files load in full alongside the CLAUDE.md that imports them, so an import saves no context. Name the file in your prompt instead.

WHAT GOES IN CLAUDE.MD
What most files hold
  • Folder layout Claude can read
  • Style rules a linter enforces
  • The framework and its version
  • One feature's full spec
What Claude can't see
  • Who your users are
  • What the product won't do
  • Rules agreed with users
  • The words your users use
  • How to prove work is done
Most CLAUDE.md files describe the code. The useful lines describe what the code can't show.

Test every line before it stays

Run each line through this list when you write the file, and again whenever you touch it.

  • Claude couldn’t learn it by reading the code
  • It’s true on every task, not only the current feature
  • It names something specific: a user, a command, a word, a folder
  • It doesn’t contradict another line or a nested CLAUDE.md
  • If it must never be broken, it’s a hook or deny rule instead
  • A new teammate would need it too

Update it when Claude repeats a mistake

The docs suggest adding to CLAUDE.md when Claude makes the same mistake a second time, or when you type a correction you already typed last session. That keeps the file grounded in real misses rather than guesses.

  1. Start from /init. It drafts a file from your codebase. Most of the work after that is deleting lines.
  2. Add the product block. Users, out of scope, product rules, words, and how to prove work is done.
  3. Move narrow rules out. A rule for one folder goes in .claude/rules/ with a paths filter, so it loads only there.
  4. Move personal habits out. Your own preferences go in CLAUDE.local.md, which you add to .gitignore.
  5. Check what loaded. Run /context in a session and look for the file under Memory files.

If you build with Claude Code or Cursor most days, see how MindBacklog works for builder founders.

See what goes in the per-feature brief. A sample Build Pack for a made-up product, with every section’s source.

See a sample Build Pack

Doing this in MindBacklog

MindBacklog keeps what your users said, ranks the problems they have, and hands your coding agent the why. For each feature, the Build Pack carries why it matters, who it’s for, the metric, and the must-haves with acceptance criteria, so CLAUDE.md can stay short. A Build Pack never carries a customer’s name, email, company, plan or revenue. How the Build Pack works.

Questions

What should a CLAUDE.md file include?

Include what Claude can’t learn from the code: who your users are, what’s out of scope, product rules, the words users use, and the commands that prove work is done. Gotchas belong too, such as a legacy folder new code shouldn’t copy. Leave out what the repo already shows.

How long should a CLAUDE.md file be?

Anthropic’s docs suggest keeping each CLAUDE.md file under 200 lines, because longer files use more context and Claude follows them less reliably. Most founders’ files can be far shorter. If yours keeps growing, move folder-specific rules into .claude/rules/ and feature detail into per-feature briefs.

Does Claude always follow CLAUDE.md?

No. Claude Code treats CLAUDE.md as context rather than enforced configuration, so it follows the file nearly every time. Short, specific lines get followed most reliably. For a rule with no exceptions, use a hook or a permission deny rule.

Aadarsh Bohara

Founder, MindBacklog

Building the product management tool I wish I had. Multiple startup exits. Writing about AI, product strategy, and what it takes to build things people want.

Build what people actually asked for.

Start with an idea, your first users or a live product. Mind drafts; you decide.

No site yet? Start from your idea.

  • 14 days free
  • No card needed
  • Viewers are free

Or look around a sample workspace first. No sign-up.