Best Practices for Claude Code

Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.

Claude performs dramatically better when it can verify its own work — run tests, compare screenshots, and validate outputs. Without clear success criteria, it might produce something that looks right but actually doesn't work. You become the only feedback loop, and every mistake requires your attention.

Key strategies: • Provide verification criteria — Instead of 'implement a function that validates email addresses,' say 'write a validateEmail function with test cases: user@example.com is true, invalid is false. Run the tests after implementing.' • Verify UI changes visually — Paste a screenshot, implement the design, take a screenshot of the result and compare. • Address root causes, not symptoms — Instead of 'the build is failing,' paste the error and ask Claude to fix the root cause.

Your verification can be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.

Separate research and planning from implementation to avoid solving the wrong problem. Use Plan Mode to separate exploration from execution.

The recommended workflow has four phases: 1. Explore — Enter Plan Mode. Claude reads files and answers questions without making changes. 2. Plan — Ask Claude to create a detailed implementation plan. Press Ctrl+G to open the plan in your editor for direct editing. 3. Implement — Switch back to Normal Mode and let Claude code, verifying against its plan. 4. Commit — Ask Claude to commit with a descriptive message and create a PR.

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. If you could describe the diff in one sentence, skip the plan.

The more precise your instructions, the fewer corrections you'll need. Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.

Key strategies: • Scope the task — Specify which file, what scenario, and testing preferences. • Point to sources — Direct Claude to the source that can answer a question. • Reference existing patterns — Point Claude to patterns in your codebase. • Describe the symptom — Provide the symptom, the likely location, and what 'fixed' looks like.

You can provide rich data to Claude in several ways: reference files with @, paste images directly, give URLs for documentation, pipe in data, or let Claude fetch what it needs using Bash commands, MCP tools, or by reading files.

A few setup steps make Claude Code significantly more effective across all your sessions.

• Write an effective CLAUDE.md — Run /init to generate a starter file, then refine over time. Include Bash commands, code style, and workflow rules. Keep it concise — only include things that apply broadly. • Configure permissions — Use /permissions to allowlist safe commands or /sandbox for OS-level isolation. • Use CLI tools — Tell Claude to use tools like gh, aws, gcloud, and sentry-cli for external services. • Connect MCP servers — Run claude mcp add to connect external tools like Notion, Figma, or your database. • Set up hooks — Use hooks for actions that must happen every time with zero exceptions. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic. • Create skills — Create SKILL.md files in .claude/skills/ for domain knowledge and reusable workflows. • Create custom subagents — Define specialized assistants in .claude/agents/ for isolated tasks. • Install plugins — Run /plugin to browse the marketplace for skills, tools, and integrations.

Ask Claude questions you'd ask a senior engineer. When onboarding to a new codebase, use Claude Code for learning and exploration — ask how logging works, how to make a new API endpoint, what edge cases a class handles, or why code calls one function instead of another.

For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the AskUserQuestion tool. Claude asks about technical implementation, UI/UX, edge cases, and tradeoffs. Once the spec is complete, start a fresh session to execute it.

Correct Claude as soon as you notice it going off track. The best results come from tight feedback loops.

• Esc — Stop Claude mid-action. Context is preserved. • Esc + Esc or /rewind — Restore previous conversation and code state. • 'Undo that' — Have Claude revert its changes. • /clear — Reset context between unrelated tasks.

Manage context aggressively — use /clear frequently between tasks, run /compact with focus instructions, and customize compaction behavior in CLAUDE.md. Delegate research to subagents to keep your main conversation clean.

Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint. Resume conversations with claude --continue or --resume.

Once you're effective with one Claude, multiply your output with parallel sessions, headless mode, and fan-out patterns.

• Run headless mode — Use claude -p 'prompt' in CI, pre-commit hooks, or scripts. Add --output-format stream-json for streaming JSON output. • Run multiple Claude sessions — Use Claude Desktop, Claude Code on the web, or agent teams for parallel work. Use a Writer/Reviewer pattern for quality. • Fan out across files — Loop through tasks calling claude -p for each. Use --allowedTools to scope permissions for batch operations. • Safe Autonomous Mode — Use --dangerously-skip-permissions in a container without internet access, or enable /sandbox for better security with similar autonomy.

Common mistakes to watch for:

• The kitchen sink session — You mix unrelated tasks in one session. Fix: /clear between unrelated tasks. • Correcting over and over — Context gets polluted with failed approaches. Fix: After two failed corrections, /clear and write a better initial prompt. • The over-specified CLAUDE.md — Too long, so Claude ignores half of it. Fix: Ruthlessly prune. If Claude already does something correctly, delete that instruction. • The trust-then-verify gap — Plausible-looking code that doesn't handle edge cases. Fix: Always provide verification. • The infinite exploration — Unscoped investigation fills the context. Fix: Scope narrowly or use subagents.

Pay attention to what works. Over time, you'll develop intuition that no guide can capture — when to be specific vs. open-ended, when to plan vs. explore, when to clear context vs. let it accumulate.