Build reliable AI systems
Your CLAUDE.md Is Not An Operating System
A markdown rule is a suggestion until something enforces it.
TL;DR
- CLAUDE.md is useful context, but it is not enforcement.
- If a rule must always happen, move it into a hook, gate, validator, wrapper, ledger, or review lane.
- Treat prose as guidance and enforced mechanisms as the actual operating layer.
01 / GuideA rule in prose is still a suggestion
CLAUDE.md is valuable. It tells the agent what matters, what the project is, how the repo works, and what habits the user wants. That is context. Context helps.
The mistake is pretending context is control. A model can miss instructions. It can compress them away. It can satisfy the local task while violating the larger operating rule. That is not malice. It is what happens when a policy lives only in prose.
I learned this the expensive way while building WarpOS, my agentic operating-system project. If a rule mattered enough to hurt when ignored, it eventually needed to move out of the instruction file and into the system.
02 / GuideHooks are where rules become real
A hook changes the conversation. The agent no longer has to remember the rule perfectly. The workflow checks the rule at the moment it matters.
That can mean scanning a path before edits. It can mean blocking a risky command. It can mean forcing a handoff note before a session ends. It can mean writing a ledger entry when a task claims to be done.
The point is not that every rule needs automation. The point is that important rules need a place to live outside the model's current attention.
03 / GuideThe operating layer is boring on purpose
The reliable parts of an agentic system look boring from the outside: trackers, ledgers, handoffs, review gates, blocked paths, and explicit status.
That is the point. A serious AI workflow should not depend on the model feeling inspired. It should make the correct next move easier and the dangerous move harder.
Use CLAUDE.md for context. Use skills for repeatable runbooks. Use MCPs for tools. Use subagents for isolated work. Use hooks and gates when a rule has to hold.
04 / Key takeawayConclusion
CLAUDE.md is a good starting point. It is not the operating system.
The operating system starts when the workflow can enforce the rules that matter, record what happened, and recover when a session forgets, drifts, or claims too much.
Vladislav Zhirnov
Quick answersCommon questions
Is CLAUDE.md still worth using?
Yes. CLAUDE.md is useful for project context, conventions, and preferences. It should not be the only place for rules that must be enforced.
What is the difference between a skill and a hook?
A skill is a repeatable runbook the agent can use. A hook is an enforcement point in the workflow. Use skills to teach a process and hooks to make critical checks happen.
What should move out of prose first?
Move rules that protect data, prevent destructive edits, require evidence, or force handoffs. If ignoring the rule creates real cost, it should not depend only on model memory.
Choose your next move