Instructions and Rule System

CLAUDE.md files are markdown files that load into the model’s context at session start. They shape how the model responds in your project. In the first post of this series, I called them rules. I wrote:

Rules are markdown files that load into context automatically.

I traced that word back to Cursor, where the settings UI literally says “Rules” with the description “Use Rules to guide agent behavior, like enforcing best practices.” That’s where it stuck. Turns out Anthropic calls them something different.

Anthropic’s docs don’t call CLAUDE.md files “rules.”¹ They call them instructions — “instructions you write to give Claude persistent context.” In their terminology, “rules” refers to something specific: path-scoped files in .claude/rules/ that load based on glob patterns.² Instructions and rules are different mechanisms. I conflated them because they’re very alike.

But it wasn’t just Cursor. Claude Code’s own /insights command generates what it calls “CLAUDE.md additions” — ready-to-paste suggestions for your instruction file. The docs say “instructions.” The tool says “rules.” I’m to blame for not reading carefully, but it wasn’t a coincidence either.

I didn’t find this out by reading carefully. I found it by preparing this post, digging into the docs to fact-check my own claims, and realizing the terminology I’d been using was imprecise. This post is what I actually found.

↑ Contents

Instructions: How CLAUDE.md Files Work

When Claude Code starts a session in a directory, it looks for a CLAUDE.md file. If it finds one, it reads the entire file and adds its contents to the context.³ Exactly as if you’d pasted them at the start of your conversation.

That’s the whole mechanism. There’s no parsing, no enforcement layer, no check against what the model does next. The file gets read. The tokens get consumed. The response the model produces next is conditioned on that content.⁴

Instructions are a special kind of prompt — the part of the prompt that’s always there. Loaded automatically, before you type anything. Every session, in every project that has a CLAUDE.md.

The way I see it, instructions, memory, and skills are all different ways of sectioning a very large prompt.⁵ The context window is the unit. Instructions occupy a chunk of it at session start.

This explains both why instructions work and why they’re unreliable. The model produces tokens based on probability distributions conditioned on everything in context. A convention that appears three times: in an instruction, in a code comment, in your prompt. That occupies more of the distribution than one that appears once. Repetition isn’t redundancy — it’s how you increase the odds that the model follows a convention when there’s no enforcement layer backing it up.

↑ Contents

Three Scopes, All Loaded Into Context

Claude Code doesn’t read a single CLAUDE.md. It walks up the directory tree from your working directory, loading every CLAUDE.md it finds along the way.⁶ Your user-level file loads too. If your organization deploys a managed policy file, that loads as well.

Three scopes, from most specific to broadest:⁶

Project — CLAUDE.md at the root of your repository. Team conventions, architecture decisions, patterns specific to this codebase. This is what most people interact with.

User — ~/.claude/CLAUDE.md. Your personal preferences, loaded for every session regardless of project. Commit message format, working style, general conventions.

Managed policy — deployed by IT at a system-level path (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS).⁶ Organization-wide standards that individual users can’t disable. Most people won’t have one of these, but if your company uses Claude Code at scale, it’s how they enforce compliance.

More specific scopes take precedence over broader ones.⁶

There’s also a fourth loading behavior: a CLAUDE.md inside a subdirectory loads on demand, not at session start.³ Claude picks it up when it reads files in that directory. Useful when part of a codebase has different conventions from the rest.

The practical implication: every CLAUDE.md in the chain costs tokens. In my experience, instructions have already consumed tens of thousands of tokens before you’ve typed a single message. Run /context to see for yourself. That budget matters. It’s context that can’t be used for your actual work.

↑ Contents

Rules: Why Instructions Weren’t Enough

Instructions don’t scale. As your CLAUDE.md grows, every instruction loads every session: API conventions, test patterns, security requirements, all of it consuming tokens even when you’re just editing a README. Anthropic’s docs are explicit about this: “For larger projects, you can break instructions into topic-specific files using project rules. Rules let you scope instructions to specific file types or subdirectories.”²

That’s why .claude/rules/ exists as a separate mechanism. Rules are modular markdown files that can be scoped to specific file paths using glob patterns in YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Rules without a paths: field load at session start, just like CLAUDE.md instructions. Path-scoped rules load on demand when the model reads matching files.² The distinction matters for context budget. Path-scoped rules don’t consume tokens until they’re relevant.

Under the hood, instructions and rules end up in the same place: the context window. The model doesn’t treat them differently. The difference is organizational:

	Instructions (CLAUDE.md)	Rules (.claude/rules/)
Location	CLAUDE.md files in directory hierarchy	.claude/rules/*.md files
Scoping	By directory position (project, user, subdirectory)	By file glob patterns (paths: frontmatter)
Loading	Ancestor files at launch, subdirectory on demand	Without paths: at launch, with paths: on demand when matching files are read
Format	Plain markdown, no frontmatter required	Markdown with optional YAML frontmatter for path scoping
Enforcement	None	None
Where they end up	Context window	Context window

Instructions are broad and always-on. Rules are modular and can be conditional.

↑ Contents

Instructions Encode What Code Can’t Say

The mechanism is genuinely useful for a specific job: encoding what the codebase can’t say for itself.

Your code might be readable, but it can’t tell the model that your team agreed to never use nested ternaries, or that this service is mid-migration and the old pattern is intentionally being phased out, or that every commit message needs a specific prefix. Instructions fill that gap.

↑ Contents

The Best Instructions Come After Incidents

In my experience, the most useful instructions aren’t the ones written in advance. They’re the ones written right after something went wrong.

A browser debugging tool crashed on me mid-session once. The agent kept going without telling me the tool was gone, told me it couldn’t fix MCP connections without even checking what happened, then just stopped. I wrote three instructions before doing anything else:

• announce when tools drop,
• investigate before giving up,
• propose recovery instead of reporting failure.

Those instructions have been active in every session since. When the model produces something you didn’t want, you write it down immediately. That failure becomes an instruction. The instruction loads next session. The behavior is softened — not eliminated, but less likely.

The ones I wrote in advance? Most of them were too vague to matter.

↑ Contents

What Instructions Don’t Do

Instructions don’t enforce anything.⁴

The model can ignore them. It does, sometimes. Not because of a flaw in the model. It operates on probability, not obligation. An instruction saying “always annotate public functions with schema types” shifts the probability of that behavior. It doesn’t guarantee it.

In a workshop I ran recently, someone asked: “If a project intentionally breaks from the standard architecture, won’t the instructions fight against it?” Yes. They fire for every session. They have no awareness of the project’s history or which conventions are intentional deviations. There’s nothing in the instruction system to handle that distinction.

If you want enforcement, you need a different tool entirely. A linter in CI catches violations before they merge. A pre-commit hook stops the wrong pattern from being committed. These tools operate directly on the code. They block the action, no probability involved.

Instructions and enforcement are complementary. Instructions guide the model during generation. Linters catch what it missed after generation.

↑ Contents

Working With Instructions Effectively

Once you see the mechanism, a few things follow.

Keep them concise. Every character in a CLAUDE.md loads at session start. Long instructions with full rationale sections consume context you might need later. In my experience, one concrete example outperforms a paragraph of explanation.

Use path-scoped rules for conditional context. If an instruction only applies to a specific part of the codebase, put it in .claude/rules/ with a paths: glob instead of the project CLAUDE.md. It saves tokens on sessions where those files aren’t relevant.

Use the scopes intentionally. Don’t duplicate user-level instructions in every project. Put universal preferences in ~/.claude/CLAUDE.md and let project files cover only what’s specific to that codebase.

Monitor your context budget. Run /context periodically. If instructions are consuming most of the window before you’ve asked anything, the files have grown too large.

Build mechanical enforcement for conventions that matter. For architecture boundaries, schema requirements, security patterns — use a linter. Instructions help. They don’t hold.

Write instructions after incidents, not before. The most accurate instructions come from running the system and noticing what goes wrong, not from anticipating failures upfront.

Instructions and rules are good primitives. Once you stop expecting enforcement from them, you can use them for what they actually do well: shaping defaults, encoding what the code can’t say, and building up context that makes the model more useful over time.

But if you need something to actually hold the line — to block an action, not just suggest against it. That’s a different mechanism entirely. That’s hooks. Next in the series.

↑ Contents

Footnotes

1. How Claude remembers your project — “CLAUDE.md files: instructions you write to give Claude persistent context.” The page never uses the word “rules” for CLAUDE.md files. ↩

2. How Claude remembers your project — “Organize rules with .claude/rules/” — path-scoped instructions with glob patterns in paths: frontmatter. ↩ ↩² ↩³

3. How Claude remembers your project — “CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in subdirectories load on demand when Claude reads files in those subdirectories.” ↩ ↩²

4. How Claude remembers your project — “Claude treats them as context, not enforced configuration” and “CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.” ↩ ↩²

5. Best Practices for Claude Code — “Claude’s context window holds your entire conversation, including every message, every file Claude reads, and every command output.” Everything shares one window. ↩

6. How Claude remembers your project — “More specific locations take precedence over broader ones.” Scopes: managed policy, project instructions, user instructions. ↩ ↩² ↩³ ↩⁴