Best practices for Claude Code - Claude Code Docs
Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Give Claude a way to verify its work
Explore first, then plan, then code
Provide specific context in your prompts
Provide rich content
@ instead of describing where code lives. Claude reads the file before responding./permissions to allowlist frequently-used domains.cat error.log | claude to send file contents directly.Configure your environment
Write an effective CLAUDE.md
# Code style - Use ES modules (import/export) syntax, not CommonJS (require) - Destructure imports when possible (eg. import { foo } from 'bar') # Workflow - Be sure to typecheck when you're done making a series of code changes - Prefer running single tests, and not the whole test suite, for performance
See @README.md for project overview and @package.json for available npm commands. # Additional Instructions - Git workflow: @docs/git-instructions.md - Personal overrides: @~/.claude/my-project-instructions.md
~/.claude/CLAUDE.md): applies to all Claude sessions./CLAUDE.md): check into git to share with your team./CLAUDE.local.md): personal project-specific notes; add this file to your .gitignore so it isn’t shared with your teamroot/CLAUDE.md and root/foo/CLAUDE.md are pulled in automaticallyConfigure permissions
npm run lint or git commitUse CLI tools
Connect MCP servers
Set up hooks
Create skills
--- name: api-conventions description: REST API design conventions for our services --- # API Conventions - Use kebab-case for URL paths - Use camelCase for JSON properties - Always include pagination for list endpoints - Version APIs in the URL path (/v1/, /v2/)
--- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Analyze and fix the GitHub issue: $ARGUMENTS. 1. Use `gh issue view` to get the issue details 2. Understand the problem described in the issue 3. Search the codebase for relevant files 4. Implement the necessary changes to fix the issue 5. Write and run tests to verify the fix 6. Ensure code passes linting and type checking 7. Create a descriptive commit message 8. Push and create a PR
Create custom subagents
--- name: security-reviewer description: Reviews code for security vulnerabilities tools: Read, Grep, Glob, Bash model: opus --- You are a senior security engineer. Review code for: - Injection vulnerabilities (SQL, XSS, command injection) - Authentication and authorization flaws - Secrets or credentials in code - Insecure data handling Provide specific line references and suggested fixes.
Install plugins
Communicate effectively
Ask codebase questions
async move { ... } do on line 134 of foo.rs?CustomerOnboardingFlowImpl handle?foo() instead of bar() on line 333?Let Claude interview you
I want to build [brief description]. Interview me in detail using the AskUserQuestion tool. Ask 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. Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
Manage your session
Course-correct early and often
Esc: stop Claude mid-action with the Esc key. Context is preserved, so you can redirect.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."Undo that": have Claude revert its changes./clear: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.Manage context aggressively
/clear frequently between tasks to reset the context window entirely/compact <instructions>, like /compact Focus on the API changesEsc + 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 Restore vs. summarize."When compacting, always preserve the full list of modified files and any test commands" to ensure critical context survives summarization/btw. The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.Use subagents for investigation
Use subagents to investigate how our authentication system handles token refresh, and whether we have any existing OAuth utilities I should reuse.
use a subagent to review this code for edge cases
Rewind with checkpoints
Resume conversations
Automate and scale
Run non-interactive mode
# One-off queries claude -p "Explain what this project does" # Structured output for scripts claude -p "List all API endpoints" --output-format json # Streaming for real-time processing claude -p "Analyze this log file" --output-format stream-json
Run multiple Claude sessions
Fan out across files
claude -p "<your prompt>" --output-format json | your_command
Run autonomously with auto mode
claude --permission-mode auto -p "fix all lint errors"
Avoid common failure patterns
Fix: /clear between unrelated tasks. Fix: After two failed corrections, /clear and write a better initial prompt incorporating what you learned. Fix: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.
Fix: Always provide verification (tests, scripts, screenshots). If you can’t verify it, don’t ship it.
Fix: Scope investigations narrowly or use subagents so the exploration doesn’t consume your main context.