Claude Code Best Practices

Claude Code has become an essential tool in my day-to-day work as a software engineer, both in my side projects and in my work at Netflix. Like many of you, I've been using LLMs in my dev workflow for some time now. In the last ~ three months, I’ve transitioned from a primarily copy-and-paste-into-chat workflow to using coding agents in my IDE.

As part of the AI working group in my org, I’ve used Cline, Roo, Aider, OpenAI Codex, GitHub Copilot, and Claude Code to examine their suitability for “enterprise engineering”. For a few AI years (i.e., 3 months), I mostly used Roo. The “custom mode” feature turns Roo into a highly customizable agentic platform, and I had written several specialized “agents” at work for various workflows. This was great, especially when Netflix pays the bills. But at home, I found my Roo sessions increasingly hitting the triple-digit territory, and my wealth advisor (Claude with a Monarch CSV file) told me I need to spend less on AI. That’s when I turned to Claude Code.

Claude Code works as a CLI tool and at first glance appears to be less customizable than Roo. In some ways, that’s true; in others, I think it’s not true (we’ll dig into that below). My initial impression of Claude was good; it’s brilliant out of the box, as good or better than other agents. However, once you integrate some best practices, Claude Code transforms into a (slightly intimidating) mini software engineer and is, in my opinion, the best coding agent available right now. Here’s how I use Claude Code:

I recommend using the Claude Max plan for Claude Code billing. However, you can also use it via the Anthropic API (though it will cost more money).

CLAUDE.md files fine-tune Claude Code to your codebase, making it noticeably more effective. You can provide important rules, examples, style guides, and other specialized context for any part of your application.

Treat CLAUDE.md files as living docs. Developers (and Claude Code) should be encouraged to update them frequently. As an AI-powered SWE, if you see Claude Code make a fixable mistake, you should update the CLAUDE.md accordingly.

Nested CLAUDE.md files

CLAUDE.md files get picked up whenever Claude Code goes into a directory where one exists. For example, if you have:

And Claude Code is looking at @SomeFile.tsx, it will pick up:
app/CLAUDE.md
components/CLAUDE.md
SomeSpecializedComponent/CLAUDE.md

I strongly recommend you take advantage of nested CLAUDE.md files. Well-structured nested CLAUDE.md files allow Claude Code to navigate through your codebase and grab enriched context as needed based on the actual work it does.

Writing Good CLAUDE.md files

DRY (Don’t repeat yourself)
Context is a valuable and limited resource. Always optimize for your context window. Nested CLAUDE.md files should reduce the context load for general prompts by providing only critical information for their specific level and then pointing to where more details can be found.

Example: If your app does A, B, C, and D, and you ask about C, the model may not need to know about A, B, and D. Your top-level CLAUDE.md shouldn’t explain how to do all four tasks — instead, provide high-level context and point to where each feature is documented (ideally in their own CLAUDE.md files).

Brevity
Try to keep your CLAUDE.md files to a maximum of 100-200 lines. There will be exceptions, but long CLAUDE.md files are a code smell and take up precious context. Include only essential information for that level of the application.

XML Tags
This isn’t my idea, but I’ve found it works better. It definitely encourages consistency and clarity. Here are some common ones I use (and an example Claude Code command I use to edit CLAUDE.md files):

• <system_context> — overview and purpose
• <critical_notes> — must-know information
• <paved_path> — the canonical way
• <file_map> — where to find things
• <patterns> — common code patterns
• <example> — examples
• <workflow> — for chain of thought steps
• <common_tasks> — step-by-step guides
• <hatch> — alternative approaches
• <advanced_pattern> — complex use cases
• <fatal_implications> — for when Claude Code will not listen :P

Pointers
Make liberal usage of <file_map>/pointing to example files in your CLAUDE.md. Claude Code is smart enough to know if it should go look, and you’ll save precious context by keeping your CLAUDE.md cleaner. Ex:

Examples
LLMs love examples. You can provide code examples, input/output examples, or point to examples:

File tagging
Use @ syntax to tag files. Claude Code does not make an index of the codebase, so when asking a question, you’ll save time and context by pointing to relevant files. Here’s a real prompt I used in a side project:

Parallel Agents
Claude Code will often spin up parallel agents to read files. You can force this by telling it: "...use parallel tasks/agents..." in your prompt.

You can also run:
claude config set -g parallelTasksCount N, where N is a number. This is a great way to analyze large codebases to generate CLAUDE.md files.

parallelTasksCount is currently an undocumented feature, but you can force more parallelization by setting this config.

From monitoring context usage, I’ve gathered that Claude Code has a “main agent,” and these subagents get their own context to perform their task. If you have well-structured nested CLAUDE.md files, you can squeeze maximum context efficiency for surprisingly large tasks with parallel subagents.

Typically, my workflow is to spawn parallel agents in plan mode, with the main agent’s task being to synthesize findings and create a plan. Based on that plan, I’ll then iterate with the main agent before kicking it off to edit-mode.

Images

Prompt: Can you fix this dropdown border to match the control pane border when selected?

Claude Code is super powerful with images. It understands them well, and you can just drag and drop them in—you can even annotate them! I’ve taken screenshots and circled areas that I wanted changed, and Claude Code will often one-shot the fix. In this example above, I didn’t like the border on the dropdown input not matching.

You can also use playwright MCP (Model Context Protocol) (more on this in Advanced Usage) for a live UI development loop, (perhaps with a custom command), tell Claude Code to implement, launch, screenshot, compare to reference shot, repeat until completion.

General Prompt Engineering Tips

• Use // CLAUDE TODO:
  I use these to mark ephemeral context for Claude Code. It’s a great way to black box functions, mark bugs, or mark refactors. I instruct my Claude Code to search for these first.
• Use /compact at around 20-30% available context
• Shift+Tab into Plan Mode mode before implementation
• Use "ultrathink" in your prompts to force Claude Code to think deeper
• Use !to enter bash mode and run a command in Claude Code’s context window
• Use dictation (I use superwhisper, others are good too)

Claude Code supports /slash-commands that allow you to access saved prompts. I use commands for repeatable workflows, QA, document generation, and more. They’re a super powerful tool to save and reuse highly specialized prompts.

You save these prompts in .claude/commands/<command-name>.md and can call them from your chat prompt with /<command-name>. Some example commands:

• /add-question-to-form <question-details>: a command to add a question to a form. Defines required information, exact steps, MCP calls, and instructs Claude Code to ask clarifying questions if anything is missing/unclear.
• /monday-summary: a command that uses scripts/mcp to pull Slack messages, Jira tickets, PRs, custom scripts, and personal todos to generate an executive summary of the week ahead (non-repo specific).

Claude Code supports remote and local MCP servers. MCP servers give Claude Code access to external tools and services. These can be very powerful (and very dangerous). Be very careful with MCP servers, especially in an enterprise environment.

You can add remote MCPs easily via the command line:
claude mcp add context7 — npx -y @upstash/context7-mcp

For more information on how to add MCP servers, check out the Claude Code Docs.

Alternative to MCP
MCP is most useful when you don’t have to maintain it. Alternatively, I prefer to write bash scripts (or any program really) and describe how to use it to Claude Code. This often allows me to iterate more quickly and retain complete control over what the tools can do. Here are some examples of scripts I’ve written:

• getSlackMessagesFromChannel <channel_name> <from_date> <to_date> — gets cleaned messages from a Slack channel for a given timeframe
• broadcastBuild — runs the app, sets up ngrok tunnel, sends a notification
• sendMail/getMail — script wrapper around testmail.app

Git Worktrees

You can use git worktrees to run parallel instances of Claude Code on different branches in your repository. I typically use git worktrees when I want to test out different prompts for the same task.

Then you can run claude in each directory and test it however you like. Once you choose a winner, just merge it into your branch and clean up:

The Anthropic docs cover setting up Git Worktrees.

QA Agent

I’ve been using Claude Code as a QA agent, and it’s unsurprisingly very good.

claude mcp add playwright — npx -y @playwright/mcp@latest

Then, you can tell Claude Code to use playwright. Pro-tip: create a command .claude/commands/qa-<flow>.md for each flow you want to test. Include entry point, test account info (if applicable, user persona, and report formatting. Claude Code will take screenshots, read HTML, and determine what to do. The nice part about QA is that you really shouldn’t provide a ton of context, since a new user won’t have that context.

For my QA agent flow, I want it to be more empowered and usable in a feedback loop with a coding agent. I typically add the Sentry MCP:

claude mcp add sentry — npx -y @sentry/mcp-server@latest — access-token=\”$SENTRY_ACCESS_TOKEN\” — host=myhost.sentry.io

and will instruct it to check Sentry if it runs into an error. If nothing’s there, I tell it to run a script that gives a tail of the runtime logs, then provide as much context as possible in their QA report.

I’ve included a basic QA command example in the Appendix.

Side note: I’m fascinated by the QA agent space, and would love to work on something open-source. Please reach out if you’re also interested or know of a good project.

YOLO

Sometimes the stakes are low or the risks are asymmetric. In that case, you can let Claude Code run wild with:

claude --dangerously-skip-permissions

I don’t recommend doing this at work, and if you do it outside of work, be sure to execute it in an isolated environment, like the one Anthropic recommends.

This mode is useful for internal tools or wild ideas. I’ve used this mode to create several free versions of paid tools.

.claude/commands/qa-agent (gist):

.claude/commands/claude-editor (gist):