CLAUDE.md is guidance, not a guarantee
Here’s the thing tool marketing avoids saying: rules you put in CLAUDE.md are delivered to the model as context, not as hard enforcement. The model reads them and usually follows them — but compliance is probabilistic, not guaranteed. Writing “never run destructive commands” in a markdown file is a strong suggestion, not a lock on the door.
That doesn’t make CLAUDE.md useless — it makes it one layer of three. Real guardrails come from stacking guidance with deterministic enforcement and human review. Miss the bottom two layers and you don’t have guardrails; you have hopes written down.
When Claude does something your CLAUDE.md “forbade,” it’s not malfunctioning. A soft instruction lost to a stronger, more immediate signal in the conversation. The fix isn’t a louder rule — it’s moving that rule to a layer that can’t be overridden.
The three layers of a real guardrail
| Layer | Where it lives | Strength | Use it for |
|---|---|---|---|
| Guidance | CLAUDE.md, project instructions | Probabilistic — the model usually complies | Conventions, style, architecture intent, “prefer X over Y” |
| Enforcement | Permissions, hooks, managed settings | Deterministic — the model cannot bypass it | Blocking dangerous commands, restricting paths, requiring checks before a tool runs |
| Governance | Version control, review, audit log | Human — changes are owned and traceable | Who can change the rules, what changed, and why |
The mistake almost everyone makes is trying to do all three jobs with layer one. If a rule genuinely must hold — secrets, destructive commands, protected files — it belongs in enforcement, not in prose the model is free to reweigh.
Move “must-hold” rules into enforcement
Claude Code supports settings that gate what a tool is even allowed to do — independent of what the model “decides.” A permission/hook layer turns a soft rule into a deterministic one. A minimal example that denies risky commands and requires a check runs before edits are accepted:
“Please don’t read secrets” in CLAUDE.md is guidance. Read(.env*) in the deny list is enforcement. Write the intent in CLAUDE.md so the model understands why; put the hard stop in settings so it can’t cross the line even if it wanted to.
For an organization, the same idea scales up: managed settings can define policies that individual developers can’t override, and every action can be logged for an audit trail. That’s the difference between a rule you hope is followed and a control you can prove was in place.
Governance: who owns the guardrails
A guardrail nobody owns decays. Governance is the third layer — the boring, essential part:
- Version it. CLAUDE.md and
.claude/settings.jsonbelong in git, reviewed like any other change. - Assign an owner. Use CODEOWNERS so changes to the guardrails get a required reviewer.
- Keep an audit trail. When a rule changes, the git history tells you who, what, and when — and route agent actions through logging where enforcement matters.
- Review on a cadence. Guardrails drift as the codebase changes, same as any config. Revisit them.
We cover the versioning side in depth in the CLAUDE.md version-control guide.
Guardrail mistakes to avoid
- Putting hard limits in prose. If it must hold, it goes in enforcement — not a paragraph.
- Assuming a bigger rule is a stronger rule. Making the sentence louder doesn’t change that it’s still just guidance.
- No audit trail. If you can’t say who changed a guardrail or when, you can’t govern it.
- Set-and-forget. Permissions and hooks need review as tools and workflows change.
Guardrails are three layers. Brainfile ships all three.
Most setups are one layer — a CLAUDE.md full of good intentions. That’s guidance the model can reweigh. The enforcement and governance layers are where safety actually lives, and they’re the parts a one-time generator skips.
Brainfile is a governed Claude Code operating system: 7 layers and 70+ components spanning guidance, deterministic enforcement, and versioned governance — maintained over time so your guardrails hold as your codebase and Claude Code change.
Free in-browser builder · Brainfile Pro maintains & governs it: 7 layers, 70+ components, $99/mo
Frequently Asked Questions
Why does Claude ignore rules in my CLAUDE.md?
Because those rules are delivered as context, so the model follows them probabilistically. A stronger, more immediate signal in the conversation can outweigh them. For rules that must hold, use enforcement (permissions/hooks), not prose.
What is the difference between CLAUDE.md and settings.json?
CLAUDE.md is guidance the model reads and usually follows. .claude/settings.json defines what tools are allowed to do at all — deny lists, permissions, and hooks — which the model cannot bypass. Use both: intent in CLAUDE.md, hard stops in settings.
How do I stop Claude Code from touching secrets or running destructive commands?
Put them in the permissions deny list in .claude/settings.json (for example, deny reading .env files or running rm -rf). That is deterministic enforcement, unlike a written request in CLAUDE.md.
How do teams govern Claude Code guardrails?
Version CLAUDE.md and settings in git, assign an owner via CODEOWNERS, keep the change history as an audit trail, and review on a cadence. Managed settings can enforce org-wide policies developers can’t override.
Generate a starter Brainfile free.
Then let it stay maintained.
The free Brainfile Builder walks you through a few questions and generates a starter CLAUDE.md-style setup right in your browser — copy it or download the .md file and drop it in your repo. No account needed to try it.
A starter file is a snapshot. Brainfile Pro ($99/mo, or $999/yr) keeps it alive — 7 layers and 70+ components, versioned and governed, and refreshed as Claude Code and your codebase change, so your context never quietly rots.
14-day free trial · 30-day money-back guarantee · Cancel anytime
Team setup? Reach out →