4 4
5# Best practices for Claude Code5# Best practices for Claude Code
6 6
7> Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.7> 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.
8 8
9Claude 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.9Claude 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.
10 10
11This 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.11For example:
12 12
13But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand.13* 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.
14* To keep your main conversation focused while independent work happens in parallel, Claude delegates to subagents and checks in only when it has to.
15* To keep a long session going without you managing it, your conversation is compacted automatically before the context window fills.
14 16
15This 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).17This 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:
16 18
17***19* A deploy process that lives in someone's head
20* A file that must never be read
21* A check that has to pass before anything counts as done
22* A budget you need to stay under
18 23
19Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.24No default can know those things about your project, so this is where a small amount of setup on your side pays off.
20 25
21Claude'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.26When a session doesn't go the way you expected, it's almost always one of these:
22 27
23This 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.28* 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).
29* 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).
30* 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).
31* 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).
24 32
25***33[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.
26 34
27## Give Claude a way to verify its work35> [!NOTE]
28
29> [!TIP]
30>36>
31> 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.37> 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).
32 38
33Claude 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.39## Deterministic and non-deterministic instructions
34 40
35The 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.41Every instruction you give Claude Code is one of these:
36 42
37| Strategy | Before | After |431. 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.
38| - | - | - |442. 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.
39| **Provide verification criteria** | *"implement a function that validates email addresses"* | *"write a validateEmail function. example test cases: [user@example.com](mailto:user@example.com) is true, invalid is false, [user@.com](mailto:user@.com) is false. run the tests after implementing"* |
40| **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"* |
41| **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"* |
42 45
43Once the check exists, decide how hard it gates the stop:46Most things in Claude Code come in both forms:
44 47
45* **In one prompt**: ask Claude to run the check and iterate in the same message, as in the table above.48| | Non-deterministic (Claude decides) | Deterministic (Claude Code enforces) |
46* **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).49| :- | :- | :- |
47* **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.50| What to do | Your prompt, `CLAUDE.md`, skills Claude picks up itself | Hooks, and which skills only you can start |
48* **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.51| 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 |
52| When it's done | A request for evidence, `/goal`, `/code-review` | Tests, typecheck, a `Stop` hook, CI |
53| 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 |
54| Who has the last word | Claude's summary of what it did | Branch protection, a person who approves the merge |
49 55
50Each 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.56Most 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.
51 57
52Have 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.58The 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:
53 59
54***60* Never edit the generated client in `src/gen/`
61* Always run the license-header script after creating a file
55 62
56## Explore first, then plan, then code63You 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.
57 64
58> [!TIP]65> [!TIP]
59>66>
60> Separate research and planning from implementation to avoid solving the wrong problem.67> 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.
61 68
62Letting 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.69## Tell Claude what it can't see
63 70
64The recommended workflow has four phases:71> [!TIP]
72>
73> Only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session.
65 74
66**1. Explore**75Claude 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.
67 76
68Enter 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.77What it can't find is the information that was never in the repo:
69 78
70```txt title="claude (plan mode)" wrap theme={null}79* A decision your team made in a meeting
71read /src/auth and understand how we handle sessions and login.80* A deploy process that lives in one person's head
72also look at how we manage environment variables for secrets.81* The environment variable your integration tests need
73```
74 82
75**2. Plan**83There'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.
76 84
77Ask Claude to create a detailed implementation plan.85A good test before you write anything down for Claude:
78 86
79```txt title="claude (plan mode)" wrap theme={null}871. Could it find this by reading the code?
80I want to add Google OAuth. What files need to change?882. Would it actually go and look?
81What's the session flow? Create a plan.
82```
83 89
84Press `Ctrl+G` to open the plan in your text editor for direct editing before Claude proceeds.90If both are yes, leave it out.
85 91
86**3. Implement**92### Write a specific prompt
87 93
88Switch out of plan mode by approving the plan or pressing `Shift+Tab`, then let Claude code, verifying against its plan.94A 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.
89 95
90```txt title="claude" wrap theme={null}96The 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.
91implement the OAuth flow from your plan. write tests for the
92callback handler, run the test suite and fix any failures.
93```
94 97
95**4. Commit**98| Instead of | Try |
99| :- | :- |
100| *"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"* |
101| *"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"* |
96 102
97Ask Claude to commit with a descriptive message and create a PR.103If you already have the thing Claude needs, hand it over instead of describing it:
98 104
99```txt title="claude" wrap theme={null}105* 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.
100commit with a descriptive message and open a PR106* An image: paste the screenshot of the design or the error into the prompt.
101```107* Command output: pipe it in from your shell with `cat error.log | claude -p "what's going on here"`.
102 108
103Plan mode is useful, but also adds overhead.109Phrases 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.
104 110
105For 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.111One 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:
106 112
107Planning 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.113```text theme={null}
114build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout
115```
108 116
109***117That's telling Claude about scope, which only you know, rather than how hard to think.
110 118
111## Provide specific context in your prompts119And 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.
112 120
113> [!TIP]121### Brainstorm with Claude first
114>
115> The more precise your instructions, the fewer corrections you'll need.
116 122
117Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.123When 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:
118 124
119| Strategy | Before | After |125```text theme={null}
120| - | - | - |126I 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.
121| **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."* |127```
122| **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"* |
123| **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."* |
124| **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"* |
125 128
126Vague 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.129Claude 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.
127 130
128### Provide rich content131Once `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).
129 132
130> [!TIP]133### Keep CLAUDE.md short
131>
132> Use `@` to reference files, paste screenshots/images, or pipe data directly.
133 134
134You can provide rich data to Claude in several ways:135Claude 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:
135 136
136* **Reference files with `@`** instead of describing where code lives. Claude reads the file before responding.137* How to confirm work in this repo: the exact test, typecheck, and lint commands, and how to run a single test file
137* **Paste images directly**. Copy/paste or drag and drop images into the prompt.138* 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
138* **Give URLs** for documentation and API references. Use `/permissions` to allowlist frequently used domains.139* Decisions that aren't in the repo: which error helper the team settled on, how deploys work, what needs a migration review
139* **Pipe in data** by running `cat error.log | claude -p "explain this error"` to send file contents directly.140* Anything you've had to correct twice already
140* **Let Claude fetch what it needs**. Tell Claude to pull context itself using Bash commands, MCP tools, or by reading files.
141 141
142***142A `CLAUDE.md` that passes that test stays short:
143 143
144## Configure your environment144```markdown CLAUDE.md theme={null}
145# Commands
146- Install: pnpm install
147- Run one test file: pnpm vitest run path/to/file.test.ts
148- Typecheck: pnpm tsc --noEmit
145 149
146A 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).150# Conventions
151- Use the error helpers in src/lib/errors.ts, never throw raw strings
152- src/legacy/ is still live but don't copy its patterns into new code
147 153
148### Write an effective CLAUDE.md154# Gotchas
155- Integration tests need DATABASE_URL set, see .env.example
156```
149 157
150> [!TIP]158In a session, run `/context` to confirm that Claude loaded the file.
151>
152> Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.
153 159
154CLAUDE.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.160Notice 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.
155 161
156There's no required format for CLAUDE.md files, but keep it short and human-readable. For example:162You don't have to write the file from scratch:
157 163
158```markdown CLAUDE.md theme={null}164* `/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.
159# Code style165* `/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).
160- Use ES modules (import/export) syntax, not CommonJS (require)166* `/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).
161- Destructure imports when possible (eg. import { foo } from 'bar')
162 167
163# Workflow168Your 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.
164- Be sure to typecheck when you're done making a series of code changes
165- Prefer running single tests, and not the whole test suite, for performance
166```
167 169
168Run `/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.170> [!NOTE]
171>
172> 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 173
170Keep 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!174### Scope rules to one part of the codebase
171 175
172| ✅ Include | ❌ Exclude |176If 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| Bash commands Claude can't guess | Anything Claude can figure out by reading code |
175| Code style rules that differ from defaults | Standard language conventions Claude already knows |
176| Testing instructions and preferred test runners | Detailed API documentation (link to docs instead) |
177| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
178| Architectural decisions specific to your project | Long explanations or tutorials |
179| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |
180| Common gotchas or behaviors that aren't self-evident | Self-evident practices like "write clean code" |
181 177
182If 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.178```markdown .claude/rules/api.md theme={null}
179---
180paths:
181 - "src/api/**/*.ts"
182---
183- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
184- Every new endpoint needs an entry in openapi.yaml, CI fails without it
185```
183 186
184If 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.187### Put team procedures in skills
185 188
186CLAUDE.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).189A 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`.
187 190
188### Configure permissions191Skills 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`.
189 192
190> [!TIP]193> [!NOTE]
191>194>
192> 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.195> The `CLAUDE.md` rule applies to skills too: only write down what Claude can't find on its own.
193 196
194With 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.197For 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:
195 198
196In 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:199```markdown .claude/skills/release/SKILL.md theme={null}
200---
201name: release
202description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
203disable-model-invocation: true
204---
2051. Make sure you're on main with a clean tree. If not, stop and ask.
2062. Run `pnpm changeset version` and commit the result.
2073. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
2084. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.
209```
197 210
198* **Permission allowlists**: permit specific tools you know are safe, like `npm run lint` or `git commit`211### Connect the tools Claude needs
199* **Sandboxing**: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries
200 212
201Read 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).213Some 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.
202 214
203### Use CLI tools215For systems without a CLI, there's [MCP](https://code.claude.com/docs/en/mcp.md). You add a server from your shell:
204 216
205> [!TIP]217```bash theme={null}
206>218claude mcp add --transport http notion https://mcp.notion.com/mcp
207> Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.219```
220
221The 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.
222
223And 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.
208 224
209CLI 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.225## Give Claude a check to run
210 226
211Claude 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.`227Claude 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.
212 228
213### Connect MCP servers229If 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.
214 230
215> [!TIP]231> [!TIP]
216>232>
217> 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`.233> 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.
218 234
219With [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.235The check can be almost anything, as long as Claude can read the result:
220 236
221### Set up hooks237* A test file
238* A build's exit code
239* A linter
240* A script that diffs output against a fixture
241* A [browser screenshot](https://code.claude.com/docs/en/chrome.md) next to the mockup
222 242
223> [!TIP]243If your repo already has one of these, the single most useful line in your `CLAUDE.md` is the command that runs it.
224>
225> Use hooks for actions that must happen every time with zero exceptions.
226 244
227[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.245How 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:
228 246
229Claude 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.247* 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.
248* 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.
249* 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).
250* 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.
230 251
231### Create skills252Whichever 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.
232 253
233> [!TIP]254> [!TIP]
234>255>
235> Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.256> 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.
236 257
237[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`.258### Review against your spec
238 259
239Create a skill by adding a directory with a `SKILL.md` to `.claude/skills/`:260If you'd rather have the review check the work against your plan than hunt for bugs in general, write the review prompt yourself:
240 261
241```markdown .claude/skills/api-conventions/SKILL.md theme={null}262```text theme={null}
242name: api-conventions263use 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
243description: REST API design conventions for our services
244# API Conventions
245- Use kebab-case for URL paths
246- Use camelCase for JSON properties
247- Always include pagination for list endpoints
248- Version APIs in the URL path (/v1/, /v2/)
249```264```
250 265
251Skills can also define repeatable workflows you invoke directly:266> [!NOTE]
252 267>
253```markdown .claude/skills/fix-issue/SKILL.md theme={null}268> 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.
254name: fix-issue269
255description: Fix a GitHub issue270### Enforce the check with a Stop hook
256disable-model-invocation: true271
257Analyze and fix the GitHub issue: $ARGUMENTS.272The `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:
258 273
2591. Use `gh issue view` to get the issue details274```json .claude/settings.json theme={null}
2602. Understand the problem described in the issue275{
2613. Search the codebase for relevant files276 "hooks": {
2624. Implement the necessary changes to fix the issue277 "Stop": [
2635. Write and run tests to verify the fix278 {
2646. Ensure code passes linting and type checking279 "hooks": [
2657. Create a descriptive commit message280 { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
2668. Push and create a PR281 ]
282 }
283 ]
284 }
285}
267```286```
268 287
269Run `/fix-issue 1234` to invoke it. Use `disable-model-invocation: true` for workflows with side effects that you want to trigger manually.288To 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).
270 289
271### Create custom subagents290## Enforce the rules that can't have exceptions
272 291
273> [!TIP]292> [!TIP]
274>293>
275> Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.294> 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.
276 295
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.296Take 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.
278 297
279```markdown .claude/agents/security-reviewer.md theme={null}298### Enforce steps with hooks
280name: security-reviewer299
281description: Reviews code for security vulnerabilities300[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:
282tools: Read, Grep, Glob, Bash301
283model: opus302* A shell command (the usual case)
284You are a senior security engineer. Review code for:303* A POST to an HTTP endpoint
285- Injection vulnerabilities (SQL, XSS, command injection)304* A tool call on one of your MCP servers
286- Authentication and authorization flaws305* A [`prompt` or `agent` hook](https://code.claude.com/docs/en/hooks#hook-handler-fields), which lets a model decide
287- Secrets or credentials in code306
288- Insecure data handling307A `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.
308
309Here'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:
289 310
290Provide specific line references and suggested fixes.311```json .claude/settings.json theme={null}
312{
313 "hooks": {
314 "PostToolUse": [
315 {
316 "matcher": "Edit|Write",
317 "hooks": [
318 { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
319 ]
320 }
321 ]
322 }
323}
291```324```
292 325
293Tell Claude to use subagents explicitly: *"Use a subagent to review this code for security issues."*326To 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.
294 327
295### Install plugins328The 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`.
296 329
297> [!TIP]330### Limit access with permission rules and the sandbox
298>
299> Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.
300 331
301[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.332[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:
302 333
303For 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).334```json .claude/settings.json theme={null}
335{
336 "permissions": {
337 "allow": ["Bash(pnpm tsc --noEmit)"],
338 "ask": ["Bash(git push *)"],
339 "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
340 }
341}
342```
304 343
305***344With this saved, asking Claude what's in `.env` fails, through the `Read` tool and through `cat .env` alike.
306 345
307## Communicate effectively346Rules match tool calls, not intent, so it's worth knowing where the edges are:
308 347
309Ask Claude the questions you'd ask another engineer, and for larger features have Claude interview you and write a spec before you start implementing.348* 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).
349* It won't catch a script that opens the file.
350* A `WebFetch` deny rule for a domain does nothing about `curl` to that same domain, unless the sandbox is on.
310 351
311### Ask codebase questions352For 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.
312 353
313> [!TIP]354By 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.
355
356> [!WARNING]
314>357>
315> Ask Claude questions you'd ask a senior engineer.358> 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.
359
360### Choose who a rule applies to
316 361
317When 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:362Where a rule lives decides who it applies to:
318 363
319* How does logging work?364* `.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.
320* How do I make a new API endpoint?365* `.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.
321* What does `async move { ... }` do on line 134 of `foo.rs`?366* [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).
322* What edge cases does `CustomerOnboardingFlowImpl` handle?
323* Why does this code call `foo()` instead of `bar()` on line 333?
324 367
325Using 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.368Whatever 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.
326 369
327### Let Claude interview you370## Change a default
328 371
329> [!TIP]372> [!TIP]
330>373>
331> For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.374> 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.
332 375
333Claude 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.376A new session already makes a handful of decisions for you:
334 377
335```text wrap theme={null}378* Interactive terminal and VS Code sessions start in auto mode.
336I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.379* 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.
380* It delegates work to subagents when it sees a reason to.
381* It compacts the conversation as it grows.
337 382
338Ask 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.383Most of the time you never think about these. When a task does cost more than it should, one of these four is usually why.
339 384
340Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.385### Change the permission mode
341```
342 386
343Once 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.387Both ends of the permission range have a cost:
344 388
345The 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.389* **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.
390* **`bypassPermissions`**: approves everything your deny and ask rules don't cover, which only makes sense in a disposable container.
346 391
347***392[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):
348 393
349## Manage your session394* `curl | bash`
395* Production deploys and migrations
396* Force pushes over other people's work
397* Sensitive data sent to external endpoints
398* Actions that look driven by content Claude read rather than by you
350 399
351Conversations are persistent and reversible. Use this to your advantage!400When 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.
352 401
353### Course-correct early and often402None 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).
354 403
355> [!TIP]404> [!NOTE]
356>405>
357> Correct Claude as soon as you notice it going off track.406> 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.
407
408The 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:
409
410```json ~/.claude/settings.json theme={null}
411{
412 "autoMode": {
413 "environment": [
414 "$defaults",
415 "Source control: github.com/example-org and every repo under it",
416 "Trusted internal domains: *.internal.example.com"
417 ],
418 "allow": [
419 "$defaults",
420 "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
421 ]
422 }
423}
424```
358 425
359The 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.426> [!WARNING]
427>
428> 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.
429>
430> The `autoMode` block also has to live in `~/.claude/settings.json` rather than the project, because the classifier ignores `autoMode` in project settings.
360 431
361* **`Esc`**: stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.432If 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`.
362* **`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.
363* **`"Undo that"`**: have Claude revert its changes.
364* **`/clear`**: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.
365 433
366If 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.434### Change the model and effort
367 435
368### Manage context aggressively436[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:
369 437
370> [!TIP]438* 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.
371>439* 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.
372> Run `/clear` between unrelated tasks to reset context.440* 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.
441* 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.
373 442
374Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.443For 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.
375 444
376During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude.445### Know what subagents cost
377 446
378* Use `/clear` frequently between tasks to reset the context window entirely447Claude delegates to [subagents](https://code.claude.com/docs/en/sub-agents.md) on its own:
379* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions
380* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`
381* 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).
382* 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
383* 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.
384 448
385### Use subagents for investigation449* Broad codebase searches go to the built-in Explore agent.
450* Side tasks get [forked](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) while fork mode is on (the default).
451* The subagents it starts run in the background by default, so your main conversation keeps moving.
386 452
387> [!TIP]453You rarely need to ask for any of this, but it helps to know what you're getting and what it costs.
388>
389> Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.
390 454
391Since 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:455Subagents pay off in these situations:
392 456
393```text wrap theme={null}457* Running independent pieces of work at the same time, so the whole task finishes sooner
394Use subagents to investigate how our authentication system handles token458* 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
395refresh, and whether we have any existing OAuth utilities I should reuse.459* Getting a reviewer that hasn't seen how the code was written
396```460* Giving a task fewer tools than the main session has, like a reviewer that can read but not edit
397 461
398You can also use subagents for verification after Claude implements something. See [Add an adversarial review step](#add-an-adversarial-review-step).462What 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.
399 463
400### Rewind with checkpoints464And 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.
401 465
402> [!TIP]466To spend less on them:
403>
404> Every prompt you send that starts a turn creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.
405 467
406Claude 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.468* 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.
469* Ask for short summaries back, so twenty results don't fill your context anyway.
470* Check `/usage` to see what share of your usage each subagent type takes, so you can tell which ones are earning their cost.
471* 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.
407 472
408Instead 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.473That reviewer is one short file, `.claude/agents/reviewer.md`:
409 474
410> [!WARNING]475```markdown .claude/agents/reviewer.md theme={null}
411>476---
412> 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.477name: reviewer
478description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
479tools: Read, Grep, Glob
480---
481You're reviewing code you didn't write. Compare the changed files against the spec you're given,
482check that every requirement is implemented and the listed edge cases have tests,
483and report only the gaps that affect correctness. Skip style.
484```
413 485
414### Resume conversations486Ask 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.
415 487
416> [!TIP]488### Keep cost and context down
417>
418> Name sessions with `/rename` and treat them like branches: each workstream gets its own persistent context.
419 489
420Claude 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.490With 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.
421 491
422***492[`/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:
423 493
424## Automate and scale494* `/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.
495* `/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.
496* 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.
425 497
426Once you're effective with one Claude, multiply your output with parallel sessions, non-interactive mode, and fan-out patterns.498> [!NOTE]
499>
500> 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.
501>
502> 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.
427 503
428### Run non-interactive mode504## Steer the session
429 505
430> [!TIP]506> [!TIP]
431>507>
432> Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json --verbose` for streaming JSON output.508> 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.
433 509
434With `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.510No 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:
435 511
436```bash theme={null}512* `Esc` stops Claude mid-action and keeps everything up to that point, so you can redirect without losing work.
437# One-off queries513* `/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.
438claude -p "Explain what this project does"514* `/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.
439
440# Structured output for scripts
441claude -p "List all API endpoints" --output-format json
442 515
443# Streaming for real-time processing516> [!WARNING]
444claude -p "Analyze this log file" --output-format stream-json --verbose517>
445```518> 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.
446 519
447The 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.520Two 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.
448 521
449### Run multiple Claude sessions522## Let Claude run without you
450 523
451> [!TIP]524> [!TIP]
452>525>
453> Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.526> 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.
454
455Pick 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:
456 527
457* [Worktrees](https://code.claude.com/docs/en/worktrees.md): run separate CLI sessions in isolated git checkouts so edits don't collide528Everything 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.
458* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): let the sessions you run yourself pass findings to each other
459* [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
460* [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
461* [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
462* [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
463 529
464Beyond 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.530Before you leave a task running on its own, it's worth going through these five questions with that specific task in mind:
465 531
466For example, use a Writer/Reviewer pattern:5321. Does it know what done looks like? A goal condition, a spec file, or a failing test it has to turn green.
5332. Can it check its own work? The test suite, a `Stop` hook, some kind of review step.
5343. What's it allowed to touch? Permission rules, `dontAsk`, the sandbox, a worktree, the one branch it may push to.
5354. What stops it? `--max-turns`, `--max-budget-usd`, a spend limit.
5365. 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.
467 537
468| Session A (Writer) | Session B (Reviewer) |538Once 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.
469| - | - |
470| `Implement a rate limiter for our API endpoints` | |
471| | `Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.` |
472| `Here's the review feedback: [Session B output]. Address these issues.` | |
473 539
474You can do something similar with tests: have one Claude write tests, then another write code to pass them.540### Run Claude from a script
475 541
476### Fan out across files542[`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.
477
478> [!TIP]
479>
480> Loop through tasks calling `claude -p` for each. Use `--allowedTools` to pre-approve tools for batch operations.
481 543
482For 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`:544In a script you'll almost always want a few more flags:
483 545
484**1. Generate a task list**546* [`--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.
547* `--append-system-prompt`, `--mcp-config`, and `--settings` pass in whatever the run *does* need, explicitly.
548* `--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.
549* `--output-format json` gives you a single result object to parse, and `stream-json` with `--verbose` streams events as they happen.
485 550
486Have 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`551Put together, that looks like this:
487
488**2. Write a script to loop through the list**
489 552
490```bash theme={null}553```bash theme={null}
491for file in $(cat files.txt); do554for file in $(cat files.txt); do
492 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \555 claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
493 --allowedTools "Edit,Bash(git commit *)" \556 --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
494 --permission-mode dontAsk557 --permission-mode dontAsk \
558 --max-turns 20
495done559done
496```560```
497 561
498**3. Test on a few files, then run on all of them**562When 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.
499
500Refine 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.
501 563
502You can also integrate Claude into existing data/processing pipelines:564Auto 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.
503 565
504```bash theme={null}566### Start runs on a schedule or an event
505claude -p "<your prompt>" --output-format json | your_command
506```
507 567
508### Run autonomously with auto mode568Once 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.
509 569
510For 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.570Inside 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:
511 571
512```bash theme={null}572```text theme={null}
513claude --permission-mode auto -p "fix all lint errors"573/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push
514```574```
515 575
516When 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.576Each 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).
517
518### Add an adversarial review step
519 577
520> [!TIP]578> [!WARNING]
521>579>
522> Before treating a task as done, have a subagent review the diff in a fresh context and report gaps.580> 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.
523
524The 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.
525 581
526For 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:582### Run sessions in parallel
527 583
528```text wrap theme={null}584When 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.
529Use a subagent to review the rate limiter diff against PLAN.md. Check that
530every requirement is implemented, the listed edge cases have tests, and
531nothing outside the task's scope changed. Report gaps, not style preferences.
532```
533 585
534Because 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.586A 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:
535 587
536A 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.588```text .worktreeinclude theme={null}
589.env
590.env.local
591config/dev-credentials.json
592```
537 593
538***594Keep 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.
539 595
540## Avoid common failure patterns596You rarely have to clean any of this up yourself:
541 597
542These are common mistakes. Recognizing them early saves time:598* 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.
599* Subagent worktrees disappear when the subagent finishes without changes.
600* Subagent and background-session worktrees that do get left behind are swept once they're older than `cleanupPeriodDays` and hold no work.
543 601
544* **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.602> [!NOTE]
545 > **Fix**: `/clear` between unrelated tasks.603>
546* **Correcting over and over.** Claude does something wrong, you correct it, it's still wrong, you correct again. Context is polluted with failed approaches.604> 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.
547 > **Fix**: After two failed corrections, `/clear` and write a better initial prompt incorporating what you learned.
548* **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.
549 > **Fix**: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.
550* **The trust-then-verify gap.** Claude produces a plausible-looking implementation that doesn't handle edge cases.
551 > **Fix**: Always provide verification (tests, scripts, screenshots). If you can't verify it, don't ship it.
552* **The infinite exploration.** You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context.
553 > **Fix**: Scope investigations narrowly or use subagents so the exploration doesn't consume your main context.
554 605
555***606For 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.
556 607
557## Develop your intuition608A 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.
558 609
559The 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.610## What you can stop doing
560 611
561Sometimes 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.612Every 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.
562 613
563Pay 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?614| The old advice | Why it's gone |
615| :- | :- |
616| 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. |
617| 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. |
618| 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. |
619| 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. |
620| `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. |
621| 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. |
622| Describe your architecture and file layout in `CLAUDE.md` | Claude reads the repo itself. Only write down what isn't in there. |
564 623
565Over 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.624If any other advice on this page ever starts to feel like busywork, that's probably a sign it belongs in this table too.
566 625
567## Related resources626## Related resources
568 627
569* [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md): the agentic loop, tools, and context management628* [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md): the loop, the tools, and what loads at startup
570* [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md): skills, hooks, MCP, subagents, and plugins629* [Explore the context window](https://code.claude.com/docs/en/context-window.md): what uses space in a session and when it loads
571* [Common workflows](https://code.claude.com/docs/en/common-workflows.md): step-by-step recipes for debugging, testing, PRs, and more630* [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md): the choice between skills, hooks, MCP, subagents, and plugins
572* [CLAUDE.md](https://code.claude.com/docs/en/memory.md): store project conventions and persistent context631* [Choose a permission mode](https://code.claude.com/docs/en/permission-modes.md) and [Configure permissions](https://code.claude.com/docs/en/permissions.md)
632* [Manage costs effectively](https://code.claude.com/docs/en/costs.md)
633* [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)
634* For team leads and admins: [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md)
