Best practices for Claude Code changedbest-practices
Nearest release: v2.1.304, published 6 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 02:14 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+132added
Lines−140removed
From line
22
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
The whole hunk
from line 22, old and new numbered
/
from line 22
2222
2323## Give Claude a way to verify its work
2424
25<Tip>
26 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.
27</Tip>
25> [!TIP]
26>
27> Give Claude a check it can run: tests, a build, a screenshot to compare. It's the difference between a session you watch and one you walk away from.
2828
2929Claude 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.
3030
from line 51
5151
5252## Explore first, then plan, then code
5353
54<Tip>
55 Separate research and planning from implementation to avoid solving the wrong problem.
56</Tip>
54> [!TIP]
55>
56> Separate research and planning from implementation to avoid solving the wrong problem.
5757
5858Letting Claude jump straight to coding can produce code that solves the wrong problem. Use [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) to separate exploration from execution.
5959
6060The recommended workflow has four phases:
6161
62<Steps>
63 <Step title="Explore">
64 Enter 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.
62**1. Explore**
6563
66 ```txt title="claude (plan mode)" wrap theme={null}
67 read /src/auth and understand how we handle sessions and login.
68 also look at how we manage environment variables for secrets.
69 ```
70 </Step>
64Enter plan mode by pressing `Shift+Tab` until the status bar shows `⏸ plan mode on`, or start the session with `claude --permission-mode plan`. Claude reads files and answers questions without making changes.
7165
72 <Step title="Plan">
73 Ask Claude to create a detailed implementation plan.
66```txt title="claude (plan mode)" wrap theme={null}
67read /src/auth and understand how we handle sessions and login.
68also look at how we manage environment variables for secrets.
69```
7470
75 ```txt title="claude (plan mode)" wrap theme={null}
76 I want to add Google OAuth. What files need to change?
77 What's the session flow? Create a plan.
78 ```
71**2. Plan**
7972
80 Press `Ctrl+G` to open the plan in your text editor for direct editing before Claude proceeds.
81 </Step>
73Ask Claude to create a detailed implementation plan.
8274
83 <Step title="Implement">
84 Switch out of plan mode by approving the plan or pressing `Shift+Tab`, then let Claude code, verifying against its plan.
75```txt title="claude (plan mode)" wrap theme={null}
76I want to add Google OAuth. What files need to change?
77What's the session flow? Create a plan.
78```
8579
86 ```txt title="claude" wrap theme={null}
87 implement the OAuth flow from your plan. write tests for the
88 callback handler, run the test suite and fix any failures.
89 ```
90 </Step>
80Press `Ctrl+G` to open the plan in your text editor for direct editing before Claude proceeds.
9181
92 <Step title="Commit">
93 Ask Claude to commit with a descriptive message and create a PR.
82**3. Implement**
9483
95 ```txt title="claude" wrap theme={null}
96 commit with a descriptive message and open a PR
97 ```
98 </Step>
99</Steps>
84Switch out of plan mode by approving the plan or pressing `Shift+Tab`, then let Claude code, verifying against its plan.
10085
101<Callout>
102 Plan mode is useful, but also adds overhead.
86```txt title="claude" wrap theme={null}
87implement the OAuth flow from your plan. write tests for the
88callback handler, run the test suite and fix any failures.
89```
10390
104 For 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.
91**4. Commit**
10592
106 Planning 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.
107</Callout>
93Ask Claude to commit with a descriptive message and create a PR.
10894
95```txt title="claude" wrap theme={null}
96commit with a descriptive message and open a PR
97```
98
99Plan mode is useful, but also adds overhead.
100
101For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.
102
103Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.
104
109105***
110106
111107## Provide specific context in your prompts
112108
113<Tip>
114 The more precise your instructions, the fewer corrections you'll need.
115</Tip>
109> [!TIP]
110>
111> The more precise your instructions, the fewer corrections you'll need.
116112
117113Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.
118114
from line 123
127123
128124### Provide rich content
129125
130<Tip>
131 Use `@` to reference files, paste screenshots/images, or pipe data directly.
132</Tip>
126> [!TIP]
127>
128> Use `@` to reference files, paste screenshots/images, or pipe data directly.
133129
134130You can provide rich data to Claude in several ways:
135131
from line 143
147143
148144### Write an effective CLAUDE.md
149145
150<Tip>
151 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.
152</Tip>
146> [!TIP]
147>
148> Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.
153149
154150CLAUDE.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.
155151
from line 183
187183
188184### Configure permissions
189185
190<Tip>
191 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.
192</Tip>
186> [!TIP]
187>
188> To get fewer prompts without giving up control, pre-approve the tools you trust with `/permissions` and let sandboxed commands run without asking with `/sandbox`. Switch to Manual mode when you want to approve edits and commands yourself.
193189
194190With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](/docs/en/permission-modes#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.
195191
from line 198
202198
203199### Use CLI tools
204200
205<Tip>
206 Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.
207</Tip>
201> [!TIP]
202>
203> Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.
208204
209205CLI 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.
210206
from line 208
212208
213209### Connect MCP servers
214210
215<Tip>
216 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`.
217</Tip>
211> [!TIP]
212>
213> Run `claude mcp add` with a server name and URL or command to connect external tools like Notion, Figma, or your database. For example: `claude mcp add --transport http notion https://mcp.notion.com/mcp`.
218214
219215With [MCP servers](/docs/en/mcp), you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.
220216
221217### Set up hooks
222218
223<Tip>
224 Use hooks for actions that must happen every time with zero exceptions.
225</Tip>
219> [!TIP]
220>
221> Use hooks for actions that must happen every time with zero exceptions.
226222
227223[Hooks](/docs/en/hooks-guide) 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.
228224
from line 226
230226
231227### Create skills
232228
233<Tip>
234 Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.
235</Tip>
229> [!TIP]
230>
231> Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.
236232
237233[Skills](/docs/en/skills) 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`.
238234
from line 270
274270
275271### Create custom subagents
276272
277<Tip>
278 Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.
279</Tip>
273> [!TIP]
274>
275> Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.
280276
281277[Subagents](/docs/en/sub-agents) 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.
282278
from line 296
300296
301297### Install plugins
302298
303<Tip>
304 Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.
305</Tip>
299> [!TIP]
300>
301> Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.
306302
307303[Plugins](/docs/en/plugins/overview) 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](/docs/en/plugins/code-intelligence) to give Claude precise symbol navigation and automatic error detection after edits.
308304
from line 312
316312
317313### Ask codebase questions
318314
319<Tip>
320 Ask Claude questions you'd ask a senior engineer.
321</Tip>
315> [!TIP]
316>
317> Ask Claude questions you'd ask a senior engineer.
322318
323319When 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:
324320
from line 328
332328
333329### Let Claude interview you
334330
335<Tip>
336 For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.
337</Tip>
331> [!TIP]
332>
333> For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.
338334
339335Claude 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.
340336
from line 354
358354
359355### Course-correct early and often
360356
361<Tip>
362 Correct Claude as soon as you notice it going off track.
363</Tip>
357> [!TIP]
358>
359> Correct Claude as soon as you notice it going off track.
364360
365361The 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.
366362
from line 369
373369
374370### Manage context aggressively
375371
376<Tip>
377 Run `/clear` between unrelated tasks to reset context.
378</Tip>
372> [!TIP]
373>
374> Run `/clear` between unrelated tasks to reset context.
379375
380376Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.
381377
from line 386
390386
391387### Use subagents for investigation
392388
393<Tip>
394 Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.
395</Tip>
389> [!TIP]
390>
391> Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.
396392
397393Since 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:
398394
from line 401
405401
406402### Rewind with checkpoints
407403
408<Tip>
409 Every prompt you send that starts a turn creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.
410</Tip>
404> [!TIP]
405>
406> Every prompt you send that starts a turn creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.
411407
412408Claude 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](/docs/en/checkpointing) for details.
413409
414410Instead 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.
415411
416<Warning>
417 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.
418</Warning>
412> [!WARNING]
413>
414> Checkpoints only track changes made through Claude's file editing tools. Changes made through Bash commands or external processes are not captured. This isn't a replacement for git.
419415
420416### Resume conversations
421417
422<Tip>
423 Name sessions with `/rename` and treat them like branches: each workstream gets its own persistent context.
424</Tip>
418> [!TIP]
419>
420> Name sessions with `/rename` and treat them like branches: each workstream gets its own persistent context.
425421
426422Claude Code saves conversations locally, so when a task spans multiple sittings you don't have to re-explain the context. Run [`claude --continue`](/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](/docs/en/sessions) for the full set of resume, branch, and naming controls.
427423
from line 429
433429
434430### Run non-interactive mode
435431
436<Tip>
437 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json --verbose` for streaming JSON output.
438</Tip>
432> [!TIP]
433>
434> Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json --verbose` for streaming JSON output.
439435
440436With `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](/docs/en/headless) 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.
441437
from line 450
454450
455451### Run multiple Claude sessions
456452
457<Tip>
458 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.
459</Tip>
453> [!TIP]
454>
455> Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.
460456
461457Pick 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:
462458
from line 477
481477
482478### Fan out across files
483479
484<Tip>
485 Loop through tasks calling `claude -p` for each. Use `--allowedTools` to pre-approve tools for batch operations.
486</Tip>
480> [!TIP]
481>
482> Loop through tasks calling `claude -p` for each. Use `--allowedTools` to pre-approve tools for batch operations.
487483
488484For large migrations or analyses, you can distribute work across many parallel Claude invocations. Run [`/batch <instruction>`](/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`:
489485
490<Steps>
491 <Step title="Generate a task list">
492 Have 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`
493 </Step>
486**1. Generate a task list**
494487
495 <Step title="Write a script to loop through the list">
496 ```bash theme={null}
497 for file in $(cat files.txt); do
498 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
499 --allowedTools "Edit,Bash(git commit *)" \
500 --permission-mode dontAsk
501 done
502 ```
503 </Step>
488Have Claude write the list of files that need migrating to a file, so the loop in the next step can read it, with a prompt like `list all 2,000 Python files that need migrating and save the list to files.txt`
504489
505 <Step title="Test on a few files, then run on all of them">
506 Refine 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`](/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](/docs/en/plugins/mods/overview) you installed can still approve some of those calls.
507 </Step>
508</Steps>
490**2. Write a script to loop through the list**
509491
492```bash theme={null}
493for file in $(cat files.txt); do
494 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
495 --allowedTools "Edit,Bash(git commit *)" \
496 --permission-mode dontAsk
497done
498```
499
500**3. Test on a few files, then run on all of them**
501
502Refine your prompt based on what goes wrong with the first 2-3 files, then run on the full set. The `--allowedTools` flag pre-approves the tools the migration needs. [`--permission-mode dontAsk`](/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](/docs/en/plugins/mods/overview) you installed can still approve some of those calls.
503
510504You can also integrate Claude into existing data/processing pipelines:
511505
512506```bash theme={null}
from line 519
525519
526520### Add an adversarial review step
527521
528<Tip>
529 Before treating a task as done, have a subagent review the diff in a fresh context and report gaps.
530</Tip>
522> [!TIP]
523>
524> Before treating a task as done, have a subagent review the diff in a fresh context and report gaps.
531525
532526The longer Claude works unattended, the more an independent check matters before you count the work as done. A reviewer running in a fresh [subagent](/docs/en/sub-agents) 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.
533527
from line 535
541535
542536Because 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.
543537
544<Callout>
545 A 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.
546</Callout>
538A reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. Chasing every finding leads to over-engineering: extra abstraction layers, defensive code, and tests for cases that can't happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional.
547539
548540***
549541
No line in this hunk matches that.