# Config files vs hooks: where agent enforcement actually belongs

> Source: <https://dev.to/piekwerk/config-files-vs-hooks-where-agent-enforcement-actually-belongs-2gi8>
> Published: 2026-09-22 06:01:16+00:00

A rule in CLAUDE.md is a request. A hook is a guarantee. Mixing these

two up is the most common config mistake I see: teams write "never

commit secrets" as prose, then act surprised when a secret gets

committed. This post is the split I use: what belongs in prose, what

belongs in a hook, and the four-level ladder that decides.

Prose config changes what the model tries to do. Hooks and CI change

what is possible to do. Anything that must never happen does not

belong in prose, because prose is sampled, not executed.

For any rule you want, ask which level it actually needs:

```
Level 1  Linter/types/CI      deterministic, catches most code issues
Level 2  Hooks (PreToolUse)   blocks the command/file before it runs
Level 3  Scoped rules         prose, loads only for matching files
Level 4  Always-on config     prose, worth spending context on every call
```

The ladder is ordered by reliability, and the reliable end is free of

tokens. Every rule you can push down a level saves context and removes

a failure mode.

Concrete examples from my own setup:

```
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "command": "block-dangerous.sh" },
      { "matcher": "Edit|Write", "command": "protect-env.sh" }
    ]
  }
}
```

`rm -rf` outside a target dir, force-push
to main, `drop table`. A regex in a PreToolUse hook blocks these
with certainty. In prose, "be careful with rm" works maybe nine
times out of ten, and you only hear about the tenth.`.env`, keys, generated files. The hook
returns a block reason and the agent adapts. No token spent until
the moment of the attempt.
The things hooks cannot decide, because they need judgment:

The clearest smell is any line in CLAUDE.md that starts with "always

run" or "never commit". If CI can check it, CI should check it.

Every prose duplicate of a linter rule is a line of context spent on

something the machine already guarantees, and a contradiction waiting

when the two drift.

Our kits keep prose for judgment and push everything checkable down

the ladder. That is also why the validator rejects placeholder

instruction files: prose that restates the linter is worse than no

file, because it trains you to stop reading your own config.

Older setups (plain .cursorrules, bare AGENTS.md) have no hook layer.

The ladder still applies, one rung lower: CI and linters carry the

hard guarantees, prose carries judgment, and the "hard guarantees in

prose" gap is covered by a pre-commit hook in git itself, which every

setup has.

*Our kits ship this split pre-built: prose for judgment, hooks and validator rules for guarantees, in [AgentConfig Studio](https://piekwerk.gumroad.com/l/agentconfig-studio). Try the approach on Next.js first: [free sample kit (MIT)](https://piekwerk.gumroad.com/l/free-sample-nextjs).*