1. The One Idea: What Claude Decides vs What Claude Code Enforces
Anthropic's docs split every instruction into two kinds, and most setup problems are a rule filed under the wrong one.
- • Claude decides. Your prompt,
CLAUDE.md, rules and skills are text the model reads. It follows them nearly every time, but it is allowed to judge that a guideline does not apply. - • Claude Code enforces. Hooks, deny rules, the sandbox and managed settings are configuration the program applies itself. The model's opinion does not come into it.
Most of the time you want the first kind. Guidelines have exceptions, and a model looking at the actual code is usually better placed to spot one than a rule you wrote last month. Keep the second kind for the few things where "nearly every time" is not good enough: never read .env, always run the formatter, never edit the migrations folder.
A quick test: if you keep adding emphasis to a line in CLAUDE.md and Claude still misses it, the line is in the wrong place. It is either lost in a file that has grown too long, or it is a no-exceptions rule that belongs in a hook.
2. What Goes Where in a Claude Code Setup
| Layer | What belongs there | Who decides | Where it lives |
|---|---|---|---|
| CLAUDE.md | What Claude cannot work out from the code: test commands, misleading spots, team decisions | Claude decides | ./CLAUDE.md |
| Rules | Conventions for one part of the codebase, loaded only when Claude works there | Claude decides | .claude/rules/*.md |
| Skills | Procedures: how you release, review, write docs, handle an incident | Claude decides (or only you start it) | .claude/skills/<name>/SKILL.md |
| Permission rules | What Claude may read, run and fetch | Always enforced | .claude/settings.json |
| Hooks | Steps with zero exceptions: format after edit, block a folder | Always enforced | .claude/settings.json |
| Sandbox | OS-level limits on files and network for shell commands | Always enforced | /sandbox |
| Done check | Tests, typecheck, a Stop hook, CI | Always enforced | Your test command |
| MCP servers | Systems with no CLI: issue tracker, docs, dashboards | Adds tools | .mcp.json |
| Plugins | Ready-made packs of skills, hooks and subagents | Adds tools | /plugin |
| Subagents | Parallel work, noisy output, an independent reviewer | Claude delegates | .claude/agents/ |
Set these up in order, top to bottom, and stop when the problems stop. A solo developer on a small repo may never need more than the first four rows. New to the commands themselves? Keep the Claude Code cheat sheet open alongside this guide.
3. How to Write a CLAUDE.md That Works
Claude Code loads CLAUDE.md into every session, so each line costs a little attention on every task. The file earns its place only when it holds things Claude could not find by reading the repo:
- • How to check work here: the exact test, lint and typecheck commands, and how to run one test file.
- • Where the code misleads: an old pattern new code must not copy, a folder that looks dead but is not.
- • Decisions that are not in the repo: which helper the team settled on, how deploys work.
- • Anything you have corrected twice.
Here is a template for a Python service. It is short on purpose.
# Commands
- Install: uv sync
- Run one test file: uv run pytest tests/test_retrieval.py -q
- Lint and types: uv run ruff check . && uv run pyright
# Conventions
- Call models through app/llm/client.py, never import a vendor SDK directly
- Prompts live in app/prompts/*.md, not inline in Python
- app/legacy/ is still in production: fix bugs there, do not copy its patterns
# Gotchas
- Eval tests need EVAL_DATASET_PATH set, see .env.example
- Changing a prompt means re-running: uv run python -m evals.run --suite smoke- • Run
/initfor a first draft, then delete lines. The memory docs recommend staying under 200. - •
/doctorsuggests cuts for anything Claude can already work out from the code. - • Personal preferences go in
CLAUDE.local.md, which you add to.gitignore. - •
/context allconfirms the file was loaded.
Scope a rule to one folder
A rule that only matters in one part of the codebase goes in .claude/rules/ with a paths filter, so it loads only when Claude is working there:
# .claude/rules/api.md
---
paths:
- "app/api/**/*.py"
---
- Validate request bodies with the pydantic models in app/api/schemas/
- Every new endpoint needs an entry in openapi.yaml; CI fails without itPut procedures in skills
How your team cuts a release or writes a postmortem is a procedure, not a guideline. Save it as a skill at .claude/skills/<name>/SKILL.md. Claude sees only the short description until the task calls for it, so a long procedure does not weigh on unrelated work. For anything with side effects, add disable-model-invocation: true so it runs only when you type the command. The full walk-through is in Claude Skills: how to add, use and create them.
4. Give Claude a Check to Run
Claude stops when the work looks done. Without something that returns pass or fail, "looks done" is all it has, and you become the test suite. With a check, it can make the change, run the check, read the failure and fix it without you.
- • Ask for it: name the command in the prompt and in CLAUDE.md. This works most of the time.
- • Enforce it: a
Stophook runs the check whenever Claude tries to finish. Exit code 2 blocks the stop and sends the error output back to Claude.
// .claude/settings.json
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "uv run pytest -q 1>&2 || exit 2" }
]
}
]
}
}There is a safety valve: if a Stop hook blocks eight stops in a row with no tool call between them, Claude Code overrides the next block and ends the turn. Keep the check fast, because it runs on every stop.
Get the AI engineering newsletter
Practical, engineering-first breakdowns on AI agents, LLMs, and breaking into the field — plus the free roadmap PDF when you join. No spam.
By subscribing you agree to receive emails from AI Engineer Insights. Unsubscribe anytime. See our Privacy Policy.
5. Rules With No Exceptions: Hooks, Permissions and the Sandbox
Hooks
A hook runs your command at a fixed point: before or after a tool call, when Claude tries to stop, when a session starts. This one formats every Python file Claude edits, and blocks edits to a frozen folder:
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *.py) uv run ruff format \"$f\";; esac" }
]
}
],
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r '.tool_input.file_path' | grep -q '/migrations/' && { echo 'migrations/ is frozen' >&2; exit 2; } || exit 0" }
]
}
]
}
}You do not have to write these by hand. "Write a hook that blocks edits to the migrations folder" works as a prompt, and /hooks shows the result. One caution from the docs: a hook that asks a model to decide (a prompt or agent hook) is not deterministic. For real enforcement use a command or http hook.
Permission rules
Permission rules decide what Claude may run, read and fetch. deny rules hold in every permission mode, including auto and bypassPermissions, which is why secrets belong here:
// .claude/settings.json
{
"permissions": {
"allow": ["Bash(uv run pytest *)", "Bash(uv run ruff *)"],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
}
}Rules match tool calls, not intent. A Read deny rule catches cat .env too, but not a script that opens the file, and a WebFetch deny rule does nothing about curl unless the sandbox is on.
The sandbox and permission modes
- • Sandbox:
/sandboxturns on OS-level limits for shell commands on macOS, Linux and WSL2, and picks up yourReaddeny rules. For anything security-related, use permission rules and the sandbox together. - • Auto mode: what interactive sessions start in. A separate classifier model checks actions and stops things like
curl | bash, production deploys and force pushes. It is a judgment call, not a hard rule, so your "never" rules still belong in deny rules or hooks. - • Manual mode: you approve every edit and command. Safe, but people start approving without reading.
- • bypassPermissions: only in a container you can throw away.
Keep the enforced set small. Every hook and deny rule sometimes fires when it should not, and someone has to maintain it. The docs' own warning sign is forty of them: at that point most are preferences. For the security side in depth, see AI agent sandboxing and MCP server trust and permissions.
6. Which Claude Code Plugins and Add-Ons Are Worth Installing?
Add tools in layers and only when the layer below is working. Every installed skill and MCP server adds its name and description to each session, so more is not free. /usage breaks your usage down by skill, plugin and MCP server, and /skill-doctor shows what each skill costs.
| Layer | Option | What it gives you | Pick it when |
|---|---|---|---|
| Workflow pack | Everything Claude Code (ECC) | Broad: its plugin describes 38 agents, 156 skills and ready-made hooks, with a selective install | You want one pack that covers review, testing, security and many languages |
| Workflow pack | Superpowers | Opinionated: a fixed brainstorm, plan, test-first, review cycle | You want one process the whole team follows |
| Loop | Built-in /goal | Keeps working until a condition you write is met | Almost always: try this before any loop plugin |
| Loop | ralph-loop (Anthropic's marketplace) | Re-feeds the same prompt until a completion phrase appears | You want the Ralph technique exactly, with --max-iterations |
| Memory | claude-mem | Carries context from earlier sessions into new ones | Long projects where you keep re-explaining decisions |
| Docs | Context7 (MCP server) | Fetches current library documentation | You work with fast-moving libraries |
| Browser | Playwright (MCP server) | Lets Claude open a page and check the result | Front-end work |
- • Pick one workflow pack. ECC and Superpowers overlap. Running both loads two sets of planning and review skills into every session.
- • Use a CLI before an MCP server. If a system has a CLI Claude can call, such as
gh, that is usually simpler. Add MCP for systems without one:claude mcp add --transport http <name> <url>. - • Read before you install. Plugins can run code through hooks. Install from sources you trust and skim the hooks first.
Install the official loop plugin with /plugin install ralph-loop@claude-plugins-official. For the others, follow each project's own README: Everything Claude Code, Superpowers, claude-mem, Context7 and Playwright MCP.
7. How Do You Set Up Claude Code for a Team?
Where a file lives decides who it applies to. Commit the shared ones and keep the personal ones out of git.
| File | Commit it? | Applies to |
|---|---|---|
CLAUDE.md | Yes | Everyone on the repo |
.claude/settings.json | Yes | Everyone: permissions and hooks |
.claude/rules/, .claude/skills/, .claude/agents/ | Yes | Everyone |
.mcp.json | Yes | Everyone: shared MCP servers |
CLAUDE.local.md | No, gitignore it | Only you, this project |
.claude/settings.local.json | No | Only you, this project |
~/.claude/CLAUDE.md, ~/.claude/settings.json | Not in the repo | Only you, all projects |
Managed settings | Set by an admin | The whole organisation; nobody can override them |
A rollout order that avoids shipping everything at once:
- • Week 1: a short
CLAUDE.mdwith the test commands, plus deny rules for secrets. Review changes to it like code. - • Weeks 2–3: one formatting hook and one Stop hook. Add path-scoped rules where people keep correcting the same thing.
- • Month 2: turn repeated procedures into skills. Add shared MCP servers in
.mcp.json. - • Later: package the stable parts as a plugin so other repos can install them. Security policy goes in managed settings, the one place personal settings cannot override.
In a monorepo, give each team's directory its own CLAUDE.md. Files in subdirectories load on demand, so a team only loads its own conventions. This is the same shape as Conway's law for AI teams: the config ends up mirroring who owns what.
8. Letting Claude Code Run Without You
Before a run goes unattended, answer five questions for that task:
- • What does done look like? A goal condition, a spec file, or a failing test to turn green.
- • Can it check its own work? Tests, a Stop hook, a review step.
- • What may it touch? Permission rules, the sandbox, a worktree, one branch.
- • What stops it? A turn limit, a budget, a spend limit.
- • Who signs off? A pull request and a person approving the merge.
Goals: the built-in loop
/goal sets a completion condition and Claude keeps working until it is met. After each turn a separate model checks the condition. That checker reads the conversation; it does not run commands itself. So write a condition Claude's own output can prove:
/goal uv run pytest tests/retrieval exits 0 and ruff check is clean,
without editing any file under tests/, or stop after 20 turns- • One measurable end state, a stated check, and the constraints that matter.
- • A goal does not change your permission mode. Run it in auto mode if it should not stop to ask.
- •
/goalwith no argument shows turns, time and token spend./goal clearstops it.
/loop is different: it repeats a prompt on a time interval, which suits polling ("every 15 minutes, check CI"). A Stop hook is the deterministic version of a goal, because your script decides.
Scripts and CI
claude -p runs once and exits. In a script, pre-approve the tools it needs, refuse the rest, and cap the turns:
claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
--allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
--permission-mode dontAsk \
--max-turns 20- •
--bareskips hooks, skills, plugins, MCP servers and CLAUDE.md so the run behaves the same everywhere. Do not use it for a run that depends on your hooks. - •
claude -w <name>gives each parallel session its own git worktree so edits cannot collide. - •
/schedulesets up cloud tasks that run on a timer. Protectmainwith a branch rule before you leave one running. - • Try any unattended job on three files first.
9. Claude Code Advice You Can Stop Following
Much of the advice still circulating was a workaround for older models. Anthropic's docs now list these as habits to drop:
| Old habit | Do this instead |
|---|---|
| Writing IMPORTANT or ALL CAPS on a rule Claude keeps missing | Shorten the file, or move the rule to a hook or deny rule |
| Adding "think hard" or "be thorough" to prompts | Set the effort level with /effort |
| Treating the context window as your main constraint | Use /clear between tasks for focus and cost, not out of fear of running out |
| Delegating to a subagent to get a better answer | Use subagents for parallel work, noisy output or a fresh reviewer |
| Telling Claude to keep going and not be lazy | Give it a check to pass; use /goal or a Stop hook for unattended runs |
| Describing your architecture and folders in CLAUDE.md | Let Claude read the repo; write down only what is not in it |
10. FAQ
What are the best practices for Claude Code?
Keep CLAUDE.md short and limited to what Claude cannot read from the code. Put rules that must always hold in hooks, deny rules and the sandbox. Give Claude a pass/fail check such as your test command so it can verify its own work. Use /clear between unrelated tasks, and cap turns or spend on any run you are not watching.
What should go in CLAUDE.md?
Only what Claude cannot work out from the repo: the exact test, lint and typecheck commands, places where the code is misleading, team decisions that are not written in the code, and anything you have had to correct twice. Leave out architecture and folder descriptions, and keep the file under about 200 lines.
What is the difference between CLAUDE.md and hooks?
CLAUDE.md is text the model reads, so it is advice: Claude follows it nearly every time but can decide a guideline does not apply. A hook is a command Claude Code runs itself at a fixed point, so it happens every time. Use CLAUDE.md for guidelines and hooks for rules with zero exceptions.
Which Claude Code plugins should I install first?
Start with none and add them when a problem shows up. Then pick one workflow pack, such as Everything Claude Code or Superpowers, not both. Add a memory plugin for long projects and an MCP server such as Context7 or Playwright when you need current docs or a browser. Every add-on costs context in each session.
How do I set up Claude Code for a team?
Commit CLAUDE.md, .claude/settings.json, and the rules, skills and agents folders so everyone shares them. Keep CLAUDE.local.md and settings.local.json out of git for personal preferences. Start with a short CLAUDE.md and deny rules for secrets, add hooks next, then skills, and put security policy in managed settings.
Is auto mode safe to use in Claude Code?
Auto mode is the default for interactive sessions and is a reasonable middle ground. A classifier model checks each action and stops risky ones such as production deploys and force pushes. Because it is a model's judgment and not a hard rule, anything that must never happen should also be a deny rule or a hook, which apply before the classifier runs.
11. Sources
- • Claude Code docs — Best practices
- • Claude Code docs — Memory and CLAUDE.md
- • Claude Code docs — Hooks guide
- • Claude Code docs — Permission modes
- • Claude Code docs — Keep Claude working toward a goal
- • Claude Code docs — Skills
- • Anthropic — Steering Claude Code: CLAUDE.md, skills, hooks and subagents
- • ralph-loop plugin, Anthropic's official marketplace
Checked against Anthropic's Claude Code docs on November 18, 2026. The examples are ours, written for a Python project; adapt the commands to your stack and test each hook before you rely on it. Add-on descriptions come from each project's own repository. Claude Code ships updates weekly.