(2026-01-21) Claude Code Best Practices

Claude Code Best Practices. Claude Code is intentionally low-level and unopinionated, providing close to raw model access without forcing specific workflows. This design philosophy creates a flexible, customizable, scriptable, and safe power tool. While powerful, this flexibility presents a learning curve for engineers new to agentic coding tools—at least until they develop their own best practices.

1. Customize your setup

a. Create CLAUDE.md files

an ideal place for documenting:

• Common bash commands
• Core files and utility functions
• Code style guidelines
• Testing instructions

There’s no required format for CLAUDE.md files. We recommend keeping them concise and human-readable. For example...

You can place CLAUDE.md files in several locations:

When you run the /init command, Claude will automatically generate a CLAUDE.md for you.

b. Tune your CLAUDE.md files

Your CLAUDE.md files become part of Claude’s prompts, so they should be refined like any frequently used prompt.

You can add content to your CLAUDE.md manually or press the # key to give Claude an instruction that it will automatically incorporate into the relevant CLAUDE.md.

At Anthropic, we occasionally run CLAUDE.md files through the prompt improver and often tune instructions (e.g. adding emphasis with "IMPORTANT" or "YOU MUST") to improve adherence.

c. Curate Claude's list of allowed tools

d. If using GitHub, install the gh CLI

2. Give Claude more tools

a. Use Claude with bash tools

Claude Code inherits your bash environment, giving it access to all your tools. While Claude knows common utilities like unix tools and gh, it won't know about your custom bash tools without instructions:

b. Use Claude with MCP

Claude Code functions as both an MCP server and client.

When working with MCP, it can also be helpful to launch Claude with the --mcp-debug flag to help identify configuration issues.

c. Use custom slash commands

For repeated workflows—debugging loops, log analysis, etc.—store prompt templates in Markdown files within the .claude/commands folder.

3. Try common workflows

Claude Code doesn’t impose a specific workflow, giving you the flexibility to use it how you want. Within the space this flexibility affords, several successful patterns for effectively using Claude Code have emerged across our community of users:

a. Explore, plan, code, commit

Ask Claude to read relevant files, images, or URLs, providing either general pointers ("read the file that handles logging") or specific filenames ("read logging.py"), but explicitly tell it not to write any code just yet. This is the part of the workflow where you should consider strong use of subagents, especially for complex problems.

Ask Claude to make a plan for how to approach a specific problem. We recommend using the word "think" to trigger extended thinking mode, which gives Claude additional computation time to evaluate alternatives more thoroughly.

If the results of this step seem reasonable, you can have Claude create a document or a GitHub issue with its plan so that you can reset to this spot if the implementation (step 3) isn’t what you want.

Ask Claude to implement its solution in code.

Ask Claude to commit the result and create a pull request. If relevant, this is also a good time to have Claude update any READMEs or changelogs with an explanation of what it just did.

Steps #1-#2 are crucial—without them, Claude tends to jump straight to coding a solution. While sometimes that's what you want, asking Claude to research and plan first significantly improves performance for problems requiring deeper thinking upfront.

b. Write tests, commit; code, iterate, commit

This is an Anthropic-favorite workflow for changes that are easily verifiable with unit, integration, or end-to-end tests. Test-driven development (TDD) becomes even more powerful with agentic coding:

c. Write code, screenshot result, iterate

*Similar to the testing workflow, you can provide Claude with visual targets:

Give Claude a way to take browser screenshots (e.g., with the Puppeteer MCP server, an iOS simulator MCP server, or manually copy / paste screenshots into Claude). Give Claude a visual mock by copying / pasting or drag-dropping an image, or giving Claude the image file path. Ask Claude to implement the design in code, take screenshots of the result, and iterate until its result matches the mock.*

d. Safe YOLO mode

*Instead of supervising Claude, you can use claude --dangerously-skip-permissions to bypass all permission checks and let Claude work uninterrupted until completion. This works well for workflows like fixing lint errors or generating boilerplate code.

Letting Claude run arbitrary commands is risky and can result in data loss, system corruption, or even data exfiltration (e.g., via prompt injection attacks). To minimize these risks, use --dangerously-skip-permissions in a container without internet access. You can follow this reference implementation using Docker Dev Containers.*

e. Codebase Q&A

f. Use Claude to interact with git

g. Use Claude to interact with GitHub

h. Use Claude to work with Jupyter notebooks (or Marimo)

Researchers and data scientists at Anthropic use Claude Code to read and write Jupyter notebooks. Claude can interpret outputs, including images, providing a fast way to explore and interact with data. There are no required prompts or workflows, but a workflow we recommend is to have Claude Code and a .ipynb file open side-by-side in VS Code.

4. Optimize your workflow

a. Be specific in your instructions

Claude Code’s success rate improves significantly with more specific instructions, especially on first attempts. Giving clear directions upfront reduces the need for course corrections later.

b. Give Claude images

Drag and drop images directly into the prompt input

This is particularly useful when working with design mocks (mockup) as reference points for UI development, and visual charts for analysis and debugging.

c. Mention files you want Claude to look at or work on

d. Give Claude URLs

e. Course correct early and often

While auto-accept mode (shift+tab to toggle) lets Claude work autonomously, you'll typically get better results by being an active collaborator and guiding Claude's approach. You can get the best results by thoroughly explaining the task to Claude at the beginning, but you can also course correct Claude at any time.

These four tools help with course correction:

• Ask Claude to make a plan before coding. Explicitly tell it not to code until you’ve confirmed its plan looks good.
• Press Escape to interrupt Claude during any phase (thinking, tool calls, file edits), preserving context so you can redirect or expand instructions.
• Double-tap Escape to jump back in history, edit a previous prompt, and explore a different direction. You can edit the prompt and repeat until you get the result you're looking for.
• Ask Claude to undo changes, often in conjunction with option #2 to take a different approach.

f. Use /clear to keep context focused

g. Use checklists and scratchpads for complex workflows

h. Pass data into Claude

Several methods exist for providing data to Claude:

• Copy and paste directly into your prompt (most common approach)
• Pipe into Claude Code (e.g., cat foo.txt | claude), particularly useful for logs, CSVs, and large data
• Tell Claude to pull data via bash commands, MCP tools, or custom slash commands
• Ask Claude to read files or fetch URLs (works for images too)

5. Use headless mode to automate your infra

a. Use Claude for issue triage

b. Use Claude as a linter

6. Uplevel with multi-Claude workflows

some of the most powerful applications involve running multiple Claude instances in parallel:

a. Have one Claude write code; use another Claude to verify

Similar to working with multiple engineers, sometimes having separate context is beneficial:

You can do something similar with tests: have one Claude write tests, then have another Claude write code to make the tests pass. You can even have your Claude instances communicate with each other by giving them separate working scratchpads and telling them which one to write to and which one to read from.

b. Have multiple checkouts of your repo

Rather than waiting for Claude to complete each step, something many engineers at Anthropic do is:

• Create 3-4 git checkouts in separate folders
• Open each folder in separate terminal tabs
• Start Claude in each folder with different tasks
• Cycle through to check progress and approve/deny permission requests

c. Use git worktrees

d. Use headless mode with a custom harness