Configure Claude |

A CLAUDE.md That Follows

Sat, 03 Oct 2026 00:00:00 +0000

Note

TL;DR

Main idea: The leaner the CLAUDE.md, the more of it Claude follows.

Treat your CLAUDE.md like production code. If you can’t justify a line, delete it.
Keep CLAUDE.md lean and followable
- Move hard rules to hooks, where they’re actually enforced.
- Organize long files with imports
- Make every rule specific and checkable, and name the replacement.
- Spend your emphasis budget on the few rules that matter most.
- Keep revising the file whenever Claude gets something wrong.

First, Ask if CLAUDE.md Is Even the Right Tool

Before you write a rule, ask whether it belongs in CLAUDE.md at all:

Some rules are guidance / softer conventions. -> Can go to CLAUDE.md.
Some rules are hard lines that must never be crossed, e.g., “never push to main.”. A hard rule like that belongs in a pre-tool-use hook instead.

The Four Locations

There are four places CLAUDE.md can live, and Claude loads all of them together at launch. Nothing gets dropped, and they stack.

Managed policy — the org-level file your platform team controls. You can’t exclude it, so org policy is always in play.
User — your personal preferences that follow you across every project on your machine.
Project — the file shared with your team, checked into the repo.
Local — ignored by git. Your personal notes for this one repository only.

Split up a Big File with Imports

When your project file starts getting long, you can break it into pieces using the path-to-file import syntax. This is great for organizing.

For example:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

Use imports to organize, not to shrink the load.

When Claude launches, it expands those imported files inline, right where you referenced them. So imports help you keep things tidy, but everything still loads up front. They do not reduce the amount of context Claude has to read.

Phrasing Is What Makes Rules Stick

Be specific and checkable

If you can’t check whether it was followed, neither can Claude.

Example

Compare these two:

Vague: “Follow best practices for API routes.”
Specific: “Put new API routes in src/api/handlers, one per file.”

The second one is explicit and clear.

Name the replacement, don’t just ban something

When you tell Claude not to do something, say what to do instead. Otherwise you’ve left the door open.

Example

Leaves it open: “Don’t use default exports.” Okay, but then what?
Closes it: “Use named exports, not default exports.”

The second version names the replacement, so there’s nothing left to misinterpret.

Emphasis is a budget

Words like “IMPORTANT” and “YOU MUST” do raise a rule’s priority. But only relative to everything quieter around it. If every rule shouts, then nothing stands out and the emphasis means nothing.

Treat emphasis like a budget. Spend it on the two or three rules that really hurt when they get broken, and let the rest sit at normal volume.

Keep the File Under Revision

Your CLAUDE.md file is never finished. Treat it like living code that keeps getting edited.

When Claude does the wrong thing, don’t just fix it by hand. Treat it as a bug report against your CLAUDE.md file. You can even tell Claude directly: “add that to the CLAUDE.md file,” and it’ll write the rule for you.

-> That way the file gets better every time something goes wrong.

Verification Skills

Sat, 03 Oct 2026 00:00:00 +0000

Note

TL;DR

A skill is a folder with a SKILL.md inside it: a name, a description that triggers it, and the procedure itself.
If you’ve typed the same multi-step instruction twice, that’s a skill.

The rule of thumb: If you’ve typed the same multi-step instruction twice, that’s a skill.

Skill Folder

A skill isn’t just a single SKILL.md file. The folder around it can carry other things.

Drop a reference.md next to SKILL.md for detailed material, then link to it from SKILL.md. Claude reads it only when it needs that depth. Your main file stays short.
Put scripts in the folder too. Claude executes them rather than loading their contents into context. That means a skill can carry its own tooling, like a check.sh that runs all the gates.

Tip

keep SKILL.md itself lean. Push the heavy material (the long explanations and the executable scripts) into side files.

The lean file describes what to do. The side files hold the depth and the tools.

Which Instruction Surface Owns Which Rule

	Owns
`CLAUDE.md` file	Conventions that apply all the time, things like naming rules or where files go.
Skill	Procedures and reference material tied to a particular kind of task belong in a skill.
Hook	A rule that Claude must not be able to skip.

Permission Modes

Sat, 03 Oct 2026 00:00:00 +0000

Mode	What it does
Manual	Reads only, without prompting. Everything else asks first.
Accept edits	Runs reads, file edits, and common file system bash commands without asking. This is for iterating on code that you review after the fact.
Plan	Researches and proposes changes without editing anything. Reads run freely, and when auto mode is available, auto’s classifier reviews the commands Claude runs to explore and lets the approved ones run without a prompt.
Auto	Accepts everything, with a separate classifier model reviewing each action before it runs.
Don’t ask	Allows only pre-approved tools. Everything else is auto-denied with no prompt.
Bypass permissions	Kips all checks. This is the equivalent of the dangerously-skip-permissions flag. Only run it inside an isolated container or virtual machine!

Cycling with shift-tab

Press shift-tab to cycle through the everyday ones: manual, accept edits, plan, and auto.

The status bar at the bottom always shows which mode you’re currently in, so you can glance down and know exactly what Claude is allowed to do.

How `auto` Mode Works

Auto is the hands-off mode. Claude runs on its own, but before each action executes, a separate classifier model reviews it. The classifier guards intent. It’s watching for moves that escalate beyond what you actually asked for.

The kind of thing it’s designed to block:

Production deploys and migrations
Force pushing, or piping downloaded code straight into a shell
Sending sensitive data to external endpoints
Irreversibly destroying files that existed before the session

What the classifier can’t do: The classifier checks intent, not correctness. It won’t catch whether the code actually works.

Example

If you ask Claude to refactor authentication and it writes broken authentication, the classifier waves it through, because broken isn’t dangerous.

In this case, you should pair auto mode with a stop hook that runs your tests. The two work together:

Auto mode watches what Claude is trying to do while it runs.
The stop hook confirms the code actually runs once Claude finishes.

One guards intent before each action, the other guards correctness after.

Use `dontAsk` Mode for Unattended Runs

Don’t ask (``dontAsk`) is the right move whenever no human is around to approve prompts, such as: CI pipelines, scheduled jobs, overnight batches.

Only pre-approved tools are allowed, and anything off that list gets auto-denied with no prompt. Your pipeline keeps moving instead of hanging on an approval no one is there to give.

How to enable: Set it with--permission-mode dontAsk. Example:

claude --permission-mode dontAsk --allowedTools "Read,Glob,Grep"

Match the Mode to the Job

Pick the mode that fits what you’re doing, and let Claude run at that level.

Auto is the hands-off mode. The classifier checks intent before each action, and a stop hook checks correctness after.
Don’t ask covers unattended pipelines where no one is there to approve.
Bypass permissions belongs only inside isolated containers and VMs.

Hooks

Sat, 03 Oct 2026 00:00:00 +0000

A hook is deterministic code that runs at a fixed point in the loop, so it can guarantee behavior instead of hoping for it. It turns a rule from “Claude usually listens” into “Claude can’t skip it.”

Interactive Claude Code hooks explorer

The Hook Events

Claude Code fires around 30 hook events over the course of a session. These are the ones worth knowing:

PreToolUse fires before a tool call. This is your enforcement primitive. It’s the one that can stop something before it happens.
PostToolUse fires after a successful tool call. This is usually where auto-formatting or an auto-lint goes.
Stop fires when Claude wants to end its turn. You can refuse and say “no, you’re not done yet” if some condition isn’t met. There’s a matching SubagentStop for when a sub-agent finishes.
PreCompact and PostCompact fire before and after compaction.
InstructionsLoaded fires when a CLAUDE.md or rule file loads. Handy for auditing what actually made it into context.
SessionStart fires at the start and primes the environment. Use the startup source if you only want it on fresh starts.

Tip

To re-inject context after compaction, don’t use PostCompact. Use SessionStart with the compact matcher. That’s the one that actually gets its output back into the conversation.

PreToolUse: Returning a Decision as JSON

PreToolUse can block a tool call before it runs.

The way you talk back to Claude is by printing JSON and exiting zero. The key field is permissionDecision, and it takes one of three values:

allow — let the call through
deny — stop the call
ask — hand it back to the user to decide

The JSON looks like this:

{
 "hookSpecificOutput": {
 "hookEventName": "PreToolUse",
 "permissionDecision": "deny",
 "permissionDecisionReason": "...",
 "updatedInput": {
 "command": "..."
 }
 }
}

Visual explanation

Example

A PreToolUse hook on the Bash tool. Claude wants to run: rm -rf / .

Before running the command, the PreToolUse hook is triggered. It prints JSON and exits 0:

{
 "hookSpecificOutput": {
 "hookEventName": "PreToolUse",
 "permissionDecision": "deny",
 "permissionDecisionReason": "Destructive command"
 }
}

Tip

Instead of just refusing, you can return updatedInput to rewrite the call. This way, you can strip a secret out of a command and still let it run.

Notice: updatedInput replaces the whole input object, so you have to echo back the fields you aren’t changing, or you’ll lose them.

Exit Codes

Not every hook needs to speak JSON. For simpler hooks, exit codes do the job.

Exit code	Meaning	Remarks
0	success	If standard out is JSON, Claude parses it. Plain text is ignored on most events, but on SessionStart, UserPromptSubmit, and UserPromptExpansion, plain text gets added to context. That’s exactly what makes a state-preserver hook work.
2	blocking error	Standard error gets fed back to Claude as context.
Anything else	Non-blocking	Standard error gets logged, and Claude carries on. ‼️ Gotcha: exit code 1 feels like an error, but it does not block. Claude runs the command anyway. So if you meant to stop something, exit 2, not 1.

Preserving State across a Compact

Compaction is lossy: When Claude compacts a long conversation, it drops a lot of detail, such as the exact files you were editing, or the branch name.

Fix: Use a SessionStart hook with the compact matcher to put the important facts back, deterministically, right after compaction.

Interactive example: Preserving State across a Compact

Example (Python)

# .claude/hooks/restore_state.py
import subprocess

files = subprocess.run(["git", "diff", "--name-only"],
 capture_output=True, text=True).stdout.strip()
branch = subprocess.run(["git", "branch", "--show-current"],
 capture_output=True, text=True).stdout.strip()

print(f"Context restored after compaction.\nBranch: {branch}\nFiles in progress:\n{files}")
# exit 0 (default): stdout from SessionStart is added to context

In the settings.json, a compact matcher is registered:

"SessionStart": [{
 "matcher": "compact",
 "hooks": [{ "type": "command", "command": "python3 .claude/hooks/restore_state.py" }]
}]

Configure Claude |

A CLAUDE.md That Follows

TL;DR

First, Ask if CLAUDE.md Is Even the Right Tool

The Four Locations

Split up a Big File with Imports

Phrasing Is What Makes Rules Stick

Be specific and checkable

Name the replacement, don’t just ban something

Emphasis is a budget

Keep the File Under Revision

Verification Skills

TL;DR

Skill Folder

Which Instruction Surface Owns Which Rule

Permission Modes

Cycling with shift-tab

How auto Mode Works

Use dontAsk Mode for Unattended Runs

Match the Mode to the Job

Hooks

The Hook Events

PreToolUse: Returning a Decision as JSON

Exit Codes

Preserving State across a Compact

How `auto` Mode Works

Use `dontAsk` Mode for Unattended Runs