Guarantees Instead of Hope
Knowledge
CLAUDE.md Is a Request -- Hooks Are a Promise
In previous modules, you learned how to steer Claude Code with CLAUDE.md and Skills. But there's a fundamental problem: CLAUDE.md is a request, not a command.
Claude reads your CLAUDE.md and tries to follow it. Most of the time, this works well. But when the context is full, when the task is complex, or when a subagent works with its own context -- Claude can forget or ignore rules. This isn't a bug but a fundamental characteristic of LLMs: They work probabilistically, not deterministically.
Hooks are the opposite. A Hook is a shell script, an HTTP call, or an LLM prompt that is guaranteed to execute at a specific point in the workflow -- regardless of what Claude is currently "thinking" or how full the context is.
!The Crucial Difference
CLAUDE.md: "Please format code with Prettier." -- Claude can forget.
Hook: PostToolUse on Write/Edit runs prettier --write. -- Runs ALWAYS.
The Analogy: Traffic Sign vs. Road Barrier
Imagine a one-way street:
- CLAUDE.md is the "Do Not Enter" traffic sign. Most drivers obey it. But someone who is distracted or doesn't see the sign will drive in anyway.
- A Hook is the physical road barrier. No matter how distracted you are -- you can't get through.
Both have their place: Traffic signs are sufficient for 95% of cases. But when a mistake would have catastrophic consequences -- for example, a git push --force to main -- you need a barrier.
What Hooks Can Do
Hooks intervene at 24 different events in the Claude Code lifecycle. From session creation to every tool call to context compaction -- you can enforce deterministic behavior everywhere.
There are 4 handler types that determine how a Hook responds:
| Handler | Description | Typical Use |
|---|---|---|
command | Execute shell script | Linting, tests, formatting |
http | HTTP POST to an endpoint | Logging, webhooks, CI/CD |
prompt | Single-turn LLM evaluation | Code review, validation |
agent | Multi-turn LLM with tools | Complex checks |
*When CLAUDE.md, When Hooks?
CLAUDE.md for style guidelines, conventions, knowledge -- everything where "usually correct" is enough. Hooks for hard rules: code quality, security, tests -- everything where "always" is necessary.
Understand
The combination of CLAUDE.md and Hooks is powerful: CLAUDE.md gives Claude the intention and context, Hooks enforce the non-negotiable rules. Together, a system emerges where Claude can work creatively but within firm guardrails.
It's like a soccer game: The coach's tactical instructions (CLAUDE.md) set the direction, but the sidelines (Hooks) ensure the ball stays in play -- without the referee having to intervene every time.
Apply
In the following sections, you'll learn about the individual Hook events, understand the four handler types in detail, and get ready-made practical recipes that you can directly adopt into your projects.
Ask yourself now: Which rules in your project are so important that "usually" isn't enough?