Best practices for Claude Code changedbest-practices
Nearest release: v2.1.311, published 5 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 27 Oct 2026 01:12 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 27 Oct 2026 01:37 UTC.
Upstream edited
Recorded here
Lines+607added
Lines−551removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits26to this page, all time
## Deterministic and non-deterministic instructions ## Tell Claude what it can't see ### Write a specific prompt ### Brainstorm with Claude first ### Keep CLAUDE.md short ### Scope rules to one part of the codebase ### Put team procedures in skills ### Connect the tools Claude needs ## Give Claude a check to run ### Review against your spec ### Enforce the check with a Stop hook ## Enforce the rules that can't have exceptions ### Enforce steps with hooks ### Limit access with permission rules and the sandbox ### Choose who a rule applies to ## Change a default ### Change the permission mode ### Change the model and effort ### Know what subagents cost ### Keep cost and context down ## Steer the session ## Let Claude run without you ### Run Claude from a script ### Start runs on a schedule or an event ### Run sessions in parallel ## What you can stop doing ## Give Claude a way to verify its work ## Explore first, then plan, then code ## Provide specific context in your prompts ### Provide rich content ## Configure your environment ### Write an effective CLAUDE.md ### Configure permissions ### Use CLI tools ### Connect MCP servers ### Set up hooks ### Create skills ### Create custom subagents ### Install plugins ## Communicate effectively ### Ask codebase questions ### Let Claude interview you ## Manage your session ### Course-correct early and often ### Manage context aggressively ### Use subagents for investigation ### Rewind with checkpoints ### Resume conversations ## Automate and scale ### Run non-interactive mode ### Run multiple Claude sessions ### Fan out across files ### Run autonomously with auto mode ### Add an adversarial review step ## Avoid common failure patterns ## Develop your intuition
The whole hunk
from line 1, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
11# Best practices for Claude Code
22
3> Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.
4
5Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely.
6
7This changes how you work. Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it. Claude explores, plans, and implements.
8
9But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand.
10
11This guide covers patterns that have proven effective across Anthropic's internal teams and for engineers using Claude Code across various codebases, languages, and environments. For how the agentic loop works, see [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md).
12
13***
14
15Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.
16
17Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.
18
19This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. To see how a session fills up in practice, [watch an interactive walkthrough](https://code.claude.com/docs/en/context-window.md) of what loads at startup and what each file read costs. Track context usage continuously with a [custom status line](https://code.claude.com/docs/en/statusline.md), and see [Reduce token usage](https://code.claude.com/docs/en/costs.md#reduce-token-usage) for strategies on reducing token usage.
20
21***
22
23## Give Claude a way to verify its work
24
25> [!TIP]
26>
27> Give Claude a check it can run: tests, a build, a screenshot to compare. It's the difference between a session you watch and one you walk away from.
28
29Claude stops when the work looks done. Without a check it can run, "looks done" is the only signal available, and you become the verification loop: every mistake waits for you to notice it. Give Claude something that produces a pass or fail, and the loop closes on its own. Claude does the work, runs the check, reads the result, and iterates until the check passes.
30
31The check is anything that returns a signal Claude can read in the conversation: a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a [browser screenshot](https://code.claude.com/docs/en/chrome.md) compared against a design. Run [`/verify`](https://code.claude.com/docs/en/skills#run-and-verify-your-app) yourself after Claude's check passes to confirm the change against the running app.
32
33| Strategy | Before | After |
34| - | - | - |
35| **Provide verification criteria** | *"implement a function that validates email addresses"* | *"write a validateEmail function. example test cases: [[email protected]](mailto:[email protected]) is true, invalid is false, [[email protected]](mailto:[email protected]) is false. run the tests after implementing"* |
36| **Verify UI changes visually** | *"make the dashboard look better"* | *"\[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them"* |
37| **Address root causes, not symptoms** | *"the build is failing"* | *"the build fails with this error: \[paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"* |
38
39Once the check exists, decide how hard it gates the stop:
40
41* **In one prompt**: ask Claude to run the check and iterate in the same message, as in the table above.
42* **Across a session**: set the check as a [`/goal` condition](https://code.claude.com/docs/en/goal). A separate evaluator re-checks it after every turn and Claude keeps working until the goal resolves. If Claude stalls, Claude Code eventually stops the run with the goal still set — see [how /goal evaluation works](https://code.claude.com/docs/en/goal.md#how-evaluation-works).
43* **As a deterministic gate**: a [Stop hook](https://code.claude.com/docs/en/hooks.md#stop) runs your check as a script and blocks the turn from ending until it passes. [Stop input](https://code.claude.com/docs/en/hooks.md#stop-input) covers the cap on consecutive blocks.
44* **By a second opinion**: a [verification subagent](https://code.claude.com/docs/en/sub-agents.md) or a [dynamic workflow](https://code.claude.com/docs/en/workflows.md) that checks its own findings has a fresh model try to refute the result, so the agent doing the work isn't the one grading it.
45
46Each step trades setup for attention. The prompt version works on any task today. The `/goal` and Stop hook versions are what let an unattended run finish correctly without you.
47
48Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result. Reviewing evidence is faster than re-running the verification yourself, and it works for sessions you weren't watching.
49
50***
51
52## Explore first, then plan, then code
53
54> [!TIP]
55>
56> Separate research and planning from implementation to avoid solving the wrong problem.
57
58Letting Claude jump straight to coding can produce code that solves the wrong problem. Use [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to separate exploration from execution.
59
60The recommended workflow has four phases:
61
62**1. Explore**
63
64Enter plan mode by pressing `Shift+Tab` until the status bar shows `⏸ plan mode on`, or start the session with `claude --permission-mode plan`. Claude reads files and answers questions without making changes.
65
66```txt title="claude (plan mode)" wrap theme={null}
67read /src/auth and understand how we handle sessions and login.
68also look at how we manage environment variables for secrets.
69```
70
71**2. Plan**
72
73Ask Claude to create a detailed implementation plan.
74
75```txt title="claude (plan mode)" wrap theme={null}
76I want to add Google OAuth. What files need to change?
77What's the session flow? Create a plan.
78```
79
80Press `Ctrl+G` to open the plan in your text editor for direct editing before Claude proceeds.
81
82**3. Implement**
83
84Switch out of plan mode by approving the plan or pressing `Shift+Tab`, then let Claude code, verifying against its plan.
85
86```txt title="claude" wrap theme={null}
87implement the OAuth flow from your plan. write tests for the
88callback handler, run the test suite and fix any failures.
89```
90
91**4. Commit**
92
93Ask Claude to commit with a descriptive message and create a PR.
94
95```txt title="claude" wrap theme={null}
96commit with a descriptive message and open a PR
97```
98
99Plan mode is useful, but also adds overhead.
100
101For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.
102
103Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.
104
105***
106
107## Provide specific context in your prompts
108
109> [!TIP]
110>
111> The more precise your instructions, the fewer corrections you'll need.
112
113Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.
114
115| Strategy | Before | After |
116| - | - | - |
117| **Scope the task.** Specify which file, what scenario, and testing preferences. | *"add tests for foo.py"* | *"write a test for foo.py covering the edge case where the user is logged out. avoid mocks."* |
118| **Point to sources.** Direct Claude to the source that can answer a question. | *"why does ExecutionFactory have such a weird api?"* | *"look through ExecutionFactory's git history and summarize how its api came to be"* |
119| **Reference existing patterns.** Point Claude to patterns in your codebase. | *"add a calendar widget"* | *"look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. build from scratch without libraries other than the ones already used in the codebase."* |
120| **Describe the symptom.** Provide the symptom, the likely location, and what "fixed" looks like. | *"fix the login bug"* | *"users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"* |
121
122Vague prompts can be useful when you're exploring and can afford to course-correct. A prompt like `"what would you improve in this file?"` can surface things you wouldn't have thought to ask about.
123
124### Provide rich content
125
126> [!TIP]
127>
128> Use `@` to reference files, paste screenshots/images, or pipe data directly.
129
130You can provide rich data to Claude in several ways:
131
132* **Reference files with `@`** instead of describing where code lives. Claude reads the file before responding.
133* **Paste images directly**. Copy/paste or drag and drop images into the prompt.
134* **Give URLs** for documentation and API references. Use `/permissions` to allowlist frequently used domains.
135* **Pipe in data** by running `cat error.log | claude -p "explain this error"` to send file contents directly.
136* **Let Claude fetch what it needs**. Tell Claude to pull context itself using Bash commands, MCP tools, or by reading files.
137
138***
139
140## Configure your environment
141
142A few setup steps make Claude Code significantly more effective across all your sessions. For a full overview of extension features and when to use each one, see [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md).
143
144### Write an effective CLAUDE.md
145
146> [!TIP]
147>
148> Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.
149
150CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.
151
152There's no required format for CLAUDE.md files, but keep it short and human-readable. For example:
3> Get more out of Claude Code: tell Claude what it can't see, give it a check to run, and enforce the rules that can't have exceptions.
4
5Claude Code is built in a way that, in most cases, your first plain prompt in a fresh session already does the right thing, without any setup on your part.
6
7For example:
8
9* To let commands run safely without you approving each one, new terminal and VS Code sessions start in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), where a classifier reviews anything risky before it runs.
10* To keep your main conversation focused while independent work happens in parallel, Claude delegates to subagents and checks in only when it has to.
11* To keep a long session going without you managing it, your conversation is compacted automatically before the context window fills.
12
13This page covers what to do when the defaults aren't enough. That usually happens when your project has knowledge, rules, or constraints that Claude can't see from the code alone:
14
15* A deploy process that lives in someone's head
16* A file that must never be read
17* A check that has to pass before anything counts as done
18* A budget you need to stay under
19
20No default can know those things about your project, so this is where a small amount of setup on your side pays off.
21
22When a session doesn't go the way you expected, it's almost always one of these:
23
24* Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It's missing information it can't get from reading the repo. See [Tell Claude what it can't see](#tell-claude-what-it-cant-see).
25* Claude said it was done and it wasn't quite, usually because it had no way to check its own work. See [Give Claude a check to run](#give-claude-a-check-to-run).
26* Claude did something that must never happen in this repo, or skipped a step that must always happen. A prompt alone can't guarantee either of those. See [Enforce the rules that can't have exceptions](#enforce-the-rules-that-cant-have-exceptions).
27* Claude got it right, but it took more time, tokens, or permission prompts than the task was worth. See [Change a default](#change-a-default).
28
29[Let Claude run without you](#let-claude-run-without-you) applies the same four points to unattended runs, and [What you can stop doing](#what-you-can-stop-doing) lists the advice that current models have made unnecessary.
30
31> [!NOTE]
32>
33> Setup for a whole team is on a separate page: [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md).
34
35## Deterministic and non-deterministic instructions
36
37Every instruction you give Claude Code is one of these:
38
391. Non-deterministic: you write the instruction, and Claude (the model) reads it. This can be your prompt, `CLAUDE.md`, or a skill. The model then decides what to do with this information. It usually follows your commands, and current models are good at understanding your intent without much context, but there's no *guarantee* that it'll follow your instructions. It can still decide not to do things, or do other things.
402. Deterministic: you configure the instruction, and Claude Code (the harness) *has* to execute this. This can be a hook, a deny rule, or a managed setting. Claude Code applies this every time, no matter what the model decided to do.
41
42Most things in Claude Code come in both forms:
43
44| | Non-deterministic (Claude decides) | Deterministic (Claude Code enforces) |
45| :- | :- | :- |
46| What to do | Your prompt, `CLAUDE.md`, skills Claude picks up itself | Hooks, and which skills only you can start |
47| What it can touch | Auto mode's classifier | Deny rules, the sandbox in [strict mode](https://code.claude.com/docs/en/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode), managed settings |
48| When it's done | A request for evidence, `/goal`, `/code-review` | Tests, typecheck, a `Stop` hook, CI |
49| How much it spends | Effort level, Claude's own pace | `--max-turns` or [`--max-budget-usd`](https://code.claude.com/docs/en/cli-reference) with `-p`, a [spend limit](https://code.claude.com/docs/en/costs.md) you've set |
50| Who has the last word | Claude's summary of what it did | Branch protection, a person who approves the merge |
51
52Most of the time, you want Claude to decide. Almost every guideline has exceptions, and current models are good at reading the code in front of them and judging whether a guideline fits the situation. With the actual code in front of it, Claude is usually better placed to make that call than a rule you wrote in advance.
53
54The deterministic kind is for when you want to make sure certain things *always* happen (or never happen), no matter what the model decides. This doesn't have to be anything dramatic. Auto mode already [blocks the dramatic things](https://code.claude.com/docs/en/permission-modes.md#what-the-classifier-blocks-by-default), like a production deploy or a force push over someone's work. It's usually something specific to *your* project, and it can be as niche as you want it to be:
55
56* Never edit the generated client in `src/gen/`
57* Always run the license-header script after creating a file
58
59You could've written either of these as a line in `CLAUDE.md` or in your prompt, and Claude would follow it nearly every time. But no matter how strongly you word it, whether Claude follows that line on a given turn is still Claude's call.
60
61> [!TIP]
62>
63> If you keep adding emphasis to a `CLAUDE.md` line and Claude still misses it, that's a sign the line belongs in a hook. The reverse holds too: if you have hooks for things that are only preferences, delete them and let Claude decide.
64
65## Tell Claude what it can't see
66
67> [!TIP]
68>
69> Only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session.
70
71Claude starts every task by reading your code, and current models are *very* good at this. They'll find your file layout, your conventions, your test framework, and how existing components are built, usually faster than you could explain them. That means Claude already knows most of what you might be tempted to write down for it.
72
73What it can't find is the information that was never in the repo:
74
75* A decision your team made in a meeting
76* A deploy process that lives in one person's head
77* The environment variable your integration tests need
78
79There's also information that *is* in the repo but takes a few minutes of digging to find, and Claude has to redo that digging at the start of every session.
80
81A good test before you write anything down for Claude:
82
831. Could it find this by reading the code?
842. Would it actually go and look?
85
86If both are yes, leave it out.
87
88### Write a specific prompt
89
90A specific prompt helps for the same reason, because it gives Claude information it doesn't already have. If you name the file, describe the symptom, and say what "fixed" looks like up front, you usually save yourself a round of corrections later.
91
92The same goes for a preference between two reasonable approaches: Claude can't read that from the code, so if you care which one it picks, say so up front.
93
94| Instead of | Try |
95| :- | :- |
96| *"fix the login bug"* | *"users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it"* |
97| *"add a calendar widget"* | *"follow the pattern in HotDogWidget.php and build a calendar widget that lets you pick a month and page between years. no new libraries"* |
98
99If you already have the thing Claude needs, hand it over instead of describing it:
100
101* A file: type `@` and the path to [include the file contents](https://code.claude.com/docs/en/common-workflows.md#reference-files-and-directories) in your message.
102* An image: paste the screenshot of the design or the error into the prompt.
103* Command output: pipe it in from your shell with `cat error.log | claude -p "what's going on here"`.
104
105Phrases like `think step by step` or `be thorough` are ordinary prompt text rather than keywords. The main control for how hard Claude thinks is the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), which [Change the model and effort](#change-the-model-and-effort) covers. Wording like that can still nudge Claude within its effort setting, but it won't lift it past it.
106
107One phrase that does still help is `be ambitious`. Claude tends to read a request conservatively and build the smallest thing that satisfies it, since it can't see how much you were hoping for. When you want the fuller version, with the edge cases handled and the natural follow-on included, say so:
108
109```text theme={null}
110build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout
111```
112
113That's telling Claude about scope, which only you know, rather than how hard to think.
114
115And when you're exploring rather than fixing something specific, a vague prompt like `what would you improve in this file?` is completely fine. You'll correct a bit more as you go, and that's the trade-off.
116
117### Brainstorm with Claude first
118
119When you don't know exactly what you want yet, you don't have to work it all out before you prompt. Ask Claude to interview you instead:
120
121```text theme={null}
122I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.
123```
124
125Claude comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope. It keeps asking until the answers add up to a spec.
126
127Once `SPEC.md` exists, start a fresh session to build from it, so the build begins with a clean context and a written definition of done. It's also the file you'll point the reviewer at later, in [Give Claude a check to run](#give-claude-a-check-to-run).
128
129### Keep CLAUDE.md short
130
131Claude Code loads [`CLAUDE.md`](https://code.claude.com/docs/en/memory) into every session, which means every line in it takes a little of Claude's attention on *every* task, whether it's relevant or not. That's why the file works best when it only holds what Claude couldn't work out from the code itself:
132
133* How to confirm work in this repo: the exact test, typecheck, and lint commands, and how to run a single test file
134* Places where the code is misleading: an old pattern that's everywhere but that new code must not copy, or a directory that looks unused but isn't
135* Decisions that aren't in the repo: which error helper the team settled on, how deploys work, what needs a migration review
136* Anything you've had to correct twice already
137
138A `CLAUDE.md` that passes that test stays short:
153139
154140```markdown CLAUDE.md theme={null}
155# Code style
156- Use ES modules (import/export) syntax, not CommonJS (require)
157- Destructure imports when possible (eg. import { foo } from 'bar')
158
159# Workflow
160- Be sure to typecheck when you're done making a series of code changes
161- Prefer running single tests, and not the whole test suite, for performance
162```
163
164Run `/context` to confirm Claude loaded the file. CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use [skills](https://code.claude.com/docs/en/skills.md) instead. Claude loads them on demand without bloating every conversation.
165
166Keep it concise. For each line, ask: *"Would removing this cause Claude to make mistakes?"* If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!
167
168| ✅ Include | ❌ Exclude |
169| - | - |
170| Bash commands Claude can't guess | Anything Claude can figure out by reading code |
171| Code style rules that differ from defaults | Standard language conventions Claude already knows |
172| Testing instructions and preferred test runners | Detailed API documentation (link to docs instead) |
173| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
174| Architectural decisions specific to your project | Long explanations or tutorials |
175| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |
176| Common gotchas or behaviors that aren't self-evident | Self-evident practices like "write clean code" |
177
178If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost. If Claude asks you questions that are answered in CLAUDE.md, the phrasing might be ambiguous. Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude's behavior actually shifts. For a checked-in CLAUDE.md, run [`/doctor`](https://code.claude.com/docs/en/commands#all-commands) and Claude proposes cuts for content it can derive from the codebase.
179
180If Claude keeps skipping one instruction, add emphasis such as "IMPORTANT" to that line alone. If you emphasize many lines, none of them stands out. Check CLAUDE.md into git so your team can contribute. The file compounds in value over time.
181
182CLAUDE.md files can import additional files using `@path/to/import` syntax. For import rules and where CLAUDE.md files can live, see [CLAUDE.md files](https://code.claude.com/docs/en/memory.md#claude-md-files).
183
184### Configure permissions
185
186> [!TIP]
187>
188> To get fewer prompts without giving up control, pre-approve the tools you trust with `/permissions` and let sandboxed commands run without asking with `/sandbox`. Switch to Manual mode when you want to approve edits and commands yourself.
189
190With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for interactive terminal and VS Code sessions: a separate classifier model reviews most actions instead of you and blocks only what looks risky, such as scope escalation, unknown infrastructure, or hostile-content-driven actions. On earlier versions, auto mode is the built-in starting permission mode only on Pro, Max, and Team plans.
191
192In Manual mode, Claude Code asks before actions that might modify your system: file writes, Bash commands, MCP tools. That's safe but tedious. After the tenth approval you're clicking through rather than reviewing. Two tools cut those interruptions in Manual mode and apply in auto mode as well:
193
194* **Permission allowlists**: permit specific tools you know are safe, like `npm run lint` or `git commit`
195* **Sandboxing**: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries
196
197Read more about [permission modes](https://code.claude.com/docs/en/permission-modes.md), [permission rules](https://code.claude.com/docs/en/permissions.md), and [sandboxing](https://code.claude.com/docs/en/sandboxing.md).
198
199### Use CLI tools
200
201> [!TIP]
202>
203> Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.
204
205CLI tools are the most context-efficient way to interact with external services. If you use GitHub, install the `gh` CLI. Claude knows how to use it for creating issues, opening pull requests, and reading comments. Without `gh`, Claude can still use the GitHub API, but unauthenticated requests often hit rate limits.
206
207Claude is also effective at learning CLI tools it doesn't already know. Try prompts like `Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.`
208
209### Connect MCP servers
210
211> [!TIP]
212>
213> Run `claude mcp add` with a server name and URL or command to connect external tools like Notion, Figma, or your database. For example: `claude mcp add --transport http notion https://mcp.notion.com/mcp`.
214
215With [MCP servers](https://code.claude.com/docs/en/mcp.md), you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.
216
217### Set up hooks
218
219> [!TIP]
220>
221> Use hooks for actions that must happen every time with zero exceptions.
222
223[Hooks](https://code.claude.com/docs/en/hooks-guide.md) run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.
224
225Claude can write hooks for you. Try prompts like *"Write a hook that runs eslint after every file edit"* or *"Write a hook that blocks writes to the migrations folder."* Edit `.claude/settings.json` directly to configure hooks by hand, and run `/hooks` to browse what's configured.
226
227### Create skills
228
229> [!TIP]
230>
231> Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.
232
233[Skills](https://code.claude.com/docs/en/skills.md) extend Claude's knowledge with information specific to your project, team, or domain. Claude applies them automatically when relevant, or you can invoke them directly with `/skill-name`.
234
235Create a skill by adding a directory with a `SKILL.md` to `.claude/skills/`:
236
237```markdown .claude/skills/api-conventions/SKILL.md theme={null}
141# Commands
142- Install: pnpm install
143- Run one test file: pnpm vitest run path/to/file.test.ts
144- Typecheck: pnpm tsc --noEmit
145
146# Conventions
147- Use the error helpers in src/lib/errors.ts, never throw raw strings
148- src/legacy/ is still live but don't copy its patterns into new code
149
150# Gotchas
151- Integration tests need DATABASE_URL set, see .env.example
152```
153
154In a session, run `/context` to confirm that Claude loaded the file.
155
156Notice that the typecheck line is only the command. Claude needs to know the command so it can check its own work as it goes. If you also want Claude Code to *enforce* a passing typecheck before Claude finishes, that's a job for a [`Stop` hook](#enforce-the-check-with-a-stop-hook). A line like `Always typecheck before you finish` in this file works most of the time, not every time.
157
158You don't have to write the file from scratch:
159
160* `/init` generates a starting version from your codebase. From there the work is mostly removing lines. The [memory guide](https://code.claude.com/docs/en/memory.md#write-effective-instructions) recommends staying under 200.
161* `/doctor` suggests cuts for anything Claude can [already work out from the code](https://code.claude.com/docs/en/memory.md#my-claude-md-is-too-large).
162* `/doctor prompt-audit` flags instructions that were written for older models, point at files that no longer exist, or [contradict each other](https://code.claude.com/docs/en/memory.md#audit-your-instruction-files).
163
164Your personal preferences go in `CLAUDE.local.md` instead of `CLAUDE.md`, and you add that file to `.gitignore` so it stays out of the repo.
165
166> [!NOTE]
167>
168> If Claude keeps ignoring a line that *is* in `CLAUDE.md`, adding IMPORTANT probably won't fix it. Either the file has grown long enough that the line gets lost, or the line is a rule that can't have exceptions, in which case it belongs in a [hook](#enforce-the-rules-that-cant-have-exceptions).
169
170### Scope rules to one part of the codebase
171
172If a rule only matters in one part of the codebase, put it in [`.claude/rules/`](https://code.claude.com/docs/en/memory#path-specific-rules) with a `paths:` filter so it only loads when Claude is actually working there. For example, this `.claude/rules/api.md` loads for TypeScript files under `src/api/`:
173
174```markdown .claude/rules/api.md theme={null}
238175---
239name: api-conventions
240description: REST API design conventions for our services
176paths:
177 - "src/api/**/*.ts"
241178---
242# API Conventions
243- Use kebab-case for URL paths
244- Use camelCase for JSON properties
245- Always include pagination for list endpoints
246- Version APIs in the URL path (/v1/, /v2/)
247```
248
249Skills can also define repeatable workflows you invoke directly:
250
251```markdown .claude/skills/fix-issue/SKILL.md theme={null}
179- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
180- Every new endpoint needs an entry in openapi.yaml, CI fails without it
181```
182
183### Put team procedures in skills
184
185A more capable model knows more about engineering, but not how *your* team does a release, what your incident runbook says, or how you want API docs written. That kind of knowledge goes in a [skill](https://code.claude.com/docs/en/skills.md): a procedure or a piece of team knowledge saved at `.claude/skills/<name>/SKILL.md`.
186
187Skills are also lighter on context than `CLAUDE.md` for this kind of thing. For a skill Claude can start on its own, it sees the name and description in every session, but only [reads the full file](https://code.claude.com/docs/en/skills.md#skill-content-lifecycle) when the task calls for it. A long release procedure sitting in a skill doesn't weigh on your unrelated bug fix the way it would in `CLAUDE.md`.
188
189> [!NOTE]
190>
191> The `CLAUDE.md` rule applies to skills too: only write down what Claude can't find on its own.
192
193For a workflow with side effects, like actually cutting that release, add `disable-model-invocation: true`. Claude then [can't start the skill on its own](https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill), and it only runs when you type `/release` yourself. Saved as `.claude/skills/release/SKILL.md`, it could look like this:
194
195```markdown .claude/skills/release/SKILL.md theme={null}
252196---
253name: fix-issue
254description: Fix a GitHub issue
197name: release
198description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
255199disable-model-invocation: true
256200---
257Analyze and fix the GitHub issue: $ARGUMENTS.
258
2591. Use `gh issue view` to get the issue details
2602. Understand the problem described in the issue
2613. Search the codebase for relevant files
2624. Implement the necessary changes to fix the issue
2635. Write and run tests to verify the fix
2646. Ensure code passes linting and type checking
2657. Create a descriptive commit message
2668. Push and create a PR
267```
268
269Run `/fix-issue 1234` to invoke it. Use `disable-model-invocation: true` for workflows with side effects that you want to trigger manually.
270
271### Create custom subagents
272
273> [!TIP]
274>
275> Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.
276
277[Subagents](https://code.claude.com/docs/en/sub-agents.md) run in their own context with their own set of allowed tools. They're useful for tasks that read many files or need specialized focus without cluttering your main conversation.
278
279```markdown .claude/agents/security-reviewer.md theme={null}
2011. Make sure you're on main with a clean tree. If not, stop and ask.
2022. Run `pnpm changeset version` and commit the result.
2033. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
2044. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.
205```
206
207### Connect the tools Claude needs
208
209Some of what Claude can't see lives in another system entirely, like your issue tracker or your error dashboard. If that system has a CLI, that's usually the easiest way in. With `gh` installed and signed in, for example, Claude will open pull requests and read review comments without any explanation from you. For a CLI it hasn't seen before, pointing it at `--help` is enough.
210
211For systems without a CLI, there's [MCP](https://code.claude.com/docs/en/mcp.md). You add a server from your shell:
212
213```bash theme={null}
214claude mcp add --transport http notion https://mcp.notion.com/mcp
215```
216
217The server then shows up under `/mcp` inside a session. Connected servers add their tool names and instructions to the context even when you're not using them, so it's worth [turning off the ones you don't need](https://code.claude.com/docs/en/mcp.md#disable-a-server-without-removing-it) there.
218
219And if you work in a typed language, a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) lets Claude jump straight to a definition instead of reading through many files to find it.
220
221## Give Claude a check to run
222
223Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually *is* done, "looks done" is all it has to go on. In practice that makes you the test suite, and every mistake sits there until you happen to notice it.
224
225If you give it something that comes back pass or fail, Claude can close that loop itself. It makes the change, runs the check, and if something broke it reads the output and fixes it before running the check again.
226
227> [!TIP]
228>
229> Give Claude something it can run that comes back pass or fail. Once it has that, it can keep going on its own and you don't have to watch.
230
231The check can be almost anything, as long as Claude can read the result:
232
233* A test file
234* A build's exit code
235* A linter
236* A script that diffs output against a fixture
237* A [browser screenshot](https://code.claude.com/docs/en/chrome.md) next to the mockup
238
239If your repo already has one of these, the single most useful line in your `CLAUDE.md` is the command that runs it.
240
241How strict you make the check is up to you. The options go from Claude deciding for itself all the way to Claude Code enforcing it:
242
243* In the prompt: `run the auth tests after, and keep going until they pass`. Claude decides for itself when it's satisfied. This works for any task, today, with no setup.
244* As a goal: [`/goal all tests in tests/auth pass and lint is clean`](https://code.claude.com/docs/en/goal) sets a condition that a separate model checks against the conversation after every turn, and Claude keeps going until it's met. You rarely need this in the session yourself. It matters for long background runs, where Claude sometimes ends a turn with a progress summary while items are still open, and the goal sends it back.
245* As a Stop hook: a [`Stop` hook](https://code.claude.com/docs/en/hooks#stop) runs your script whenever Claude tries to end its turn, and sends Claude back to work if the script exits with code 2. This one is enforced by Claude Code (the harness), so the turn doesn't end until the typecheck passes or the [block limit](https://code.claude.com/docs/en/hooks.md#stop-input) is reached. There's an [example further down](#enforce-the-check-with-a-stop-hook).
246* By someone who didn't write the code: in the terminal, [`/code-review`](https://code.claude.com/docs/en/code-review-local) reviews the diff in a fresh subagent that never saw your conversation. It isn't swayed by the reasoning that produced the code.
247
248Whichever option you use, ask Claude for *evidence*: the command it ran and its output, or the screenshot. "All tests pass" on its own tells you very little, and reading the output is faster than rerunning the check yourself. For a session you weren't watching, it's also the only evidence you have.
249
250> [!TIP]
251>
252> Once Claude says it's done, you can also run [`/verify`](https://code.claude.com/docs/en/skills#run-and-verify-your-app) in the session, which has Claude build and run the app and look at the result. That catches the kind of problem that tests and typechecks miss.
253
254### Review against your spec
255
256If you'd rather have the review check the work against your plan than hunt for bugs in general, write the review prompt yourself:
257
258```text theme={null}
259use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style
260```
261
262> [!NOTE]
263>
264> Don't drop the `skip style` part of that prompt. A reviewer that's asked to find problems will always find *something*. If you fix every finding, you end up with extra abstraction layers and tests for cases that can't happen.
265
266### Enforce the check with a Stop hook
267
268The `Stop` hook version of the typecheck rule is a few lines in `.claude/settings.json`. Exit code 2 is what blocks the stop. Whatever the command prints to stderr goes back to Claude as the reason it can't finish yet, which is why the compiler output is redirected there:
269
270```json .claude/settings.json theme={null}
271{
272 "hooks": {
273 "Stop": [
274 {
275 "hooks": [
276 { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
277 ]
278 }
279 ]
280 }
281}
282```
283
284To see it work, ask Claude for a change that breaks a type: instead of finishing, it gets the compiler errors back and keeps going until `tsc` passes. If the hook blocks [eight stops in a row](https://code.claude.com/docs/en/hooks.md#stop-input) with no tool call between them, Claude Code overrides the next block and ends the turn. To raise the cap, set [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](https://code.claude.com/docs/en/env-vars).
285
286## Enforce the rules that can't have exceptions
287
288> [!TIP]
289>
290> If something has to happen every time, make it a hook, a deny rule, or a managed setting. `CLAUDE.md` is for guidelines, and Claude is allowed to decide a guideline doesn't apply.
291
292Take three rules you might have in `CLAUDE.md` today: `Never read .env`, `Always run the formatter after editing`, `Don't touch the migrations folder`. Claude will follow these almost every time. For the few where "almost" isn't good enough, move them out of `CLAUDE.md` and into configuration that Claude Code (the harness) applies itself. From then on, the outcome doesn't depend on what the model remembers or decides.
293
294### Enforce steps with hooks
295
296[Hooks](https://code.claude.com/docs/en/hooks-guide.md) run something of yours at fixed points in Claude's loop: before or after a tool call, when Claude tries to stop, when a session starts, and so on. That something can be:
297
298* A shell command (the usual case)
299* A POST to an HTTP endpoint
300* A tool call on one of your MCP servers
301* A [`prompt` or `agent` hook](https://code.claude.com/docs/en/hooks#hook-handler-fields), which lets a model decide
302
303A `prompt` or `agent` hook asks *another model* to decide, so it isn't deterministic either. For real enforcement, use a `command` or `http` hook, and add [`onFailure: "block"`](https://code.claude.com/docs/en/hooks#block-the-action-when-a-hook-fails) if the action should also be stopped when the hook itself crashes or times out. For a hook that scans commits for secrets, say, you'd rather block the commit than let it through unscanned while the scanner is down.
304
305Here's the formatter rule as a `PostToolUse` hook. It runs after every `Edit` or `Write`, and whether Claude remembers the rule no longer matters, because Claude isn't the one running it:
306
307```json .claude/settings.json theme={null}
308{
309 "hooks": {
310 "PostToolUse": [
311 {
312 "matcher": "Edit|Write",
313 "hooks": [
314 { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
315 ]
316 }
317 ]
318 }
319}
320```
321
322To check the hook, ask Claude to add a badly indented line to a file Prettier formats. The saved file comes back with the indentation fixed.
323
324The migrations rule becomes a [`PreToolUse` hook](https://code.claude.com/docs/en/hooks-guide#block-edits-to-protected-files) that exits with code 2 for any path under `migrations/`. You don't have to write it yourself: `write a hook that blocks edits to the migrations folder` works as a prompt, and `/hooks` shows the result. Don't overdo it, though: a hook is for a rule with *zero* exceptions, and `Prefer named exports` has plenty, so that one stays in `CLAUDE.md`.
325
326### Limit access with permission rules and the sandbox
327
328[Permission rules](https://code.claude.com/docs/en/permissions.md) decide what Claude is allowed to run, read, and fetch. `deny` rules hold in every permission mode, including auto and `bypassPermissions`, which is exactly why the `.env` rule belongs there:
329
330```json .claude/settings.json theme={null}
331{
332 "permissions": {
333 "allow": ["Bash(pnpm tsc --noEmit)"],
334 "ask": ["Bash(git push *)"],
335 "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
336 }
337}
338```
339
340With this saved, asking Claude what's in `.env` fails, through the `Read` tool and through `cat .env` alike.
341
342Rules match tool calls, not intent, so it's worth knowing where the edges are:
343
344* The `Read` rule *does* catch `cat .env`, because Claude Code recognizes the [common file-reading commands](https://code.claude.com/docs/en/permissions.md#read-and-edit).
345* It won't catch a script that opens the file.
346* A `WebFetch` deny rule for a domain does nothing about `curl` to that same domain, unless the sandbox is on.
347
348For an OS-level limit on filesystem or network access, turn on the [sandbox](https://code.claude.com/docs/en/sandboxing.md) with `/sandbox` in a session. It confines Claude's shell commands on macOS, Linux, and WSL2 and [picks up your `Read` deny rules and `WebFetch(domain:...)` rules](https://code.claude.com/docs/en/sandboxing#permission-rules) too, so for anything security-related you want both.
349
350By default Claude can still ask to retry a blocked command outside the sandbox, and that request goes through the normal permission flow. [Strict sandbox mode](https://code.claude.com/docs/en/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode), in the `/sandbox` **Overrides** tab, turns that retry off.
351
352> [!WARNING]
353>
354> Auto mode is a classifier model judging each action rather than a hard rule. It's good at that, but like any judgment call it can be wrong. You can also tune what it treats as risky, and your org can turn it off entirely, so your "never" rules belong in deny rules or hooks.
355
356### Choose who a rule applies to
357
358Where a rule lives decides who it applies to:
359
360* `.claude/settings.local.json` and `~/.claude/settings.json` are yours alone. When you select **Yes, and don't ask again** for a command, Claude Code saves that rule to the local file.
361* `.claude/settings.json` and the hooks in it belong to the repo. Once you commit them, they apply to everyone who works in the repo. Its deny rules apply right away. Its `allow` rules wait until each person accepts the [trust dialog](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder, and [workspace trust](https://code.claude.com/docs/en/hooks.md#workspace-trust) also decides when its hooks start running on their machine.
362* [Managed settings](https://code.claude.com/docs/en/managed-settings.md) belong to the organization. They come from the admin console, MDM, or a `managed-settings.json` file, and no personal settings file can override them, which makes them the only place for a security team's policy. If you are the person who sets them, see [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md).
363
364Whatever the scope, keep the enforced set small. Every hook and deny rule will occasionally fire when it shouldn't, and someone has to maintain each one. If you ever find yourself at forty of them, most are probably preferences that Claude could have weighed on its own.
365
366## Change a default
367
368> [!TIP]
369>
370> The defaults are good enough to leave alone until a task costs more time, tokens, or interruptions than it should. When that happens, run `/usage` in the session to see where it went.
371
372A new session already makes a handful of decisions for you:
373
374* Interactive terminal and VS Code sessions start in auto mode.
375* It runs [Claude Opus 5.5 at medium effort](https://code.claude.com/docs/en/model-config.md#default-model-setting) on most plans and providers.
376* It delegates work to subagents when it sees a reason to.
377* It compacts the conversation as it grows.
378
379Most of the time you never think about these. When a task does cost more than it should, one of these four is usually why.
380
381### Change the permission mode
382
383Both ends of the permission range have a cost:
384
385* **Manual mode**: you approve every edit and every command that isn't read-only yourself. Safe, but after the tenth prompt you start approving without reading, and nothing moves while you're away from the keyboard.
386* **`bypassPermissions`**: approves everything your deny and ask rules don't cover, which only makes sense in a disposable container.
387
388[Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) sits between the two, and it's what interactive terminal and VS Code sessions [start in](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in). Claude works without stopping for routine approvals, and a separate classifier model checks actions in [a fixed order](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions) before they run. It concentrates on [the things you'd want a person to stop](https://code.claude.com/docs/en/permission-modes.md#what-the-classifier-blocks-by-default):
389
390* `curl | bash`
391* Production deploys and migrations
392* Force pushes over other people's work
393* Sensitive data sent to external endpoints
394* Actions that look driven by content Claude read rather than by you
395
396When it does block something, you get a notification and the action shows up under **Recently denied** in `/permissions`, where you can retry it with a manual approval. After [three blocks in a row](https://code.claude.com/docs/en/permission-modes.md#when-auto-mode-falls-back) (or twenty in total), auto mode pauses and goes back to asking you.
397
398None of this replaces your deterministic controls, because it runs *after* them. Deny and ask rules and `PreToolUse` hooks apply before the classifier sees anything, so a deny rule blocks in auto mode exactly like it does everywhere else. The sandbox still confines the [shell commands it wraps](https://code.claude.com/docs/en/sandboxing.md#what-runs-outside-the-sandbox).
399
400> [!NOTE]
401>
402> You can also say `don't push until I've reviewed` in the conversation, and the classifier [treats that as a block signal](https://code.claude.com/docs/en/permission-modes.md#boundaries-you-state-in-conversation). It's still a model reading the transcript, and the sentence can get lost when the conversation compacts, so anything that matters belongs in a deny rule.
403
404The opposite problem is the classifier repeatedly stopping something that's routine in your setup. Rather than approving it manually every time, add it to `autoMode.allow` or describe your trusted infrastructure in the [auto mode configuration](https://code.claude.com/docs/en/auto-mode-config.md). It's plain English rather than patterns, and [`/auto-mode-setup`](https://code.claude.com/docs/en/auto-mode-config#generate-environment-entries) can draft the `environment` part for you from your project and recent sessions:
405
406```json ~/.claude/settings.json theme={null}
407{
408 "autoMode": {
409 "environment": [
410 "$defaults",
411 "Source control: github.com/example-org and every repo under it",
412 "Trusted internal domains: *.internal.example.com"
413 ],
414 "allow": [
415 "$defaults",
416 "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
417 ]
418 }
419}
420```
421
422> [!WARNING]
423>
424> Keep `"$defaults"` in every list you set, because without it your entries *replace* that list's built-in rules instead of adding to them. For `environment` and `allow` you'd lose the built-in context and exceptions, and a `soft_deny` list without it drops the built-in blocks on force pushes and production deploys.
425>
426> The `autoMode` block also has to live in `~/.claude/settings.json` rather than the project, because the classifier ignores `autoMode` in project settings.
427
428If you'd rather see every edit and command before it happens, `Shift+Tab` in the session cycles through the permission modes, Manual included, or start with `claude --permission-mode manual` from your shell. And if Manual then asks too often, `/fewer-permission-prompts` scans your recent transcripts for common read-only Bash and MCP calls and adds them to an allowlist in `.claude/settings.json`.
429
430### Change the model and effort
431
432[Effort](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) is the main control for how long Claude thinks, and it replaces most of what people used to do with prompt wording. Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5 default to `medium`, which is plenty for everyday feature work with a clear scope. The times you'd move it, with `/effort` in the session:
433
434* Raise it with `/effort high` or `/effort xhigh` when getting it right depends on cases that are quick to overlook. Think of a bug in code you didn't write, a flaky test, or a schema change where Claude has to find every reader of the old shape. Claude then checks more edge cases and verifies more of its work before answering, which is where the extra time and tokens go.
435* Lower it with `/effort low` when you're going back and forth quickly and reviewing each result anyway: brainstorming, a first sketch, a rename across a few files. Claude gets you a starting point sooner, and since you're steering every step, the extra deliberation wouldn't have changed much besides the wait.
436* Save `max` for a hard problem you want Claude to work through without you, like hunting for a security vulnerability. On ordinary tasks it tends to overthink, so you pay more for an answer that may be no better than `high` would have given you.
437* When only the next message needs it, like one tricky question in the middle of otherwise routine work, put [`ultrathink`](https://code.claude.com/docs/en/model-config#use-ultrathink-for-one-off-deep-reasoning) in that prompt instead of changing the setting.
438
439For the model itself, the default Opus 5.5 handles most coding well and Sonnet costs less on routine work. [Claude Fable 5.1](https://code.claude.com/docs/en/model-config.md#work-with-fable) is there when you select it explicitly with `/model fable`, and Haiku is a good fit for subagents doing simple jobs. [Model configuration](https://code.claude.com/docs/en/model-config.md) has the full list per plan and provider.
440
441### Know what subagents cost
442
443Claude delegates to [subagents](https://code.claude.com/docs/en/sub-agents.md) on its own:
444
445* Broad codebase searches go to the built-in Explore agent.
446* Side tasks get [forked](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) while fork mode is on (the default).
447* The subagents it starts run in the background by default, so your main conversation keeps moving.
448
449You rarely need to ask for any of this, but it helps to know what you're getting and what it costs.
450
451Subagents pay off in these situations:
452
453* Running independent pieces of work at the same time, so the whole task finishes sooner
454* Keeping long output, like a full test run or a wide search, out of your main conversation, where it would otherwise ride along for the rest of the session
455* Getting a reviewer that hasn't seen how the code was written
456* Giving a task fewer tools than the main session has, like a reviewer that can read but not edit
457
458What they cost you is mostly tokens, since every subagent sends its own requests and they count against the same usage as your main conversation. Sometimes it's time as well: a fresh subagent first has to gather context your conversation already had, so it can end up *slower* than doing the task where you are.
459
460And by default it's the same model (or a smaller one) on the same task. You get parallelism or a fresh pair of eyes out of it, but not a smarter answer.
461
462To spend less on them:
463
464* Set [`model: haiku`](https://code.claude.com/docs/en/sub-agents#choose-a-model) in a subagent's definition if its work is simple, like collecting the files that import a module or checking links in the docs. That kind of job doesn't need the bigger model, and Haiku costs a lot less per request.
465* Ask for short summaries back, so twenty results don't fill your context anyway.
466* Check `/usage` to see what share of your usage each subagent type takes, so you can tell which ones are earning their cost.
467* Give a custom subagent in `.claude/agents/` only `tools: Read, Grep, Glob`. Now it's a reviewer that can't edit anything, and that limit is enforced by Claude Code rather than requested in a prompt.
468
469That reviewer is one short file, `.claude/agents/reviewer.md`:
470
471```markdown .claude/agents/reviewer.md theme={null}
280472---
281name: security-reviewer
282description: Reviews code for security vulnerabilities
283tools: Read, Grep, Glob, Bash
284model: opus
473name: reviewer
474description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
475tools: Read, Grep, Glob
285476---
286You are a senior security engineer. Review code for:
287- Injection vulnerabilities (SQL, XSS, command injection)
288- Authentication and authorization flaws
289- Secrets or credentials in code
290- Insecure data handling
291
292Provide specific line references and suggested fixes.
293```
294
295Tell Claude to use subagents explicitly: *"Use a subagent to review this code for security issues."*
296
297### Install plugins
298
299> [!TIP]
300>
301> Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.
302
303[Plugins](https://code.claude.com/docs/en/plugins/overview.md) bundle skills, hooks, subagents, and MCP servers into a single installable unit from the community and Anthropic. If you work with a typed language, install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) to give Claude precise symbol navigation and automatic error detection after edits.
304
305For guidance on choosing between skills, subagents, hooks, and MCP, see [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md#match-features-to-your-goal).
306
307***
308
309## Communicate effectively
310
311Ask Claude the questions you'd ask another engineer, and for larger features have Claude interview you and write a spec before you start implementing.
312
313### Ask codebase questions
314
315> [!TIP]
316>
317> Ask Claude questions you'd ask a senior engineer.
318
319When onboarding to a new codebase, use Claude Code for learning and exploration. You can ask Claude the same sorts of questions you would ask another engineer:
320
321* How does logging work?
322* How do I make a new API endpoint?
323* What does `async move { ... }` do on line 134 of `foo.rs`?
324* What edge cases does `CustomerOnboardingFlowImpl` handle?
325* Why does this code call `foo()` instead of `bar()` on line 333?
326
327Using Claude Code this way is an effective onboarding workflow, improving ramp-up time and reducing load on other engineers. No special prompting required: ask questions directly.
328
329### Let Claude interview you
330
331> [!TIP]
332>
333> For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.
334
335Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs. Replace `[brief description]` with your feature before sending the prompt.
336
337```text wrap theme={null}
338I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
339
340Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
341
342Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
343```
344
345Once the spec is complete, start a fresh session to execute it. The new session has clean context focused entirely on implementation, and you have a written spec to reference.
346
347The most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. Time spent making the spec precise pays off more than time spent watching the implementation.
348
349***
350
351## Manage your session
352
353Conversations are persistent and reversible. Use this to your advantage!
354
355### Course-correct early and often
356
357> [!TIP]
358>
359> Correct Claude as soon as you notice it going off track.
360
361The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.
362
363* **`Esc`**: stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.
364* **`Esc + Esc` or `/rewind`**: press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.
365* **`"Undo that"`**: have Claude revert its changes.
366* **`/clear`**: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.
367
368If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.
369
370### Manage context aggressively
371
372> [!TIP]
373>
374> Run `/clear` between unrelated tasks to reset context.
375
376Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.
377
378During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude.
379
380* Use `/clear` frequently between tasks to reset the context window entirely
381* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions
382* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`
383* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here** or **Summarize up to here**. The first condenses messages from that point forward while keeping earlier context intact; the second condenses earlier messages while keeping recent ones in full. See [the rewind menu's summarize options](https://code.claude.com/docs/en/checkpointing.md#rewind-and-summarize).
384* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization
385* For questions that don't need to stay in context, use [`/btw`](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw). The answer never enters conversation history, so you can check a detail without growing context.
386
387### Use subagents for investigation
388
389> [!TIP]
390>
391> Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.
392
393Since context is your fundamental constraint, use subagents to keep research out of it. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:
394
395```text wrap theme={null}
396Use subagents to investigate how our authentication system handles token
397refresh, and whether we have any existing OAuth utilities I should reuse.
398```
399
400You can also use subagents for verification after Claude implements something. See [Add an adversarial review step](#add-an-adversarial-review-step).
401
402### Rewind with checkpoints
403
404> [!TIP]
405>
406> Every prompt you send that starts a turn creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.
407
408Claude automatically snapshots files before each change so a checkpoint can restore them. Double-tap `Escape` or run `/rewind` to open the rewind menu. You can restore conversation only, restore code only, restore both, or summarize from a selected message. See [Checkpointing](https://code.claude.com/docs/en/checkpointing.md) for details.
409
410Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach. Checkpoints are saved with the conversation, so you can close your terminal, resume the session later, and still rewind.
477You're reviewing code you didn't write. Compare the changed files against the spec you're given,
478check that every requirement is implemented and the listed edge cases have tests,
479and report only the gaps that affect correctness. Skip style.
480```
481
482Ask Claude to `have the reviewer compare the rate limiter against SPEC.md` and the gaps come back into your session, where Claude can fix them.
483
484### Keep cost and context down
485
486With a 1M-token window on most current models and compaction near the top of it, you'll rarely run out of context. You can still *pay* for context you don't need, though. Every request sends the whole conversation, so a session that's collected three unrelated tasks re-reads all three on every turn of the fourth. That's [discounted while the cache is warm](https://code.claude.com/docs/en/costs.md#why-usage-climbs-in-a-long-session) and full price once it expires.
487
488[`/usage`](https://code.claude.com/docs/en/costs) is the first place to look. On Pro, Max, Team, and Enterprise it breaks your usage down by skill, subagent, plugin, and MCP server. It also flags patterns like long context or frequent cache misses once one of them passes 10% of your usage. From there, the usual fixes:
489
490* `/clear` between unrelated tasks. It costs nothing, and it means the next task doesn't keep paying for the previous one's history. `/clear oauth-migration` names the session you're leaving, so you can come back to it later.
491* `/compact` with a focus, like `/compact keep the API changes and the test commands`. On a long session `/compact` is itself a big request, since it reads the whole conversation to summarize it, and even more so once the cache has expired.
492* Keep an eye on background work: a `/loop`, a goal's check after every turn, and Claude's own subagents all keep sending requests while you aren't typing.
493
494> [!NOTE]
495>
496> The [prompt cache](https://code.claude.com/docs/en/prompt-caching.md) lasts about an hour on a subscription and five minutes on an API key, cloud provider, or usage credits. Subagents get five minutes unless you change it.
497>
498> On the one-hour cache, a session past about 200K tokens that sits idle is compacted shortly before the cache expires, so after lunch you continue from a summary. If you don't need the history at all, a fresh session still costs less.
499
500## Steer the session
501
502> [!TIP]
503>
504> Watch the first minute, press `Esc` the moment Claude drifts, and after two failed corrections run `/clear` and write a better prompt instead of a third.
505
506No amount of configuration replaces watching the first minute and stepping in when Claude heads somewhere you didn't intend. There are only a few controls for that, and they're worth knowing by heart:
507
508* `Esc` stops Claude mid-action and keeps everything up to that point, so you can redirect without losing work.
509* `/rewind`, or `Esc` twice on an empty prompt, opens the [rewind menu](https://code.claude.com/docs/en/checkpointing.md#rewind-and-summarize), where you roll the code, the conversation, or both back to an earlier prompt. That makes it low-risk to try the bolder approach first and rewind if it doesn't work out. The same menu can also summarize part of the conversation when it has gone stale.
510* `/clear` starts over. If you've corrected the same thing twice and it's still wrong, a third correction mostly adds to a conversation that already contains two failed attempts for Claude to keep re-reading. `/clear` plus one new prompt that folds in what you learned works better almost every time.
411511
412512> [!WARNING]
413513>
414> Checkpoints only track changes made through Claude's file editing tools. Changes made through Bash commands or external processes are not captured. This isn't a replacement for git.
415
416### Resume conversations
417
418> [!TIP]
419>
420> Name sessions with `/rename` and treat them like branches: each workstream gets its own persistent context.
421
422Claude Code saves conversations locally, so when a task spans multiple sittings you don't have to re-explain the context. Run [`claude --continue`](https://code.claude.com/docs/en/sessions#resume-a-session) to pick up where you left off, or `claude --resume` to choose from a list. Give sessions descriptive names like `oauth-migration` so you can find them later. See [Manage sessions](https://code.claude.com/docs/en/sessions.md) for the full set of resume, branch, and naming controls.
423
424***
425
426## Automate and scale
427
428Once you're effective with one Claude, multiply your output with parallel sessions, non-interactive mode, and fan-out patterns.
429
430### Run non-interactive mode
431
432> [!TIP]
433>
434> Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json --verbose` for streaming JSON output.
435
436With `claude -p "your prompt"`, you can run Claude non-interactively, without an interactive prompt. The run still creates a resumable session unless you pass `--no-session-persistence`. [Non-interactive mode](https://code.claude.com/docs/en/headless.md) is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.
437
438```bash theme={null}
439# One-off queries
440claude -p "Explain what this project does"
441
442# Structured output for scripts
443claude -p "List all API endpoints" --output-format json
444
445# Streaming for real-time processing
446claude -p "Analyze this log file" --output-format stream-json --verbose
447```
448
449The first command prints plain text. The `json` format returns a single JSON object with a `result` field. The `stream-json` format prints one JSON object per line, starting with an init event.
450
451### Run multiple Claude sessions
452
453> [!TIP]
454>
455> Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.
456
457Pick the parallel approach that fits how much coordination you want to do yourself, and add messaging when the sessions need to pass findings between them:
458
459* [Worktrees](https://code.claude.com/docs/en/worktrees.md): run separate CLI sessions in isolated git checkouts so edits don't collide
460* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): let the sessions you run yourself pass findings to each other
461* [Desktop app](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions): manage multiple local sessions visually, optionally each in its own worktree
462* [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md): run sessions on Anthropic-managed infrastructure by default
463* [Agent view](https://code.claude.com/docs/en/agent-view.md): research preview. Run `claude agents` to dispatch sessions that keep running in the background and watch them from one screen
464* [Agent teams](https://code.claude.com/docs/en/agent-teams.md): experimental and disabled by default. Automated coordination of multiple sessions with shared tasks, messaging, and a team lead
465
466Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.
467
468For example, use a Writer/Reviewer pattern:
469
470| Session A (Writer) | Session B (Reviewer) |
471| - | - |
472| `Implement a rate limiter for our API endpoints` | |
473| | `Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.` |
474| `Here's the review feedback: [Session B output]. Address these issues.` | |
475
476You can do something similar with tests: have one Claude write tests, then another write code to pass them.
477
478### Fan out across files
479
480> [!TIP]
481>
482> Loop through tasks calling `claude -p` for each. Use `--allowedTools` to pre-approve tools for batch operations.
483
484For large migrations or analyses, you can distribute work across many parallel Claude invocations. Run [`/batch <instruction>`](https://code.claude.com/docs/en/commands#all-commands) to have Claude split the change across 5 to 30 subagents. Each subagent works in its own worktree. To drive the fan-out from your own script instead, loop over `claude -p`:
485
486**1. Generate a task list**
487
488Have Claude write the list of files that need migrating to a file, so the loop in the next step can read it, with a prompt like `list all 2,000 Python files that need migrating and save the list to files.txt`
489
490**2. Write a script to loop through the list**
514> Checkpoints cover the files Claude edited with its own file tools in your main conversation, so a file that only a Bash command touched [isn't restored](https://code.claude.com/docs/en/checkpointing.md#bash-command-changes-not-tracked). They work alongside git rather than replacing it.
515
516Two smaller ones: [`/btw`](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw) answers a quick question without adding anything to the history. And for work that spans several days, `/rename oauth-migration` in the session names it, so that [`claude --resume oauth-migration`](https://code.claude.com/docs/en/sessions#resume-by-session-id-or-name) from your shell picks it back up later, checkpoints included. `claude --continue` resumes the most recent one.
517
518## Let Claude run without you
519
520> [!TIP]
521>
522> Before a run goes unattended, make sure it knows what done looks like, can check its own work, and can only touch what it should. Give it a cap on turns or spend, and have a person approve the result at the end.
523
524Everything on this page matters a little more once you're not around to catch mistakes. While you're watching, Claude missing some piece of context isn't a big deal: you notice within a message or two and tell it. In a run you started before going to bed, nobody tells it, and you find out the next morning that it spent the whole night building on the wrong assumption.
525
526Before you leave a task running on its own, it's worth going through these five questions with that specific task in mind:
527
5281. Does it know what done looks like? A goal condition, a spec file, or a failing test it has to turn green.
5292. Can it check its own work? The test suite, a `Stop` hook, some kind of review step.
5303. What's it allowed to touch? Permission rules, `dontAsk`, the sandbox, a worktree, the one branch it may push to.
5314. What stops it? `--max-turns`, `--max-budget-usd`, a spend limit.
5325. Where does the result go, and who signs off? A PR, a comment, or a summary, and then a person approving the merge, the deploy, or anything else you can't take back.
533
534Once it's going, Claude will carry a long task through on its own. The parts that stay with you are starting it, deciding what "done" means this time, and approving the merge at the end.
535
536### Run Claude from a script
537
538[`claude -p "prompt"`](https://code.claude.com/docs/en/headless) runs once and exits, which is how Claude Code ends up in CI jobs, git hooks, and shell loops.
539
540In a script you'll almost always want a few more flags:
541
542* [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode) skips hooks, skills, plugins, MCP servers, and `CLAUDE.md` files, the repo's as well as the machine's, so the run does the same thing wherever it runs. It also never touches your claude.ai login: auth comes from `ANTHROPIC_API_KEY`, an `apiKeyHelper` in the file you pass with `--settings`, or your cloud provider's credentials.
543* `--append-system-prompt`, `--mcp-config`, and `--settings` pass in whatever the run *does* need, explicitly.
544* `--allowedTools` pre-approves its tools, and [`--permission-mode dontAsk`](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) refuses anything else that would have prompted.
545* `--output-format json` gives you a single result object to parse, and `stream-json` with `--verbose` streams events as they happen.
546
547Put together, that looks like this:
491548
492549```bash theme={null}
493550for file in $(cat files.txt); do
494 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
495 --allowedTools "Edit,Bash(git commit *)" \
496 --permission-mode dontAsk
551 claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
552 --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
553 --permission-mode dontAsk \
554 --max-turns 20
497555done
498556```
499557
500**3. Test on a few files, then run on all of them**
501
502Refine your prompt based on what goes wrong with the first 2-3 files, then run on the full set. The `--allowedTools` flag pre-approves the tools the migration needs. [`--permission-mode dontAsk`](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) denies anything else that would need approval, which matters when you're running unattended, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve some of those calls.
503
504You can also integrate Claude into existing data/processing pipelines:
505
506```bash theme={null}
507claude -p "<your prompt>" --output-format json | your_command
508```
509
510### Run autonomously with auto mode
511
512For uninterrupted execution with background safety checks, use [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode). A classifier model reviews commands before they run, blocking scope escalation, unknown infrastructure, and hostile-content-driven actions while letting routine work proceed without prompts.
513
514```bash theme={null}
515claude --permission-mode auto -p "fix all lint errors"
516```
517
518When the classifier repeatedly blocks actions in a non-interactive run with the `-p` flag, Claude Code doesn't stop the run. See [when auto mode falls back](https://code.claude.com/docs/en/permission-modes.md#when-auto-mode-falls-back) for what happens instead and for the thresholds.
519
520### Add an adversarial review step
521
522> [!TIP]
523>
524> Before treating a task as done, have a subagent review the diff in a fresh context and report gaps.
525
526The longer Claude works unattended, the more an independent check matters before you count the work as done. A reviewer running in a fresh [subagent](https://code.claude.com/docs/en/sub-agents.md) context sees only the diff and the criteria you give it, not the reasoning that produced the change, so it evaluates the result on its own terms.
527
528For a correctness check, run the bundled [`/code-review` skill](https://code.claude.com/docs/en/commands), which reviews the current diff for bugs in a fresh subagent and returns findings to the session. To check the diff against your plan instead, write the review prompt yourself. Name the work to check, the plan to check it against, and what counts as a finding:
529
530```text wrap theme={null}
531Use a subagent to review the rate limiter diff against PLAN.md. Check that
532every requirement is implemented, the listed edge cases have tests, and
533nothing outside the task's scope changed. Report gaps, not style preferences.
534```
535
536Because the reviewer runs as a subagent, the implementing session receives the gaps directly and can fix them and re-review without you copying findings between windows.
537
538A reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. Chasing every finding leads to over-engineering: extra abstraction layers, defensive code, and tests for cases that can't happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional.
539
540***
541
542## Avoid common failure patterns
543
544These are common mistakes. Recognizing them early saves time:
545
546* **The kitchen sink session.** You start with one task, then ask Claude something unrelated, then go back to the first task. Context is full of irrelevant information.
547 > **Fix**: `/clear` between unrelated tasks.
548* **Correcting over and over.** Claude does something wrong, you correct it, it's still wrong, you correct again. Context is polluted with failed approaches.
549 > **Fix**: After two failed corrections, `/clear` and write a better initial prompt incorporating what you learned.
550* **The over-specified CLAUDE.md.** If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.
551 > **Fix**: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.
552* **The trust-then-verify gap.** Claude produces a plausible-looking implementation that doesn't handle edge cases.
553 > **Fix**: Always provide verification (tests, scripts, screenshots). If you can't verify it, don't ship it.
554* **The infinite exploration.** You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context.
555 > **Fix**: Scope investigations narrowly or use subagents so the exploration doesn't consume your main context.
556
557***
558
559## Develop your intuition
560
561The patterns in this guide aren't set in stone. They're starting points that work well in general, but might not be optimal for every situation.
562
563Sometimes you *should* let context accumulate because you're deep in one complex problem and the history is valuable. Sometimes you should skip planning and let Claude figure it out because the task is exploratory. Sometimes a vague prompt is exactly right because you want to see how Claude interprets the problem before constraining it.
564
565Pay attention to what works. When Claude produces great output, notice what you did: the prompt structure, the context you provided, the mode you were in. When Claude struggles, ask why. Was the context too noisy? The prompt too vague? The task too big for one pass?
566
567Over time, you'll develop intuition that no guide can capture. You'll know when to be specific and when to be open-ended, when to plan and when to explore, when to clear context and when to let it accumulate.
558When a run finishes, Claude replies `OK` or `FAIL`, and a run that hits the turn limit exits with an error instead. Try it on three files first, see what goes wrong, fix the prompt, then run the rest.
559
560Auto mode works with `-p` too if you pass `--permission-mode auto`. In a non-interactive run, a classifier block denies that one action and Claude carries on, and repeated blocks don't pause the run the way they do in a terminal. Read [how the thresholds apply there](https://code.claude.com/docs/en/permission-modes.md#repeated-block-thresholds) before you rely on it.
561
562### Start runs on a schedule or an event
563
564Once a run is going, Claude can handle the rest by itself. The one thing it can't do is decide to *start*, so something has to: you, a timer, or an event like a failed CI check or a new PR.
565
566Inside an open session that's [`/loop`](https://code.claude.com/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop), which repeats a prompt on an interval:
567
568```text theme={null}
569/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push
570```
571
572Each run is another turn in the same session, so don't leave one going in a long conversation. For anything that should happen while your laptop is closed, [`/schedule`](https://code.claude.com/docs/en/routines#create-from-the-cli) sets up a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) that runs on a timer. It needs a claude.ai login rather than an API key. You can add a GitHub-event trigger by asking Claude, or an API trigger at [claude.ai/code/routines](https://claude.ai/code/routines).
573
574> [!WARNING]
575>
576> Before you leave a cloud scheduled task running, protect `main` with a [GitHub branch rule the task can't bypass](https://code.claude.com/docs/en/routines.md#repositories-and-branch-permissions). And watch the first few runs of anything new before trusting it unattended.
577
578### Run sessions in parallel
579
580When you have separate pieces of work going at once, give each its own checkout so the edits can't collide. [`claude -w feature-auth`](https://code.claude.com/docs/en/worktrees#start-claude-in-a-worktree) starts a session in a new worktree, the [desktop app](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions) runs several of these side by side, and [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) run them in the cloud instead of on your machine.
581
582A worktree is a fresh checkout, which means gitignored files like `.env` aren't there and dependencies aren't installed. For the first, list the gitignored files you need in a [`.worktreeinclude`](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees) at the repo root (same syntax as `.gitignore`) and Claude Code copies them into every worktree it creates:
583
584```text .worktreeinclude theme={null}
585.env
586.env.local
587config/dev-credentials.json
588```
589
590Keep it to small files: it copies rather than links, so `node_modules` in there would mean a full copy per worktree. For large directories there's the [`worktree.symlinkDirectories`](https://code.claude.com/docs/en/settings-reference#worktree-symlinkdirectories) setting, or keep the install command in `CLAUDE.md` so Claude runs it whenever it starts in a new checkout.
591
592You rarely have to clean any of this up yourself:
593
594* When you exit an unnamed worktree session, Claude Code [removes the worktree](https://code.claude.com/docs/en/worktrees.md#clean-up-worktrees) if there's nothing in it. For a named session, or one with changes, it asks what to do.
595* Subagent worktrees disappear when the subagent finishes without changes.
596* Subagent and background-session worktrees that do get left behind are swept once they're older than `cleanupPeriodDays` and hold no work.
597
598> [!NOTE]
599>
600> A `claude -p --worktree` run is one you clean up yourself, since it exits without asking. Remove those with `git worktree remove <path>`, and if git refuses because the worktree is locked, `git worktree unlock <path>` first.
601
602For one big mechanical change across many files, [`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/en/commands) splits the work into 5 to 30 units and shows you the plan. Then it runs each unit in its own worktree and opens a PR for it. From your shell, [`claude agents`](https://code.claude.com/docs/en/agent-view) (still a research preview) gives you one screen for everything running in the background on your machine.
603
604A second session is also the easiest independent reviewer you can get. One session writes the rate limiter, another reviews `@src/middleware/rateLimiter.ts` without having watched it being written, and you paste the findings back into the first. Same idea as `/code-review`, with you carrying the messages.
605
606## What you can stop doing
607
608Every one of these was good advice when it was written. Most were workarounds for something the model couldn't reliably do yet, and the models have since caught up. If a few are still habits, here's why it's safe to drop them.
609
610| The old advice | Why it's gone |
611| :- | :- |
612| The context window is your main constraint, manage it aggressively | Most current models have a 1M-token window and compaction happens on its own, so running out is rare. `/clear` between tasks is still worth doing, because a focused context gets you better answers and costs less. |
613| Add IMPORTANT or ALL CAPS to instructions Claude keeps missing | Older models sometimes needed the emphasis. Current ones follow a plainly worded line, and piling on emphasis mostly makes Claude over-apply the rule. If it's a rule that can't bend, turn it into a hook or a deny rule. If the line is getting lost in a long file, the file needs to be shorter. |
614| Use subagents to protect your context window | Running out of context is rarely the problem anymore. Subagents are still great for parallel work, keeping noisy output out of your way, and independent review, but each of those costs extra tokens. |
615| Delegate to a subagent for a better answer | Handing the same task to a subagent doesn't make the answer any better. A fresh reviewer does help, because it hasn't seen your reasoning, which is a different thing from delegating. |
616| `think hard`, `think harder`, `be thorough` in the prompt | Effort is the control for that. Those phrases are ordinary prompt text that nudges Claude within its effort setting rather than keywords that raise it. `ultrathink` still works: it asks for deeper reasoning on that single turn without touching your effort setting. |
617| Tell Claude to keep going, loop until done, don't be lazy | Current models usually carry on through an agreed task without being told, and lines like that are more likely to cause over-work than fix a stall. Giving Claude a check to pass is different, and still worth doing. If a run does stop short, say `continue`, and for runs nobody's watching, `/goal` or a `Stop` hook enforces it. |
618| Describe your architecture and file layout in `CLAUDE.md` | Claude reads the repo itself. Only write down what isn't in there. |
619
620If any other advice on this page ever starts to feel like busywork, that's probably a sign it belongs in this table too.
568621
569622## Related resources
570623
571* [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md): the agentic loop, tools, and context management
572* [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md): skills, hooks, MCP, subagents, and plugins
573* [Common workflows](https://code.claude.com/docs/en/common-workflows.md): step-by-step recipes for debugging, testing, PRs, and more
574* [CLAUDE.md](https://code.claude.com/docs/en/memory.md): store project conventions and persistent context
624* [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md): the loop, the tools, and what loads at startup
625* [Explore the context window](https://code.claude.com/docs/en/context-window.md): what uses space in a session and when it loads
626* [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md): the choice between skills, hooks, MCP, subagents, and plugins
627* [Choose a permission mode](https://code.claude.com/docs/en/permission-modes.md) and [Configure permissions](https://code.claude.com/docs/en/permissions.md)
628* [Manage costs effectively](https://code.claude.com/docs/en/costs.md)
629* [Run Claude Code programmatically](https://code.claude.com/docs/en/headless.md) and [Automate work with cloud scheduled tasks](https://code.claude.com/docs/en/routines.md)
630* For team leads and admins: [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md)
575631
No line in this hunk matches that.