1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
1# Best Practices for Claude Code5# Best Practices for Claude Code
2 6
3> Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.7> Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.
8 12
9But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand.13But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand.
10 14
11This guide covers patterns that have proven effective across Anthropic's internal teams and for engineers using Claude Code across various codebases, languages, and environments.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 under the hood, see [How Claude Code works](/en/how-claude-code-works).
12 16
13***17***
14 18
16 20
17Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.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.
18 22
19This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage.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. For detailed strategies on reducing token usage, see [Reduce token usage](/en/costs#reduce-token-usage).
20 24
21***25***
22 26
23## Give Claude a way to verify its work27## Give Claude a way to verify its work
24 28
25<Tip>29<Tip>
26 **Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.**30 Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.
27</Tip>31</Tip>
28 32
29Claude performs dramatically better when it can verify its own work, like run tests, compare screenshots, and validate outputs.33Claude performs dramatically better when it can verify its own work, like run tests, compare screenshots, and validate outputs.
45## Explore first, then plan, then code49## Explore first, then plan, then code
46 50
47<Tip>51<Tip>
48 **Separate research and planning from implementation to avoid solving the wrong problem.**52 Separate research and planning from implementation to avoid solving the wrong problem.
49</Tip>53</Tip>
50 54
51Letting Claude jump straight to coding can produce code that solves the wrong problem. Use [Plan Mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to separate exploration from execution.55Letting Claude jump straight to coding can produce code that solves the wrong problem. Use [Plan Mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to separate exploration from execution.
102## Provide specific context in your prompts106## Provide specific context in your prompts
103 107
104<Tip>108<Tip>
105 **The more precise your instructions, the fewer corrections you'll need.**109 The more precise your instructions, the fewer corrections you'll need.
106</Tip>110</Tip>
107 111
108Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.112Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.
119### Provide rich content123### Provide rich content
120 124
121<Tip>125<Tip>
122 **Use `@` to reference files, paste screenshots/images, or pipe data directly.**126 Use `@` to reference files, paste screenshots/images, or pipe data directly.
123</Tip>127</Tip>
124 128
125You can provide rich data to Claude in several ways:129You can provide rich data to Claude in several ways:
134 138
135## Configure your environment139## Configure your environment
136 140
137A few setup steps make Claude Code significantly more effective across all your sessions.141A 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](/en/features-overview).
138 142
139### Write an effective CLAUDE.md143### Write an effective CLAUDE.md
140 144
141<Tip>145<Tip>
142 **Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.**146 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.
143</Tip>147</Tip>
144 148
145CLAUDE.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**.149CLAUDE.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**.
146 150
147The `/init` slash command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.151The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.
148 152
149There's no required format for CLAUDE.md files, but keep it short and human-readable. For example:153There's no required format for CLAUDE.md files, but keep it short and human-readable. For example:
150 154
158- Prefer running single tests, and not the whole test suite, for performance162- Prefer running single tests, and not the whole test suite, for performance
159```163```
160 164
161While it's tempting to dump everything in this file, keep 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!165CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use [skills](/en/skills) instead. Claude loads them on demand without bloating every conversation.
166
167Keep 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!
162 168
163| ✅ Include | ❌ Exclude |169| ✅ Include | ❌ Exclude |
164| ---------------------------------------------------- | -------------------------------------------------- |170| ---------------------------------------------------- | -------------------------------------------------- |
194### Configure permissions200### Configure permissions
195 201
196<Tip>202<Tip>
197 **Use `/permissions` to allowlist safe commands or `/sandbox` for OS-level isolation. This reduces interruptions while keeping you in control.**203 Use `/permissions` to allowlist safe commands or `/sandbox` for OS-level isolation. This reduces interruptions while keeping you in control.
198</Tip>204</Tip>
199 205
200By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:206By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:
213### Use CLI tools219### Use CLI tools
214 220
215<Tip>221<Tip>
216 **Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.**222 Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.
217</Tip>223</Tip>
218 224
219CLI 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.225CLI 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.
223### Connect MCP servers229### Connect MCP servers
224 230
225<Tip>231<Tip>
226 **Run `claude mcp add` to connect external tools like Notion, Figma, or your database.**232 Run `claude mcp add` to connect external tools like Notion, Figma, or your database.
227</Tip>233</Tip>
228 234
229With [MCP servers](/en/mcp), you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.235With [MCP servers](/en/mcp), you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.
230 236
231### Create custom slash commands237### Set up hooks
238
239<Tip>
240 Use hooks for actions that must happen every time with zero exceptions.
241</Tip>
242
243[Hooks](/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.
244
245Claude 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."* Run `/hooks` for interactive configuration, or edit `.claude/settings.json` directly.
246
247### Create skills
232 248
233<Tip>249<Tip>
234 **Save repeated workflows as markdown files in `.claude/commands/` for project-level commands or `~/.claude/commands/` for global commands available in all sessions.**250 Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.
235</Tip>251</Tip>
236 252
237Custom slash commands can include the special keyword `$ARGUMENTS` to pass parameters from command invocation, or `$1`, `$2`, etc. for positional arguments.253[Skills](/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`.
254
255Create a skill by adding a directory with a `SKILL.md` to `.claude/skills/`:
256
257```markdown .claude/skills/api-conventions/SKILL.md theme={null}
258---
259name: api-conventions
260description: REST API design conventions for our services
261---
262# API Conventions
263- Use kebab-case for URL paths
264- Use camelCase for JSON properties
265- Always include pagination for list endpoints
266- Version APIs in the URL path (/v1/, /v2/)
267```
268
269Skills can also define repeatable workflows you invoke directly:
238 270
239```markdown .claude/commands/fix-github-issue.md theme={null}271```markdown .claude/skills/fix-issue/SKILL.md theme={null}
240---272---
273name: fix-issue
241description: Fix a GitHub issue274description: Fix a GitHub issue
275disable-model-invocation: true
242---276---
243Please analyze and fix the GitHub issue: $ARGUMENTS.277Analyze and fix the GitHub issue: $ARGUMENTS.
244 278
245Follow these steps:
2461. Use `gh issue view` to get the issue details2791. Use `gh issue view` to get the issue details
2472. Understand the problem described in the issue2802. Understand the problem described in the issue
2483. Search the codebase for relevant files2813. Search the codebase for relevant files
2538. Push and create a PR2868. Push and create a PR
254```287```
255 288
256Now you can run `/fix-github-issue 1234`. Read more in the [custom slash commands documentation](/en/slash-commands#custom-slash-commands).289Run `/fix-issue 1234` to invoke it. Use `disable-model-invocation: true` for workflows with side effects that you want to trigger manually.
257
258### Install plugins
259
260<Tip>
261 **Run `/plugin` to browse the marketplace. Plugins add commands, tools, and integrations without configuration.**
262</Tip>
263
264Plugins extend Claude Code with pre-built capabilities from the community and Anthropic. Instead of configuring everything yourself, install a plugin and it works immediately.
265
266A plugin can add:
267
268* **Custom commands**: New slash commands for specific workflows (e.g., `/deploy`, `/review`, `/migrate`)
269* **MCP servers**: Pre-configured connections to external tools (databases, APIs, SaaS products)
270* **Subagents**: Specialized assistants for tasks like security review, documentation, or testing
271* **Skills**: Domain knowledge that Claude applies automatically when relevant
272
273Read more in the [plugins documentation](/en/plugins).
274
275### Set up hooks
276
277<Tip>
278 **Use `/hooks` to provide deterministic control over Claude Code's behavior. Instead of hoping Claude remembers to perform an action, hooks guarantee it happens every time.**
279</Tip>
280
281Hooks run scripts automatically at specific points in Claude's workflow:
282
283* **Auto-formatting**: Run prettier on `.ts` files, gofmt on `.go` files after every edit
284* **Linting**: Automatically lint changed files and surface errors
285* **Guardrails**: Block modifications to `.env`, `secrets/`, or production configs
286* **Logging**: Track all executed commands for compliance or debugging
287* **Notifications**: Get alerted when Claude is waiting for input
288
289Claude 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."* Run `/hooks` for interactive configuration, or edit `.claude/settings.json` directly.
290
291If something *must* happen every time with zero exceptions (formatting, linting, blocking writes to sensitive files), use a hook. If it's guidance where judgment is needed (code style preferences, architectural patterns), use CLAUDE.md. Hooks are deterministic; CLAUDE.md is advisory.
292
293Read more in the [hooks documentation](/en/hooks-guide).
294 290
295### Create custom subagents291### Create custom subagents
296 292
297<Tip>293<Tip>
298 **Define specialized assistants in `.claude/agents/` that Claude can delegate to. Each subagent has its own context window, tools, and instructions.**294 Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.
299</Tip>295</Tip>
300 296
301Unlike slash commands (which are prompt templates you invoke explicitly), subagents run in their own context with their own set of allowed tools. They're delegated assistants rather than scripted workflows.297[Subagents](/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.
302 298
303```markdown .claude/agents/security-reviewer.md theme={null}299```markdown .claude/agents/security-reviewer.md theme={null}
304---300---
316Provide specific line references and suggested fixes.312Provide specific line references and suggested fixes.
317```313```
318 314
319Subagents are useful for:315Tell Claude to use subagents explicitly: *"Use a subagent to review this code for security issues."*
320
321* **Code review**: A reviewer subagent checks work without biasing the main conversation
322* **Investigation**: Explore unfamiliar code without consuming your main context
323* **Specialized tasks**: Security review, documentation generation, test writing
324* **Verification**: Have a subagent check that the main agent's work is correct
325 316
326Tell Claude to use subagents explicitly: *"Use a subagent to review this code for security issues."* Read more in the [subagents documentation](/en/sub-agents).317### Install plugins
327
328### Add agent skills
329 318
330<Tip>319<Tip>
331 **Create markdown files in `.claude/skills/` to give Claude domain knowledge it applies automatically. Unlike slash commands, skills are triggered by context, not explicit invocation.**320 Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.
332</Tip>321</Tip>
333 322
334Skills extend Claude's knowledge with information specific to your project, team, or domain. Claude reads skills and autonomously decides when to apply them based on the task at hand.323[Plugins](/en/plugins) 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](/en/discover-plugins#code-intelligence) to give Claude precise symbol navigation and automatic error detection after edits.
335 324
336Create a skill by adding a markdown file to `.claude/skills/`325For guidance on choosing between skills, subagents, hooks, and MCP, see [Extend Claude Code](/en/features-overview#match-features-to-your-goal).
337
338```yaml .claude/skills/api-conventions.md theme={null}
339name: api-conventions
340description: REST API design conventions for our services
341# API Conventions
342- Use kebab-case for URL paths
343- Use camelCase for JSON properties
344- Always include pagination for list endpoints
345- Version APIs in the URL path (/v1/, /v2/)
346```
347
348Skills vs. other customization:
349
350| Feature | Triggered by | Best for |
351| -------------- | ------------------- | ---------------------- |
352| CLAUDE.md | Always loaded | Global project context |
353| Slash commands | Explicit `/command` | Repeatable workflows |
354| Skills | Context (automatic) | Domain knowledge |
355| Subagents | Delegation | Isolated tasks |
356
357Read more in the [skills documentation](/en/skills).
358 326
359***327***
360 328
367### Ask codebase questions333### Ask codebase questions
368 334
369<Tip>335<Tip>
370 **Ask Claude questions you'd ask a senior engineer.**336 Ask Claude questions you'd ask a senior engineer.
371</Tip>337</Tip>
372 338
373When 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:339When 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:
383### Let Claude interview you349### Let Claude interview you
384 350
385<Tip>351<Tip>
386 **For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.**352 For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.
387</Tip>353</Tip>
388 354
389Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.355Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.
407### Course-correct early and often373### Course-correct early and often
408 374
409<Tip>375<Tip>
410 **Correct Claude as soon as you notice it going off track.**376 Correct Claude as soon as you notice it going off track.
411</Tip>377</Tip>
412 378
413The 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.379The 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.
422### Manage context aggressively388### Manage context aggressively
423 389
424<Tip>390<Tip>
425 **Run `/clear` between unrelated tasks to reset context.**391 Run `/clear` between unrelated tasks to reset context.
426</Tip>392</Tip>
427 393
428Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.394Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.
432* Use `/clear` frequently between tasks to reset the context window entirely398* Use `/clear` frequently between tasks to reset the context window entirely
433* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions399* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions
434* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`400* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`
401* 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
435 402
436### Use subagents for investigation403### Use subagents for investigation
437 404
438<Tip>405<Tip>
439 **Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.**406 Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.
440</Tip>407</Tip>
441 408
442Since context is your fundamental constraint, subagents are one of the most powerful tools available. 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:409Since context is your fundamental constraint, subagents are one of the most powerful tools available. 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:
457### Rewind with checkpoints424### Rewind with checkpoints
458 425
459<Tip>426<Tip>
460 **Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.**427 Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.
461</Tip>428</Tip>
462 429
463Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the checkpoint menu. You can restore conversation only (keep code changes), restore code only (keep conversation), or restore both.430Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the checkpoint menu. You can restore conversation only (keep code changes), restore code only (keep conversation), or restore both.
471### Resume conversations438### Resume conversations
472 439
473<Tip>440<Tip>
474 **Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.**441 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.
475</Tip>442</Tip>
476 443
477Claude Code saves conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don't have to re-explain the context:444Claude Code saves conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don't have to re-explain the context:
494### Run headless mode461### Run headless mode
495 462
496<Tip>463<Tip>
497 **Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.**464 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.
498</Tip>465</Tip>
499 466
500With `claude -p "your prompt"`, you can run Claude headlessly, without an interactive session. Headless mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats (plain text, JSON, streaming JSON) let you parse results programmatically.467With `claude -p "your prompt"`, you can run Claude headlessly, without an interactive session. Headless mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats (plain text, JSON, streaming JSON) let you parse results programmatically.
513### Run multiple Claude sessions480### Run multiple Claude sessions
514 481
515<Tip>482<Tip>
516 **Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.**483 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.
517</Tip>484</Tip>
518 485
519There are two main ways to run parallel sessions:486There are two main ways to run parallel sessions:
536### Fan out across files503### Fan out across files
537 504
538<Tip>505<Tip>
539 **Loop through tasks calling `claude -p` for each. Use `--allowedTools` to scope permissions for batch operations.**506 Loop through tasks calling `claude -p` for each. Use `--allowedTools` to scope permissions for batch operations.
540</Tip>507</Tip>
541 508
542For large migrations or analyses, you can distribute work across many parallel Claude invocations:509For large migrations or analyses, you can distribute work across many parallel Claude invocations:
607 574
608Over 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.575Over 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.
609 576
577## Related resources
610 578
579<CardGroup cols={2}>
580 <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works">
581 Understand the agentic loop, tools, and context management
582 </Card>
583
584 <Card title="Extend Claude Code" icon="puzzle-piece" href="/en/features-overview">
585 Choose between skills, hooks, MCP, subagents, and plugins
586 </Card>
587
588 <Card title="Common workflows" icon="list-check" href="/en/common-workflows">
589 Step-by-step recipes for debugging, testing, PRs, and more
590 </Card>
611 591
612> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt592 <Card title="CLAUDE.md" icon="file-lines" href="/en/memory">
593 Store project conventions and persistent context
594 </Card>
595</CardGroup>
