<div class="callout" data-callout="info"> <div class="callout-title">Overview</div> <div class="callout-content"> Claude Code is Anthropic's command line tool for agentic coding, designed as a flexible, customizable power tool that integrates Claude into coding workflows. This article summarizes key best practices from Anthropic's engineering team for maximizing productivity with Claude Code across various codebases, languages, and environments. </div> </div> <div class="topic-area"> ## Customizing Your Setup The foundation of an effective Claude Code workflow starts with proper environment configuration. These customizations significantly improve Claude's ability to understand your codebase and follow your preferred patterns. ### CLAUDE.md Files: Your Project's Memory CLAUDE.md files serve as Claude's memory for your project, automatically pulled into context when starting a conversation. These files are ideal for documenting: - Common bash commands - Core files and utility functions - Code style guidelines - Testing instructions - Repository etiquette - Developer environment setup - Project-specific quirks You can place CLAUDE.md files in several strategic locations: - The repository root (most common) - Any parent directory of where you run Claude - Any child directory of where you run Claude - Your home folder (~/.claude/CLAUDE.md) <div class="callout" data-callout="tip"> <div class="callout-title">Pro Tip</div> <div class="callout-content"> When you run the /init command, Claude will automatically generate a CLAUDE.md file for you. You can then refine this file over time to improve Claude's understanding of your project. </div> </div> ### Tuning Your Instructions Your CLAUDE.md files become part of Claude's prompts, so they should be refined like any frequently used prompt. Take time to experiment with different instructions and determine what produces the best results. Many engineers use the # key to give Claude instructions that it automatically incorporates into the relevant CLAUDE.md, documenting commands, files, and style guidelines while coding. ### Curating Allowed Tools By default, Claude Code requests permission for any action that might modify your system. You can customize the allowlist to permit additional tools that you know are safe: - Select "Always allow" when prompted during a session - Use the `/allowed-tools` command after starting Claude Code - Manually edit your `.claude/settings.json` or `~/.claude.json` - Use the `--allowedTools` CLI flag for session-specific permissions ### GitHub Integration If you're using GitHub, install the `gh` CLI to enable Claude to interact with GitHub for creating issues, opening pull requests, reading comments, and more. </div> <div class="topic-area"> ## Expanding Claude's Toolbox Claude becomes more powerful when given access to additional tools and capabilities. ### Bash Tools Integration Claude Code inherits your bash environment, giving it access to all your tools. To help Claude use your custom bash tools: 1. Tell Claude the tool name with usage examples 2. Tell Claude to run `--help` to see tool documentation 3. Document frequently used tools in CLAUDE.md ### MCP (Model Context Protocol) Integration Claude Code functions as both an MCP server and client, allowing it to connect to any number of MCP servers to access their tools in three ways: - In project config (available when running Claude Code in that directory) - In global config (available in all projects) - In a checked-in `.mcp.json` file (available to anyone working in your codebase) <div class="callout" data-callout="tip"> <div class="callout-title">Debugging Tip</div> <div class="callout-content"> When working with MCP, launch Claude with the `--mcp-debug` flag to help identify configuration issues. </div> </div> ### Custom Slash Commands For repeated workflows—debugging loops, log analysis, etc.—store prompt templates in Markdown files within the `.claude/commands` folder. These become available through the slash commands menu when you type /. Custom slash commands can include the special keyword `$ARGUMENTS` to pass parameters from command invocation, enabling powerful automation for common tasks. </div> <div class="topic-area"> ## Effective Workflows Claude Code doesn't impose a specific workflow, giving you the flexibility to use it how you want. Several successful patterns have emerged across the user community: ### Explore, Plan, Code, Commit This versatile workflow suits many problems: 1. **Explore**: Ask Claude to read relevant files, images, or URLs 2. **Plan**: Ask Claude to make a plan for approaching the problem (use "think" to trigger extended thinking mode) 3. **Code**: Ask Claude to implement its solution 4. **Commit**: Ask Claude to commit the result and create a pull request <div class="callout" data-callout="warning"> <div class="callout-title">Important</div> <div class="callout-content"> Steps #1-#2 are crucial—without them, Claude tends to jump straight to coding a solution. Asking Claude to research and plan first significantly improves performance for problems requiring deeper thinking upfront. </div> </div> ### Test-Driven Development This Anthropic-favorite workflow is particularly effective for changes that are easily verifiable with tests: 1. Ask Claude to write tests based on expected input/output pairs 2. Tell Claude to run the tests and confirm they fail 3. Ask Claude to commit the tests 4. Ask Claude to write code that passes the tests 5. Ask Claude to commit the code once all tests pass ### Visual-Driven Development Similar to the testing workflow, you can provide Claude with visual targets: 1. Give Claude a way to take browser screenshots 2. Provide a visual mock 3. Ask Claude to implement the design, take screenshots, and iterate until the result matches the mock 4. Commit when satisfied ### Safe YOLO Mode For tasks like fixing lint errors or generating boilerplate code, you can use `claude --dangerously-skip-permissions` to bypass all permission checks and let Claude work uninterrupted. <div class="callout" data-callout="danger"> <div class="callout-title">Security Warning</div> <div class="callout-content"> Letting Claude run arbitrary commands is risky. To minimize these risks, use `--dangerously-skip-permissions` in a container without internet access. </div> </div> ### Codebase Q&A When onboarding to a new codebase, use Claude Code for learning and exploration. Ask questions like: - How does logging work? - How do I make a new API endpoint? - What edge cases does this component handle? - Why is the code structured this way? ### Git Integration Claude can effectively handle many git operations: - Searching git history to answer questions - Writing commit messages - Handling complex git operations like reverting files and resolving rebase conflicts ### GitHub Integration Claude Code can manage many GitHub interactions: - Creating pull requests - Implementing one-shot resolutions for code review comments - Fixing failing builds or linter warnings - Categorizing and triaging open issues ### Jupyter Notebook Integration Researchers and data scientists can 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. </div> <div class="topic-area"> ## Workflow Optimization These suggestions apply across all workflows: ### 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. | Poor | Good | |------|------| | add tests for foo.py | write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks | | why does ExecutionFactory have such a weird api? | look through ExecutionFactory's git history and summarize how its api came to be | | add a calendar widget | look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase. | ### Leverage Visual Context Claude excels with images and diagrams through several methods: - Paste screenshots - Drag and drop images directly into the prompt input - Provide file paths for images This is particularly useful when working with design mocks as reference points for UI development. ### Reference Files Explicitly Use tab-completion to quickly reference files or folders anywhere in your repository, helping Claude find or update the right resources. ### Provide URLs for External Context Paste specific URLs alongside your prompts for Claude to fetch and read. To avoid permission prompts for the same domains, use `/allowed-tools` to add domains to your allowlist. ### Course Correct Early and Often While auto-accept mode lets Claude work autonomously, you'll typically get better results by being an active collaborator and guiding Claude's approach. These four tools help with course correction: - Ask Claude to make a plan before coding - Press Escape to interrupt Claude during any phase - Double-tap Escape to jump back in history - Ask Claude to undo changes ### Keep Context Focused Use the `/clear` command frequently between tasks to reset the context window, preventing it from filling with irrelevant conversation, file contents, and commands. ### Use Checklists for Complex Tasks For large tasks with multiple steps, improve performance by having Claude use a Markdown file as a checklist and working scratchpad. ### Efficient Data Input Several methods exist for providing data to Claude: - Copy and paste directly into your prompt - Pipe into Claude Code (e.g., `cat foo.txt | claude`) - Tell Claude to pull data via bash commands, MCP tools, or custom slash commands - Ask Claude to read files or fetch URLs </div> <div class="topic-area"> ## Automation with Headless Mode Claude Code includes headless mode for non-interactive contexts like CI, pre-commit hooks, build scripts, and automation. Use the `-p` flag with a prompt to enable headless mode, and `--output-format stream-json` for streaming JSON output. ### Issue Triage Automation Headless mode can power automations triggered by GitHub events, such as when a new issue is created in your repository, automatically assigning appropriate labels. ### AI-Powered Linting Claude Code can provide subjective code reviews beyond what traditional linting tools detect, identifying issues like typos, stale comments, misleading function or variable names, and more. </div> <div class="topic-area"> ## Multi-Claude Workflows Beyond standalone usage, some of the most powerful applications involve running multiple Claude instances in parallel: ### Separation of Concerns Have one Claude write code while another reviews or tests it: 1. Use Claude to write code 2. Run `/clear` or start a second Claude in another terminal 3. Have the second Claude review the first Claude's work 4. Start another Claude to read both the code and review feedback 5. Have this Claude edit the code based on the feedback ### Multiple Repository Checkouts Rather than waiting for Claude to complete each step: 1. Create 3-4 git checkouts in separate folders 2. Open each folder in separate terminal tabs 3. Start Claude in each folder with different tasks 4. Cycle through to check progress and approve/deny permission requests ### Git Worktrees Git worktrees allow you to check out multiple branches from the same repository into separate directories: 1. Create worktrees: `git worktree add ../project-feature-a feature-a` 2. Launch Claude in each worktree: `cd ../project-feature-a && claude` 3. Create additional worktrees as needed ### Headless Mode with Custom Harness `claude -p` (headless mode) integrates Claude Code programmatically into larger workflows. There are two primary patterns: 1. **Fanning out** handles large migrations or analyses 2. **Pipelining** integrates Claude into existing data/processing pipelines </div> <div class="callout" data-callout="success"> <div class="callout-title">Key Takeaway</div> <div class="callout-content"> Claude Code's flexibility allows it to adapt to your specific workflow and codebase. By customizing your setup, leveraging the right tools, and following these best practices, you can significantly enhance your productivity and code quality. The most successful users actively collaborate with Claude, providing clear instructions and course-correcting as needed. </div> </div>