CLAUDE.md, hooks, skills or the task: where each rule for Claude Code belongs

Claude Code gives you four places to put a rule, and they differ in when they load, what they cost and whether they are enforced. How I decide, with the rules in my own setup that moved from one place to another.

When a Claude Code session does something I never want to see again, I write a rule. For a long time I wrote all of them into CLAUDE.md. That was the wrong default for about half of them.

Claude Code gives you four places to put a rule: the CLAUDE.md file (or AGENTS.md), a hook, a skill, or the task itself. They load at different times, cost different amounts, and only one of them can actually stop something from happening.

What each one is

CLAUDE.md is read at the start of every session and stays in the context for every step. The Claude Code docs are plain about its limits: Claude treats it "as context, not enforced configuration". My global one is about 1,100 words.

A hook is a script that Claude Code runs on an event: before a tool call, after one, when a session starts or stops. A hook that runs before a tool call can refuse it. It costs nothing in the context until it says something. The same docs page says: to block an action "regardless of what Claude decides, use a PreToolUse hook".

A skill is a folder with a SKILL.md file. Only its short description is in the context. The body loads when the skill is used: "a skill's body loads only when it's used, so long reference material costs almost nothing until you need it" (skills docs).

The task is the brief a session starts with. In my setup every session gets a written brief for one job, plus a short card of rules for that kind of job.

The four questions

For each new rule I ask these, in this order:

  1. Can a script tell right from wrong? Then it is a hook.
  2. Is it about this one job? Then it goes in the brief.
  3. Is it a long procedure that is only needed sometimes? Then it is a skill.
  4. Is it judgement that applies to every job? Only then CLAUDE.md.

The order matters. CLAUDE.md is the easiest place to write a rule, so it fills up first. It is also the only place that costs context on every step and enforces nothing.

Rules that are hooks in my setup

These run before every shell command, and some before every file read:

  • No push to main. This one blocks. A session commits on a branch and opens a pull request. CLAUDE.md says so too, but the hook is what makes it true.
  • Secrets. A guard refuses a command that would print a key file or the whole environment.
  • Heavy local work. A guard refuses a heavy build or test run on my own machine. Once, a single check step filled 15 GB of swap and the system closed a whole group of windows.
  • Context budget. After each tool call, a hook checks how long the conversation has become. Past 200,000 tokens it tells the session to finish its step and hand over.

Most of them start in warn mode, as these two did. They say what they would have blocked, and I read those lines for a week before I switch them to block. Why I do that, and how to test a hook without Claude Code, is in Claude Code hooks: run each one in warn mode for a week first.

When a written rule was not enough

The clearest sign that a rule belongs somewhere else: it is in CLAUDE.md, and it is broken anyway.

  • Waiting for a check. I had written rules about how to wait for a test run. Sessions still wrote their own wait loops. One used pgrep -f, which matched its own command line and never ended: three hours. Another waited for a run to show up in a status list, but finished runs drop off that list: five hours. The fix was not a better sentence. It was a ci wait command that reads the run's result line and exits. Now the rule just says to use it.
  • Secrets. The secrets guard already existed when, on 29 October, a session printed a private key anyway. It had searched a server's whole environment with one wide grep, a command shape nobody had written down. Now the rule names that exact shape, and the guard looks for it.

A rule in text tells a session what you want. A hook or a tool makes the wrong way harder than the right one. When a rule keeps breaking, move it down the list.

Skills, and what their list costs

Skills are a good fit for procedures I need sometimes, like my design workflow or a written plan for a large change. The body stays out of the context until the skill is used.

The list itself is not free, though. When I measured what a fresh session had loaded before reading its task, the descriptions of all available skills came to about 11,000 tokens. Working sessions on my machine now start with the skill list turned off. Only the kinds of job that need skills, such as design work, start with them on. The full measurement is in What Claude Code really costs.

The task: rules for one kind of job

Most of my rules are about one kind of job: a release, a design, a research task. They used to sit in CLAUDE.md, where every session paid for all of them. Now each kind of job has a short card of rules that comes with its brief, and CLAUDE.md keeps only the rules that hold for every job.

The card wins when the two disagree. That way a release job can have a release-specific exception without CLAUDE.md growing a paragraph of "except when".

CLAUDE.md or AGENTS.md

If you also use other coding agents, you may already have an AGENTS.md. According to the docs, Claude Code (version 2.1.277 or later) reads it as your project instructions by default when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If there is a CLAUDE.md, it reads that instead. If you want one file for all tools, keep AGENTS.md and import it from CLAUDE.md with a line @AGENTS.md. Your personal ~/.claude/CLAUDE.md loads either way.

The choice of file name does not change anything above. Either file is context, not enforcement.

What I would do in your place

  • Before you add a line to CLAUDE.md, ask the four questions.
  • Keep a date and a reason next to each rule. It tells you later which rules failed and should move to a hook. More on that in My CLAUDE.md, and the failure behind each rule.
  • When a written rule is broken twice, stop rewording it. Write a hook or a small command that makes the right way the easy way.

More posts

All posts →
  1. 21 Nov 2026

    Same agent, rebuilt workspace, a quarter of the bill: what EnvOpt showsA new arXiv paper leaves the model and the harness alone and lets another AI rebuild the workspace the agent works in. On 200 test tasks, the same Claude Haiku 4.5 agent cost $42.36 before and $11.55 after, and passed more tasks.

    AI · 7 min
  2. 21 Nov 2026

    CLAUDE.md vs AGENTS.md: which one Claude Code reads, and why I keep only oneWhen a repository has both files, Claude Code reads CLAUDE.md and leaves AGENTS.md alone unless you import it. I found five of my repositories set up the wrong way round: the real instructions in AGENTS.md, and a CLAUDE.md that only pointed at it.

    How I build · 5 min
  3. 20 Nov 2026

    Running several Claude Code agents at once: worktrees, handoffs and one check per phaseWhat broke when I put many Claude Code agents on the same repositories, and the four rules that stayed: one worktree per agent, small file-disjoint jobs, a rewritten handoff, and one full check per phase.

    How I build · 5 min