When a team adopts Claude Code, the first file to appear in the repository is usually a CLAUDE.md. It collects the code conventions, the test commands and, little by little, everything else: "don't touch the migrations", "don't push to main", "don't read the .env". A few weeks later the file is three hundred lines long and the team believes its rules are in place.
The Claude Code documentation itself says otherwise. The model treats CLAUDE.md as context, not enforced configuration. Rules that allow no exceptions belong somewhere else, and that is not an implementation detail: it is the difference between asking the agent for something and the client not letting it do the opposite.
The thesis of this piece is easy to state and less easy to apply: if a rule carries risk, it cannot depend on the agent remembering it. What guides goes in CLAUDE.md. What must be enforced goes in the permissions of .claude/settings.json and in hooks, which are deterministic. And that file is versioned in the repository and reviewed like code.
What the documentation says, in its own words
There is little to interpret. Four pages of the official documentation say it explicitly.
- On the memory page: Claude treats CLAUDE.md and auto memory "as context, not enforced configuration", and to block an action regardless of what the model decides it points to a
PreToolUsehook. Further down: "Settings rules are enforced by the client regardless of what Claude decides to do"; CLAUDE.md instructions shape Claude's behaviour "but are not a hard enforcement layer". - In the hooks guide: hooks give "deterministic control", so certain actions always happen rather than relying on the model to choose to run them.
- In the best practices: "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic". And a warning worth reading twice: bloated CLAUDE.md files cause Claude to ignore your actual instructions.
- On the settings page: commit
.claude/settings.jsonso everyone who clones the repository gets the same permissions, hooks and plugins.
Four places for a rule, with four different guarantees
Claude Code offers several places to write a rule down. They are not interchangeable: they change who applies it and who can skip it.
| Where | What it is | Who applies it | What it is for |
|---|---|---|---|
| CLAUDE.md (project, user or organisation) | Text the model reads at the start of every session | The model, if it follows it | Commands, conventions, architecture decisions, whatever the agent cannot infer from the code |
Permissions in .claude/settings.json | Rules on which tools and commands are allowed, asked about or denied | The Claude Code client | What the agent can do in this repository, the same for the whole team |
| Hooks (in the same settings file) | Shell commands that run at fixed points, for example before a tool is used | The client, every time the event fires | Blocking a specific action, formatting after each edit, logging what happens |
| Managed settings | Settings deployed by the organisation | The client, above every other level | Security and compliance policy that no repository should be able to relax |
onext's own analysis, based on the memory, settings and hooks pages of the Claude Code documentation (accessed on 8 October 2026)
The example the hooks guide itself uses to get started says a lot: a script that runs before every edit, checks the file path against a list of protected patterns (.env, package-lock.json, .git/) and exits with code 2 on a match. With that code, Claude Code blocks the edit before it happens and passes the reason to the model so it can adjust its approach. Nobody has to trust the agent to remember the list: it cannot edit those files even if it tries.
What goes where: the question that decides it
The practical way to sort rules is to ask a single question about each one: if the agent fails to follow it once, what happens? If the answer is "the code comes out a bit worse", it is context. If the answer is "something breaks, something leaks or someone has to explain themselves", it is a condition.
| Rule | If the agent does not follow it | Where it goes |
|---|---|---|
| "We use ES modules, not CommonJS" | A change that gets fixed in review | CLAUDE.md |
"Run the tests with npm test before calling anything done" | Unverified work reaches review | CLAUDE.md, plus a Stop hook if the team wants it to be mandatory |
"Don't read or edit the .env" | Credentials exposed in a session or in a change | Denied permission and a PreToolUse hook |
"Don't push to main" | A deployment nobody has approved | Denied permission, on top of branch protection on the server |
| "Don't touch the generated files" | Changes that get lost on the next generation | PreToolUse hook on those paths |
| A security policy that applies to the whole company | A repository or a person relaxes it without anyone deciding to | Managed settings |
onext's own analysis. The split is a proposed criterion, not a rule from the documentation; the examples in the first and third rows come from the best practices and the hooks guide
The fourth row hides a trap: a permission in the client does not replace branch protection on the server. The agent is not the only one who can push. The rules that protect production have to live where production lives, and the agent's configuration is one more layer, not the only one. It is the same logic we set out for agents with tools in prompt injection and tool permissions: what limits the damage is what the agent can do, not what it has been asked.
The shared file can be overridden too
Versioning .claude/settings.json comes with a nuance worth knowing. The documentation orders the configuration levels, from highest to lowest precedence: managed settings, command line, the project's .claude/settings.local.json, the shared .claude/settings.json and user settings. A key set at a higher level overrides the same key set lower down.
In other words: each person can adjust for themselves what the team has versioned, with their local file, which Claude Code keeps out of git. For personal preferences, that is what you want. For a security rule, it is not enough.
Risk What must hold across the whole company, with no exceptions per person or per repository, goes in managed settings. The documentation puts it this way: settings for technical enforcement and a managed CLAUDE.md for guidance, such as code standards or compliance reminders. It also notes that some rules in the shared file, such as allow rules, only apply once each person trusts the folder; deny and ask rules apply right away.
A short CLAUDE.md is followed better
Moving the enforcing rules out has a side effect: CLAUDE.md slims down, and that is a gain too. The documentation suggests under 200 lines per file, because longer files consume more context and reduce adherence. The best-practices guide gives a test for each line: if removing it would not cause Claude to make mistakes, cut it. If Claude keeps doing something despite a rule against it, the file is probably too long and the rule is getting lost.
What only applies to part of the codebase can go into path-scoped rules under .claude/rules/, which load when the agent works with those files. And what is only needed sometimes, into a skill, which loads when it is needed. How to curate that shared text so it stays useful is covered in shared, curated team instructions, and when it pays to turn a procedure into a skill, in the practical guide to skills.
The agent's configuration is code
If permissions and hooks decide what the agent can do in a repository, changing them changes how the system behaves. They deserve the same treatment as code: a pull request, someone who reviews it and a written reason. A new hook that blocks something, or a permission that gets relaxed, is exactly the kind of change nobody should find by surprise.
It is the same idea we argue for prompts and skills in evals on every pull request: whatever changes an agent's behaviour goes through the same gate as the rest of the code. And it is the same underlying question as in the specification is where you sign off: where a person decides and what gets written down.
If your CLAUDE.md has been growing for months, the useful reading is not "we need to write it better". It is a different one: how many of those lines are really conditions that nobody checks. The product changes that also affect how Claude Code is configured in a team are reviewed in the six technical changes of 15 June.
Frequently asked questions
Does Claude Code always follow what CLAUDE.md says?
It is not guaranteed. The Claude Code documentation says the model treats CLAUDE.md as context, not enforced configuration, and that the more specific and concise the instructions, the more consistently it follows them. To block an action regardless of what the model decides, it points to a PreToolUse hook.
What is the difference between CLAUDE.md and .claude/settings.json?
CLAUDE.md is text the model reads at the start of every session and that shapes its behaviour. .claude/settings.json is configuration applied by the Claude Code client itself: permissions, hooks, plugins and environment variables. The documentation sums it up: settings rules are enforced by the client regardless of what Claude decides; CLAUDE.md instructions shape its behaviour but are not a hard enforcement layer.
What is a hook in Claude Code?
It is a shell command that Claude Code runs at a fixed point in its lifecycle, for example before using a tool (PreToolUse) or after editing a file. The documentation describes it as deterministic control: certain actions always happen rather than relying on the model to choose them. A PreToolUse hook that exits with code 2 blocks the action and returns the reason to Claude.
Should .claude/settings.json be committed to the repository?
Yes, if it is the team's configuration. The documentation recommends committing .claude/settings.json so everyone who clones the repository gets the same permissions, hooks and plugins. Personal exceptions go in .claude/settings.local.json, which stays out of git.
How long should a CLAUDE.md be?
The documentation suggests under 200 lines per file: longer files consume more context and reduce adherence. The best-practices guide adds a test for each line: if removing it would not cause Claude to make mistakes, cut it. What only applies to part of the codebase can go into path-scoped rules under .claude/rules/.
How do you enforce a rule across the whole company rather than one repository?
With managed settings, which the organisation deploys and which sit above every other level in the precedence order. The documentation separates settings, for technical enforcement, from a managed CLAUDE.md, for behavioural guidance such as code standards or compliance reminders.
Sources
- Claude Code Docs, "How Claude remembers your project" (accessed on 8 October 2026).
- Claude Code Docs, "Settings files and precedence" (accessed on 8 October 2026).
- Claude Code Docs, "Automate actions with hooks" (accessed on 8 October 2026).
- Claude Code Docs, "Best practices for Claude Code" (accessed on 8 October 2026).
Bernat López is founder and CEO of onext, an AI boutique. He helps development and product teams work with AI with method —specification before building, a person who decides where there is risk and Spec-Driven Development— and applies to his own company what he proposes: onext runs on its own agentic system.
LinkedIn →