How to Use CLAUDE.md: What It Is and Why It Is Powerful

`CLAUDE.md` is a special markdown file that gives Claude Code persistent instructions across sessions. If you want Claude to follow your project conventions, remember your build and test workflow, or respect non-obvious architecture rules without re-explaining them every time, `CLAUDE.md` is one of the most effective tools in the Claude Code workflow.

That power comes from a simple idea: instead of re-prompting the assistant in every session, you move repeatable guidance into a file Claude reads automatically. In practice, that means less prompt repetition and more consistent output.

For businesses experimenting with AI-assisted operations, this matters beyond engineering teams. A PR agency like PRESS.com.my can use the same idea to standardize editorial workflows, campaign brief structures, media-response playbooks, and AI-assisted content production.

What is CLAUDE.md?

`CLAUDE.md` is a markdown file that Claude Code reads to pick up persistent instructions for a project, user, or organization.

According to Anthropic’s Claude Code documentation, `CLAUDE.md` is designed for things like:

• coding standards
• common workflows
• architectural decisions
• build and test commands
• naming conventions
• repository etiquette
• environment quirks and non-obvious gotchas

In other words, `CLAUDE.md` is your long-lived instruction layer. You write the rules once, and Claude can reuse them every session.

Is CLAUDE.md a skill?

This is the first thing many people get mixed up on: `CLAUDE.md` is not a skill file in the same sense as `SKILL.md`.

Anthropic’s current docs make a clear distinction:

• `CLAUDE.md` is loaded every session and is best for broad, persistent instructions.
• Skills are loaded on demand and are better for specialized workflows that should not bloat every conversation.

That means if you are asking “how to use the `CLAUDE.md` skill,” the more accurate wording is:

• `CLAUDE.md` is the persistent instruction and memory guidance layer
• `SKILL.md` is the skill packaging layer

Both are useful, but they solve different problems. `CLAUDE.md` tells Claude how your project works all the time, while skills handle specialized tasks only when needed.

How CLAUDE.md works in Claude Code

Anthropic says Claude Code reads `CLAUDE.md` files at the start of a session by walking up the directory tree from the current working directory. That means Claude can combine instructions from multiple levels instead of relying on only one file.

Here is the simplified loading model:

Anthropic also documents several behaviors that make the system especially practical:

1. `/init` can generate a starter file. Claude analyzes your codebase and proposes build commands, test instructions, and conventions.
2. `@imports` are supported. A `CLAUDE.md` file can pull in other files using `@path/to/file`, with recursive imports up to 5 hops.
3. Subdirectory instructions can load on demand. Claude can discover nested `CLAUDE.md` files when it works inside those subdirectories.
4. `/memory` helps inspect what is loaded. The `/memory` command shows active `CLAUDE.md`, `CLAUDE.local.md`, and rules files in the session.

This design is powerful because it balances persistence with structure.

Why CLAUDE.md is powerful

`CLAUDE.md` is powerful because it makes Claude more project-aware and less dependent on repeated prompting.

1. It removes repetitive prompting

Without `CLAUDE.md`, you repeat the same instructions over and over:

• use pnpm, not npm
• run this targeted test before finishing
• keep API handlers in this folder
• avoid changing generated files

`CLAUDE.md` reduces that friction by turning recurring instructions into reusable context.

2. It captures what code alone does not explain

A codebase may show structure, but it does not always explain intent. Claude cannot always infer:

• which command your team actually trusts
• which subsystem is fragile
• what naming choice is mandatory for downstream tooling
• which tests are slow, flaky, or not worth running for routine edits

These are exactly the kinds of details that belong in `CLAUDE.md`.

3. It improves consistency across sessions and teammates

Anthropic explicitly recommends checking shared project `CLAUDE.md` into git. That turns tribal knowledge into team knowledge and helps multiple Claude sessions behave more consistently.

4. It works with other Claude Code features

It becomes more useful when paired with:

• `/init` for generating a starting structure
• `/memory` for checking which instruction files are active
• `.claude/rules/` for modular, path-specific rules
• skills for specialized workflows that should load only when needed

5. It helps protect context quality

Anthropic warns that Claude’s context window fills up fast and that overly large instruction files can reduce adherence. Because `CLAUDE.md` is always loaded, it forces you to decide what belongs in persistent context and what should stay in an on-demand skill or linked document.

How to use CLAUDE.md step by step

Step 1: Create the file

For most teams, the best place is the project root:

• `./CLAUDE.md`
• or `./.claude/CLAUDE.md`

If you are starting from scratch, Anthropic recommends using `/init` to generate a first version automatically.

Step 2: Add only high-value persistent instructions

Start with the things Claude cannot reliably infer from the repository alone:

• exact build command
• exact test command
• code style rules that differ from defaults
• architecture constraints
• deployment or review workflow expectations

Step 3: Use markdown structure

Anthropic recommends using headers and bullets because Claude scans structured instructions more reliably than dense blocks of text.

A simple template could look like this:

“`md

Build and Test

• Install dependencies with `pnpm install`
• Run focused tests with `pnpm test –filter `

Code Style

• Use TypeScript strict mode patterns already present in `src/`
• Prefer named exports unless an existing file uses default export

Architecture

• API handlers live in `src/api/handlers/`
• Do not edit generated files under `src/generated/`

Workflow

• Run lint and relevant tests before finishing
• Keep changes scoped to the user’s request

“`

Step 4: Split large guidance with imports or rules

Anthropic recommends targeting under 200 lines per `CLAUDE.md`. If your file gets too large:

• move details into imported files with `@path`
• use `.claude/rules/` for topic or path-specific rules
• keep the main file focused on broad instructions

Step 5: Verify what Claude is actually loading

Use `/memory` to inspect the active memory and rule files in the current session. This is one of the easiest ways to debug “Claude is not following my instructions” problems.

Step 6: Refine based on repeated mistakes

If Claude keeps making the same avoidable mistake, either add the missing rule, make the rule more specific, or move the workflow into a skill or path-specific rule file.

What to put inside CLAUDE.md

Anthropic’s best-practices guidance is to put broad, durable instructions in `CLAUDE.md`, and avoid filling it with content Claude can easily infer or content that changes all the time.

Good candidates include:

• build commands Claude cannot guess
• testing instructions and preferred test runners
• branch, PR, and repo etiquette
• architectural decisions specific to the project
• required environment quirks
• common gotchas and non-obvious behaviors

Avoid using it for:

• long tutorials
• full API documentation
• file-by-file codebase tours
• rules that constantly change
• generic advice like “write clean code”

A good `CLAUDE.md` contains the instructions Claude would otherwise get wrong, forget, or waste time rediscovering.

Common mistakes to avoid

Mistake 1: Making it too long

Anthropic specifically says files over 200 lines consume more context and may reduce adherence.

Mistake 2: Writing vague rules

“Format code properly” is weak. “Use 2-space indentation” is strong.

Mistake 3: Mixing persistent rules with task-specific workflows

If a workflow matters only occasionally, it may belong in a skill rather than in `CLAUDE.md`. Anthropic explicitly points users toward skills for specialized tasks that should not load every session.

Mistake 4: Letting instructions conflict

If `CLAUDE.md`, nested files, and rules disagree with each other, Claude may choose one inconsistently. Review and prune regularly.

Mistake 5: Assuming it is hard enforcement

Anthropic notes that `CLAUDE.md` shapes Claude’s behavior but is not a hard enforcement layer. It is loaded as context, not as an absolute policy engine.

Conclusion

If you want the short answer, here it is: `CLAUDE.md` is powerful because it turns project knowledge into reusable AI operating context.

It is not a magic file, and it is not the same as a skill. But when you use it well, it gives Claude a stable understanding of your workflow, coding expectations, and project structure before the conversation even begins.

That is why `CLAUDE.md` matters. It helps Claude act less like a blank-slate chatbot and more like a collaborator that already knows how your team works.

If you want a broader look at AI tooling beyond Claude Code workflows, PRESS.com.my also has a simple explainer on What OpenClaw is, which fits naturally for readers comparing different AI work environments.

FAQ

Is `CLAUDE.md` the same as a Claude skill?

No. `CLAUDE.md` is the always-loaded instruction layer for a project or user context. Skills are modular, on-demand workflow packages intended for more specialized tasks.

How do I start using `CLAUDE.md`?

Create `./CLAUDE.md` or `./.claude/CLAUDE.md`, add concise rules that apply broadly, and use `/init` if you want Claude Code to generate a starter version.

What should not go into `CLAUDE.md`?

Do not use it for long documentation dumps, changing project notes, or task-specific workflows that are better handled by skills or rules files.