Skip to main content
Have a project in mind? Let's talk
Book a call Tell us about your project Book a Call
Insights & Guides

What Is a CLAUDE.md File? How Businesses Give AI Agents Their Rules

A CLAUDE.md file is where you write the rules an AI agent follows every session. Here is how it loads, what to put in it and why it is not a security lock.

A CLAUDE.md file is a plain markdown file of instructions that Claude Code reads at the start of every session, so the AI starts each job already knowing your rules. It is where a business writes down what it would otherwise repeat every time: how things are done here, what never to do, which checks to run and where files live.

Devvista is a software development and growth agency that uses CLAUDE.md files on its own website and writes them for client projects. This post explains how the file loads, what to put in it, the next layers (skills, subagents, hooks), an example from our own site, and what the file cannot do.

01 What a CLAUDE.md File Is and Why Claude Needs One

Anthropic explains the problem plainly: each Claude Code session begins with a fresh context window. Without something written down, you re-explain your standards every time.

CLAUDE.md is the fix. It is a markdown file you write in ordinary language, and Claude reads it at the start of every session. The documentation says to treat it as the place you write down what you would otherwise re-explain, and to add to it when Claude makes the same mistake a second time or when you type the same correction you typed last session.

A second mechanism, auto memory, holds notes Claude writes itself from your corrections. The two are complementary: you write CLAUDE.md, Claude writes the memory.

02 How Claude Code Loads the File

Loading follows a few rules worth knowing before you write anything:

  • Claude Code loads CLAUDE.md from your working directory and every directory above it. All the files are combined, not overridden, and the ones closest to where you started appear last.
  • Files in subdirectories load later, when Claude works with a file in that folder.
  • The file can import other files with an @path reference, up to four levels deep. Imports load with the file that names them, so they do not reduce its size cost.
  • Block-level HTML comments are removed before the content reaches Claude, so you can leave notes for human maintainers at no cost.
  • Typing /init generates a starting file by studying the project, and /context all lists the memory files that actually loaded.
  • If a repository already uses an AGENTS.md file for other tools, Claude Code can read that instead.

To check that your file is working, ask Claude to describe the rules it was given. If it cannot, the file is not loading, or it is too long to be followed.

03 Project, User and Organization Scope

Where the file lives decides who gets its rules:

ScopeLocationWho it applies toBusiness use
Organization (managed policy)A system folder set by ITEveryone in the organizationCompany-wide security and compliance rules
User~/.claude/CLAUDE.mdYou, in every projectYour preferences, such as tone and shortcuts
Project./CLAUDE.md or ./.claude/CLAUDE.mdEveryone working on the project, through version controlRules for this system: tests, structure, approvals
Local./CLAUDE.local.mdYou, in this project onlyYour own test URLs and notes; keep it out of git

Broader scopes load first and more specific ones later, so a project rule appears after a user rule. If two instructions contradict, the documentation warns that Claude may pick one arbitrarily, so review the files together now and then.

04 What a Business Should Put in It

The documentation keeps the advice practical: facts Claude should hold in every session, such as build commands, conventions, project layout and "always do X" rules. For a business that translates into five groups.

  • Company rules. Approval thresholds, who can authorise what, which data counts as sensitive.
  • Tone and wording. How customer messages should sound, words you never use, spelling by market.
  • What it must never do. Never send messages to customers, never touch the live database, never print secrets.
  • Checks to run. The tests and validations that must pass before a change counts as finished.
  • Where things live. The folders, exports and systems the work depends on.

Write each line so it can be checked. "Run python -m pytest before saying a change is done" works. "Test your changes" does not. Aim for under 200 lines, because longer files use more context and reduce how consistently the rules are followed.

05 A Sample CLAUDE.md for a Small Business Project

This example is invented for illustration. It is not a client file. It shows the shape: short sections, concrete lines, a clear "never" list.

# Acme Plumbing: working rules

## What this project is
- Internal tools for quotes, jobs and invoices. Not customer-facing.

## Always
- Run `python -m pytest` before saying a change is done.
- Write customer-facing text in plain, friendly English. No jargon.
- Quotes over 5,000 need a manager approval step.

## Never
- Never send an email or text to a customer. Draft it and stop.
- Never read or print values from .env.
- Never change the pricing table without asking.

## Where things live
- Pricing rules: `pricing/rules.py`
- Job export: `exports/jobs.csv` (refunds are negative rows)

The "Never" section is the most valuable part. It is where you put the mistakes you cannot afford. Keep it short and specific, and remember the limit covered below: a line in this file is a request, not a lock.

Want a CLAUDE.md written for your systems and checked against real tasks? Book a call and tell us the process; projects are quoted after a short call, and you state your budget in the form.

06 A Real Example: How Devvista Uses It on Its Own Website

This website's repository uses a CLAUDE.md file and skills, which we edit through our admin. We checked the project files while writing this post:

  • A project CLAUDE.md at the repository root, about 84 lines, holding the working rules: the business goal, the markets, how to research, what to check before handing work back, and the hard rules.
  • Skills in .claude/skills/, eleven folders, one per area of work: content, publishing and QA, brand, keyword research, backlinks and others. Each is a SKILL.md file.
  • An admin page in our local admin panel, "AI Agents", where the owner edits the CLAUDE.md and every skill without opening a code editor. Each save keeps the previous version, so a bad edit can be undone.

Two of the rules in the file show why it earns its place. One says never to invent clients, results or statistics. Another says every page must pass a set of automated checks before it is published. Those lines mean the person briefing the tool does not have to repeat them.

That is one project. We do not claim every business needs eleven skills. A small team might start with one CLAUDE.md of thirty lines.

07 The Next Layer: Rules, Skills, Subagents and Hooks

CLAUDE.md is where you start. When the file grows or a task needs more than a rule, the documentation points to other mechanisms. Here is how each is described:

MechanismWhat it isUse it when
Path-scoped rulesMarkdown files in .claude/rules/ that load only for matching filesA rule matters for one part of the project only
SkillsA SKILL.md in .claude/skills/<name>/; Its short description is normally in context; the full text loads when the skill is usedYou have a multi-step procedure, such as a publishing checklist
SubagentsA Markdown file in .claude/agents/ with its own context window, system prompt, tool access and permissionsA side task would flood the main conversation, or needs tighter tool limits
HooksShell commands that run automatically at set points, such as before or after an editSomething must always happen, or an action must be blocked
MCP serversConnections to outside tools and data through an open standardThe work needs your issue tracker, database or other system

The documentation draws a clear line: multi-step procedures and part-of-the-project rules belong outside CLAUDE.md. Keep the main file for what holds in every session. Our Claude Code guide for business covers how these tools fit a business job, and our post on AI agents shows where they fit in an automated process.

08 What a CLAUDE.md File Cannot Do

The most important sentence on Anthropic's memory page is this one: Claude treats these files as context, not enforced configuration. A rule is an instruction the model usually follows. It is not a lock.

  • It is not a security boundary. If an action must never happen, the documentation says to block it with a PreToolUse hook, which runs deterministically. A hook can stop an edit to a protected file such as .env.
  • It does not replace permissions. Manual mode, allow and deny rules, sandboxing and your own review decide what can actually run.
  • It should not hold secrets. Committed project files are shared with the team through version control. Put keys in environment variables or a secrets manager.
  • It can contradict itself. Two conflicting lines make behaviour unpredictable. Run /doctor prompt-audit to find outdated or conflicting instructions.
  • It does not guarantee correct work. Someone still reviews output before it reaches customers or live data.

09 How to Write and Maintain One: Steps for This Week

  1. Run /init in the project so Claude drafts a starting file from what it finds.
  2. Delete anything obvious. Keep what Claude could not work out alone: your rules, your approvals, your exceptions.
  3. Add a "Never" list of three to five lines for the mistakes that would cost you most.
  4. List the checks that must pass before work counts as done.
  5. Run /context all and confirm the file loaded.
  6. Give Claude a real task and note every correction you had to type. Add each correction as a rule.
  7. Review the file monthly. Remove what is outdated and merge duplicates. Keep it under about 200 lines.

If the same instruction keeps being ignored, make it shorter and more concrete, and if it truly must hold, enforce it with a hook rather than hoping.

10 When to Hire Help With Agent Setup

Writing a CLAUDE.md is within reach of any owner who can describe their own rules. Hire help when the setup touches real risk: skills that run deployments, hooks that guard live data, integrations to your CRM or billing system, or an agent that acts without a person watching each step.

We build that layer for clients as part of AI automation and AI agent projects: the rules file, the checks, the permissions and the review points, tested against your real tasks. Projects are quoted after a short call.

? Frequently Asked Questions

A CLAUDE.md file is a markdown file of persistent instructions that Claude Code reads at the start of every session. You write it in plain language to record project rules, standards, commands and conventions so you do not have to repeat them.

For a project, put it in the project root as CLAUDE.md or in a .claude folder as CLAUDE.md. A personal version for all your projects goes in your home .claude folder. A CLAUDE.local.md file holds private notes for one project and should be kept out of version control.

Anthropic suggests staying under about 200 lines per file. Longer files use more context and reduce how consistently the rules are followed. Move procedures into skills and part-of-the-project rules into path-scoped rules.

No. The documentation says Claude treats CLAUDE.md as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook, and keep permission settings and human review in place.

CLAUDE.md loads every session and holds facts and rules that always apply. A skill is a SKILL.md file for a specific procedure or workflow. Its short description is normally in context; the full text loads when the skill is used, either because Claude judges it relevant or because you call it.

A subagent is a specialised assistant defined in a Markdown file in a .claude/agents folder. Each runs in its own context window with its own system prompt, tool access and permissions, and it returns a summary to the main conversation.

Hooks are shell commands that run automatically at set points in the lifecycle, such as after a file edit or before a tool runs. They give deterministic control: the action always happens, rather than depending on the model choosing to do it.

You should not. Project files are shared through version control and loaded into the model context. Keep secrets in environment variables or a secrets manager, and add a rule that tells Claude never to print or read them.

Yes. Anthropic says each surface connects to the same underlying engine, so your repository CLAUDE.md files, settings and MCP servers work across them.

Yes. We write and test the rules file, skills and checks against your real tasks, set the permissions and review points, and hand over documentation. We quote the work after a short call, and you state your budget in the form.

→ Related Resources

Businesses in Canada, Pakistan or Saudi Arabia can start from their own pages: AI automation in Canada, AI WhatsApp automation in Pakistan and AI chatbots in Saudi Arabia.

→ Sources

Opened and checked on 2026-11-11. Product documentation changes often, so check the page itself before you rely on a detail.

SA
Written by
Samowal Faiz
Chief Executive Officer, Co-Founder, Devvista

Samowal Faiz is the Chief Executive Officer and co-founder of Devvista, a custom software agency that has delivered 195+ projects across healthcare, fintech, SaaS, and e-commerce. He leads strategy, client relationships, and business development with 7+ years of industry experience.

Devvista on LinkedIn
Ready to start?

Have a project in mind? Let's talk about it.

Book a discovery call with Devvista. We'll scope your project honestly, ask the right questions, and tell you what you need to hear, not what you want to hear.

  • 30-minute consultation
  • No commitment required
  • Response within 24 hours
  1. Book a call30 minutes, no pitch. Tell us what you want to build.
  2. Get a straight answerHonest feedback on fit, scope and timeline.
  3. Decide with no pressureMove ahead only if it feels right. No commitment required.
Chat on WhatsApp