Claude Code Best Practices: 20 Tips from Production Deployments

The most effective CLAUDE.md files read like technical onboarding documentation: they explain why the codebase is structured the way it is, what invariants must be preserved, and how decisions were made. A CLAUDE.md that just lists "always use TypeScript strict mode" is weaker than one that explains your service boundary design, your testing philosophy, and which patterns are legacy versus intentional. Claude reasons better from context than from constraints.

In a monorepo with a Python ML service, a Node API, and a React frontend, a single root CLAUDE.md gets noisy fast. Place a CLAUDE.md in each sub-directory. The root file covers repo-wide rules (branching strategy, PR conventions, security requirements); each sub-directory file covers its specific language, framework, and test patterns. Claude reads all applicable files in scope, composing them at runtime — so you get context-appropriate behavior without polluting the root.

# /CLAUDE.md (root)
## Repo Structure
- /api — Node 20, Express, Prisma ORM
- /ml — Python 3.12, PyTorch, FastAPI
- /web — React 19, Vite, Tailwind

## Global Rules
- All PRs must pass pre-commit hooks
- Never commit secrets or API keys
- Branch convention: feat/JIRA-123-short-description

# /api/CLAUDE.md
## API Service Context
- Prisma schema is source of truth for data models
- Use Zod for all request validation
- All endpoints require JWT middleware except /health

Explicitly list prohibited actions in your CLAUDE.md. This is especially important in regulated industries. A financial services client of ours added a section titled "DO NOT under any circumstances" that listed actions like modifying schema migration files, touching the secrets management module, or changing SSL certificate paths. Claude respects these hard stops because they're framed as engineering invariants, not just preferences.

Always specify how to run tests and lint in your CLAUDE.md. Without this, Claude may guess — and guessing means running npm test when you use pnpm run test:unit, or running pytest without the required --asyncio-mode=auto flag. Every minute Claude spends resolving a wrong command invocation is a minute it's not solving your actual problem.

Context window management is the discipline that separates professional Claude Code deployments from amateur ones. If a task involves reading multiple large files, making changes across multiple modules, and then running tests — that's a sub-agent task. The orchestrating agent keeps a high-level view; sub-agents handle the implementation detail. This architecture also means failures in one sub-task don't contaminate the main agent's reasoning.

When invoking a sub-agent, your prompt should specify: the specific files it has permission to touch, what "done" looks like (including how to verify), and what to do if it hits an ambiguity. A sub-agent that can wander into adjacent files and "fix things while it's there" is a sub-agent that will cause unexpected diffs and failed reviews. Scope discipline is the single biggest driver of sub-agent reliability in production.

Claude Code can run multiple sub-agents in parallel. When you're updating documentation across five service directories and none of them share state, run them concurrently — you'll complete the task in the time it takes for one. But when sub-agent B needs the output of sub-agent A (e.g., running tests after a refactor), chain them sequentially and pass outputs explicitly. Treating concurrency as the default and sequencing as the exception will cut your task completion time by 40–60% on large codebases.

A PreToolCall hook fires before Claude executes any tool — including file writes, shell commands, and API calls. Use this to add policy enforcement: check that Claude isn't about to write to a protected directory, verify the branch name follows your convention, or block rm -rf patterns entirely. One financial services client uses a PreToolCall hook to route all planned file changes through a change-log audit trail before they're executed. This isn't Claude being restricted — it's Claude operating inside your existing governance framework.

# Example PreToolCall hook (hooks.yaml)
hooks:
  - event: PreToolCall
    matcher: "tool.name == 'Write' or tool.name == 'Edit'"
    command: "./scripts/validate-write-permissions.sh"
    timeout: 5s
    on_failure: block

The single highest-leverage hook in most codebases: automatically run your test suite after every file change Claude makes. Not at the end of the session — after every individual write. This surfaces failures immediately, before Claude has moved on to writing five more files based on assumptions that break due to the first change. The feedback loop compresses from "end of task" to "after each action," which dramatically improves the quality of multi-step refactors.

Hooks run synchronously in Claude's workflow. A hook that takes 30 seconds to complete means a 30-second pause on every tool call. Validate quickly. If you need heavy validation (full test suites, static analysis), run them asynchronously and report back via a summary hook rather than blocking. Target sub-5-second hook execution for anything in the hot path. Reserve slow hooks for PostSession events that don't block iterative work.

The fastest path to production MCP integration is to expose your internal systems as read-only tools first. Claude can query your Jira board, read Confluence docs, and pull from your internal package registry without any write risk. This gives immediate value — Claude understands your project context without you pasting it into prompts — and it builds organisational confidence before you grant write access to production systems. Add write-capable MCP tools only after you've reviewed audit logging, authentication scoping, and approval workflows.

Every MCP server that accesses an external system should authenticate with the minimum permissions required. A Jira MCP tool that can only read issues in a specific project is far safer than one authenticated as a service account with global Jira admin. Scope credentials at tool registration time. This is especially critical in enterprises where MCP tool outputs may be visible in shared Claude Code sessions — the blast radius of a misconfigured tool should be bounded, not systemic.

Claude can't use MCP tools effectively if it doesn't know what they do or when they're appropriate. Add a section to your CLAUDE.md describing available MCP tools, their purpose, and when to invoke them. For example: "Use the jira-query tool to look up ticket context before implementing a feature. Never invent acceptance criteria — always read the ticket first." This transforms your MCP tools from capabilities that sometimes get used into tools that get used systematically.

In environments where Claude Code runs on systems with access to internal networks, use Claude Code's network access controls to restrict outbound traffic. Claude Code can be configured to allow-list specific hosts (e.g., your npm registry, your internal pypi mirror, your CI system) and block all others. This prevents a class of supply chain and exfiltration risks that are otherwise hard to audit. Pair this with your existing egress firewall rules rather than treating Claude Code's controls as the only layer.

Claude Code supports isolated git worktrees — separate working copies of your repository where Claude can make changes without touching your main branch checkout. For any task involving large-scale refactors, dependency upgrades, or schema migrations, have Claude work in a worktree first. You review the diff on a clean branch. Nothing touches your working tree until you explicitly merge. This eliminates the risk of interrupted long-running tasks leaving your working directory in a broken state.

In regulated industries, you need to know who ran Claude, on which codebase, with what instructions, and what changes resulted. Claude Code's session logging captures this. Route logs to your SIEM or centralised log management system. For HIPAA, SOC 2, and ISO 27001 environments, this is non-negotiable. The good news: Claude Code's session logs are structured JSON, which means they're trivially parseable by your existing log pipeline. If you need help building a Claude governance framework, this is something we implement routinely.

Different tasks benefit from different interaction patterns. For well-defined, mechanical tasks (adding tests, updating types, generating boilerplate), use Claude Code headlessly — fire and forget, review the diff. For ambiguous tasks (architectural refactors, debugging unknown failures), use interactive mode and review Claude's reasoning at each step. For documentation, use Claude Code with explicit file scope. Training your team to match mode to task type is the highest-leverage soft skill in Claude Code adoption.

CLAUDE.md should be in version control and reviewed like any other engineering documentation. When a pattern emerges that Claude gets wrong repeatedly, add it to CLAUDE.md. When a new convention is adopted (a new testing library, a new deployment pattern), update CLAUDE.md on day one. The teams with the best Claude Code results are the ones who treat CLAUDE.md maintenance as part of their engineering culture, not an afterthought. Budget 30 minutes per sprint for CLAUDE.md review.

Claude Code produces code faster than human review can keep up with — if you let it. The right mental model is Claude Code as a very fast junior engineer whose output is always reviewed before merging. Define PR policies that apply to Claude-assisted code the same as human code. Some teams add a "claude-assisted" label to PRs so reviewers know to apply slightly more scrutiny to structural decisions. This preserves the velocity gain while maintaining code quality ownership where it belongs: with your engineers.

Cycle time, PR throughput, test coverage trends, and time-to-close on bug tickets — these are the metrics that tell you whether Claude Code is working. "Engineers feel more productive" is a lagging indicator. Most teams running Claude Code at scale see a 30–50% reduction in cycle time for well-defined feature work within 60 days of a properly configured deployment. If you're not tracking baselines before you roll out, you won't be able to make the business case for expanding it. Start your measurement framework on day one.