AI Coding

Claude Code Best Practices (2026): A Setup That Scales From One Engineer to a Team

Most Claude Code best practices come down to one decision: is this a guideline Claude should weigh, or a rule that must hold every time? Guidelines go in CLAUDE.md, rules and skills. Rules with no exceptions go in hooks, permission rules and the sandbox. This guide shows what belongs in each place, with config you can copy, which add-ons are worth installing, and how to roll the same setup out to a team.

Gurram Poorna Prudhvi

Lead AI Engineer

Intermediate
Nov 18, 2026
13 min read
CLAUDE CODE SETUP: WHAT GOES WHEREsome instructions Claude weighs · others Claude Code applies every timeLAYERWHAT BELONGS THEREWHO DECIDESWHERE IT LIVESCLAUDE.mdtest commands, gotchas, decisions not in the repoCLAUDE DECIDES./CLAUDE.mdRulesconventions for one part of the codebaseCLAUDE DECIDES.claude/rules/*.mdSkillsteam procedures: release, review, runbookCLAUDE DECIDES.claude/skills/<name>/SKILL.mdPermissionswhat Claude may read, run and fetchALWAYS ENFORCED.claude/settings.jsonHookssteps with zero exceptions: format, block a folderALWAYS ENFORCED.claude/settings.jsonSandboxOS-level limits on files and networkALWAYS ENFORCED/sandboxDone checktests, typecheck, a Stop hook, CIALWAYS ENFORCEDyour test commandMCP + pluginsoutside systems and ready-made packsADDS TOOLS.mcp.json · /pluginif it must happen every time, it does not belong in CLAUDE.mdaiengineerinsights.com · from Anthropic's Claude Code docs, checked Nov 18 2026

TL;DR — Claude Code best practices: keep CLAUDE.md under 200 lines and limit it to what Claude cannot read from the code. Put anything that must happen every time in a hook or a deny rule, because CLAUDE.md is advice. Give Claude a pass/fail check to run so it can finish without you. Install one workflow pack, not three. Commit the shared config, keep personal config local, and cap turns or spend on any run you are not watching.

Explore this article with

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

LayerWhat belongs thereWho decidesWhere it lives
CLAUDE.mdWhat Claude cannot work out from the code: test commands, misleading spots, team decisionsClaude decides./CLAUDE.md
RulesConventions for one part of the codebase, loaded only when Claude works thereClaude decides.claude/rules/*.md
SkillsProcedures: how you release, review, write docs, handle an incidentClaude decides (or only you start it).claude/skills/<name>/SKILL.md
Permission rulesWhat Claude may read, run and fetchAlways enforced.claude/settings.json
HooksSteps with zero exceptions: format after edit, block a folderAlways enforced.claude/settings.json
SandboxOS-level limits on files and network for shell commandsAlways enforced/sandbox
Done checkTests, typecheck, a Stop hook, CIAlways enforcedYour test command
MCP serversSystems with no CLI: issue tracker, docs, dashboardsAdds tools.mcp.json
PluginsReady-made packs of skills, hooks and subagentsAdds tools/plugin
SubagentsParallel work, noisy output, an independent reviewerClaude 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 /init for a first draft, then delete lines. The memory docs recommend staying under 200.
  • • /doctor suggests cuts for anything Claude can already work out from the code.
  • • Personal preferences go in CLAUDE.local.md, which you add to .gitignore.
  • • /context all confirms 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 it

Put 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 Stop hook 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: /sandbox turns on OS-level limits for shell commands on macOS, Linux and WSL2, and picks up your Read deny 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.

LayerOptionWhat it gives youPick it when
Workflow packEverything Claude Code (ECC)Broad: its plugin describes 38 agents, 156 skills and ready-made hooks, with a selective installYou want one pack that covers review, testing, security and many languages
Workflow packSuperpowersOpinionated: a fixed brainstorm, plan, test-first, review cycleYou want one process the whole team follows
LoopBuilt-in /goalKeeps working until a condition you write is metAlmost always: try this before any loop plugin
Loopralph-loop (Anthropic's marketplace)Re-feeds the same prompt until a completion phrase appearsYou want the Ralph technique exactly, with --max-iterations
Memoryclaude-memCarries context from earlier sessions into new onesLong projects where you keep re-explaining decisions
DocsContext7 (MCP server)Fetches current library documentationYou work with fast-moving libraries
BrowserPlaywright (MCP server)Lets Claude open a page and check the resultFront-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.

FileCommit it?Applies to
CLAUDE.mdYesEveryone on the repo
.claude/settings.jsonYesEveryone: permissions and hooks
.claude/rules/, .claude/skills/, .claude/agents/YesEveryone
.mcp.jsonYesEveryone: shared MCP servers
CLAUDE.local.mdNo, gitignore itOnly you, this project
.claude/settings.local.jsonNoOnly you, this project
~/.claude/CLAUDE.md, ~/.claude/settings.jsonNot in the repoOnly you, all projects
Managed settingsSet by an adminThe whole organisation; nobody can override them

A rollout order that avoids shipping everything at once:

  • • Week 1: a short CLAUDE.md with 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.
  • • /goal with no argument shows turns, time and token spend. /goal clear stops 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
  • • --bare skips 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.
  • • /schedule sets up cloud tasks that run on a timer. Protect main with 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 habitDo this instead
Writing IMPORTANT or ALL CAPS on a rule Claude keeps missingShorten the file, or move the rule to a hook or deny rule
Adding "think hard" or "be thorough" to promptsSet the effort level with /effort
Treating the context window as your main constraintUse /clear between tasks for focus and cost, not out of fear of running out
Delegating to a subagent to get a better answerUse subagents for parallel work, noisy output or a fresh reviewer
Telling Claude to keep going and not be lazyGive it a check to pass; use /goal or a Stop hook for unattended runs
Describing your architecture and folders in CLAUDE.mdLet 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

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.

Found this useful? Share it.

Share:

Related Articles