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
@pathreference, 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
/initgenerates a starting file by studying the project, and/context alllists 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:
| Scope | Location | Who it applies to | Business use |
|---|---|---|---|
| Organization (managed policy) | A system folder set by IT | Everyone in the organization | Company-wide security and compliance rules |
| User | ~/.claude/CLAUDE.md | You, in every project | Your preferences, such as tone and shortcuts |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Everyone working on the project, through version control | Rules for this system: tests, structure, approvals |
| Local | ./CLAUDE.local.md | You, in this project only | Your 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:
| Mechanism | What it is | Use it when |
|---|---|---|
| Path-scoped rules | Markdown files in .claude/rules/ that load only for matching files | A rule matters for one part of the project only |
| Skills | A SKILL.md in .claude/skills/<name>/; Its short description is normally in context; the full text loads when the skill is used | You have a multi-step procedure, such as a publishing checklist |
| Subagents | A Markdown file in .claude/agents/ with its own context window, system prompt, tool access and permissions | A side task would flood the main conversation, or needs tighter tool limits |
| Hooks | Shell commands that run automatically at set points, such as before or after an edit | Something must always happen, or an action must be blocked |
| MCP servers | Connections to outside tools and data through an open standard | The 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-auditto 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
- Run
/initin the project so Claude drafts a starting file from what it finds. - Delete anything obvious. Keep what Claude could not work out alone: your rules, your approvals, your exceptions.
- Add a "Never" list of three to five lines for the mistakes that would cost you most.
- List the checks that must pass before work counts as done.
- Run
/context alland confirm the file loaded. - Give Claude a real task and note every correction you had to type. Add each correction as a rule.
- 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
→ Related Resources
- Claude Code for business: what it can automate
- AI agents for business: what they can automate
- AI automation for business: a plain-English guide
- How to automate business processes with AI
- AI automation use cases for companies
- AI automation service
- Workflow automation service
- API development service
- AI agents service
- Our work and case studies
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.
- https://code.claude.com/docs/en/memory: What CLAUDE.md is, where it lives, how it loads, the under 200 lines guidance, imports, rules, auto memory, and that it is context, not enforced configuration.
- https://code.claude.com/docs/en/overview: CLAUDE.md is read at the start of every session; skills package repeatable workflows; hooks run shell commands around Claude Code actions; the Agent SDK builds custom agents.
- https://code.claude.com/docs/en/skills: A skill is a SKILL.md file in .claude/skills/<name>/ (project) or ~/.claude/skills/<name>/ (personal); descriptions load always, full content loads when used.
- https://code.claude.com/docs/en/sub-agents: A subagent has its own context window, system prompt, tool access and permissions, and is a Markdown file in .claude/agents/.
- https://code.claude.com/docs/en/hooks-guide: Hooks run deterministically at set points; a PreToolUse hook can block an edit to a protected file such as .env.
- https://code.claude.com/docs/en/security: Permission modes, review responsibility and the limits of any protection.