CLAUDE.md is the instruction file that tells Claude Code how to behave in your project. This page is what I would tell you after measuring it rather than guessing.
This page used to say that files over 100 lines cause Claude to miss important rules, and that the longer the file, the more likely instructions are ignored. I measured it in August 2026 and could not reproduce that, so I have removed it.
39 trials on Claude Code 2.1.246. One task, one forbidden command, and a hook present in every condition that only records — so that the “zero attempts” rows have an instrument in the room.
| Condition | Trials | Attempted the forbidden command |
|---|---|---|
| No prohibition written anywhere | 17 | 17 / 17 |
| Prohibition in a 5-line CLAUDE.md | 4 | 0 / 4 |
| Prohibition buried in a 128-line file, section 10 of 20 | 3 | 0 / 3 |
| Prohibition near the bottom, section 18 of 20 | 3 | 0 / 3 |
| Same, plus other sections telling it to do the opposite | 6 | 0 / 6 |
Length did not dilute the rule. Position did not. Neither did contradicting it elsewhere in the same file with the same command named. The same shape held when the forbidden move was an irreversible one (rm on a directory) instead of a text edit.
Read the limits before you rely on this. Three to four trials per condition, one prohibition at a time, one version, short single-task runs. 0 / 22 is a rate observed in 22 attempts, not a law — do not read it as cannot happen. Long sessions where early context fades, and files carrying dozens of prohibitions that contradict each other, are exactly what I have not tested. Full method and all five parts.
Keep CLAUDE.md under 50 lines, and move detailed instructions to .claude/skills/ files, which load on demand.
The reason is money, not obedience. CLAUDE.md is read on every turn — not once per session. A 500-line file costs roughly 15× what a 35-line one does across a month of daily use, and you pay it on every single message whether or not the rule was relevant. That is a measurable, boring cost, and it is a better argument for brevity than a compliance claim I could not reproduce.
| Use Case | Lines | Safety | Focus |
|---|---|---|---|
| Beginner | 14 | ★★ | Basic safety rules |
| Autonomous | 24 | ★★★★ | Long-running, unattended |
| Team | 26 | ★★★ | Shared repo conventions |
| Production | 22 | ★★★★★ | Zero-tolerance safety |
| Learning | 14 | ★ | Explanations, minimal constraints |
# Project Rules
## Safety
- Never use rm -rf, git reset --hard, or git push --force
- Never commit .env files or API keys
- Always create a new branch before making changes
- Run tests before committing
## Code Style
- Follow existing code conventions
- Keep functions under 50 lines# Autonomous Operation Rules
## Critical Safety
- NEVER delete files without explicit backup first
- NEVER push to main/master directly
- Stop and report if the same error occurs 3 times in a row
## Work Pattern
- Create a git branch for each task
- Commit after each meaningful change
- Run tests after every code change
## Context Management
- Save work state before context compaction
- Keep TODO items in tasks/todo.md100+ line CLAUDE.md: costs tokens on every turn, for every message, whether or not the rule was relevant. Split into CLAUDE.md (principles) + Skills (procedures, loaded on demand). Note: I used to write here that Claude struggles with long instruction files. In 39 trials I could not reproduce that — see the measurement above. The cost is the reason to split; the struggling is not established.
Contradictory rules: "Write tests for everything" + "Move fast" without priority. State which wins — it costs one line and removes the guesswork. Worth knowing what I measured, though: when I put two sections saying "apply the change in one pass with sed -i" against one section saying "never edit files with sed", the prohibition won 3 times out of 3. A direct contradiction did not break the rule in that test.
Code snippets in CLAUDE.md: Wastes tokens on every turn. Put code in Skills files instead.
CLAUDE.md tells Claude the rules. Hooks enforce them at the process level.
# CLAUDE.md says "never rm -rf"
# This hook BLOCKS it:
npx github:yurukusa/cc-safe-setup --install-example destructive-guardAuto-generate CLAUDE.md from your project:
npx github:yurukusa/cc-safe-setup --scan --apply
Detects your tech stack and creates appropriate rules + hooks
Learn more: Production Guide · All Tools