Claude Code Best Practices: 18 Patterns From Production Teams

1

Write a focused CLAUDE.md, not a wiki CONTEXT

CLAUDE.md is the project-level context file Claude reads at the start of every session. Treat it like onboarding instructions to a new engineer — direct, terse, action-oriented.

Include: tech stack, where the entry points live, naming conventions, commands for build/test/lint, common gotchas, and team coding style preferences. Skip: marketing copy, history, philosophy. Keep it under 500 words.

2

Use /init to bootstrap CLAUDE.md CONTEXT

Run /init in a fresh repo and Claude will generate a starter CLAUDE.md by inspecting the codebase. Edit it down to what matters — the auto-generated version is usually too verbose.

3

Keep secrets out of context SECURITY

Anything in CLAUDE.md, file paths, or pasted into chat is part of the model's context. Don't paste API keys, customer data, or production credentials. For sensitive workflows, route through a gateway (Clarista, internal MCP proxy) that scrubs PII automatically.

4

Use plan mode before action mode WORKFLOW

For any task touching more than 2-3 files, ask Claude to plan first. Plan mode shows you what it intends to do without executing. Approve the plan, then say "go." This catches misinterpretations before they become expensive bad code.

5

Compact aggressively WORKFLOW

Long sessions accumulate context that crowds out new information. Use /compact after major milestones to summarize the conversation and reset the context budget. The trade-off: you lose detail, but you regain reasoning quality.

6

Use sub-agents for noisy tasks WORKFLOW

For codebase searches, test suite runs, or multi-file refactors, spawn a sub-agent via the Task tool. The sub-agent does the work in its own context, returns a summary, and your main session stays clean.

Good sub-agent prompts: "Run the entire test suite. Report only failing tests with the relevant assertion message. Under 200 words." Bad sub-agent prompts: "Help me with my codebase."

7

Tell Claude what success looks like WORKFLOW

"Fix the bug" is a worse prompt than "Fix the bug. Verify by running pytest tests/test_billing.py. The test should print '5 passed'." Concrete success criteria make Claude verify its own work and stop earlier.

8

Use slash commands for repetitive workflows WORKFLOW

If you run the same task more than twice, codify it as a custom slash command in ~/.claude/commands/. Examples: /release, /runbook, /migrate. The command lives in version control and the team uses the same workflow.

9

Use PreToolUse hooks to block dangerous operations SAFETY

A PreToolUse hook fires before Claude runs a tool. Use it to block rm -rf, prevent writes to /etc, require confirmation for destructive Bash. Critical for teams letting Claude run with bash access.

10

Use PostToolUse hooks for auto-format and lint QUALITY

After every file write, run Prettier / Black / Rustfmt. After every commit, run the linter. PostToolUse hooks make this automatic. Result: AI-generated code matches your codebase style without manual cleanup.

11

Use scoped credentials for every MCP server SECURITY

github-mcp gets a read-only PAT. Postgres MCP gets a read-only DB user. If a server gets compromised, blast radius is limited.

12

Track MCP configuration in Git REPRODUCIBILITY

Commit your ~/.claude/settings.json as a dotfile. When you onboard a new engineer or set up a new machine, they pull the file and they're configured. More on MCP servers and plugins →

13

Prefer plugins to one-off MCP installs REPRODUCIBILITY

Plugins are versioned bundles. Easier to roll back, easier to share. A team-published plugin beats every engineer wiring MCP servers separately.

14

Use the right model for the task COST

Haiku for routine work (formatting, simple refactors, boilerplate). Sonnet for most everyday engineering. Opus for complex reasoning, system design, architecture decisions. Don't pay Opus prices for tasks Haiku can do.

15

Set session budgets in CI COST

When running Claude Code in CI (auto-PR-review, auto-doc-generation), cap each run with --max-budget. A runaway agent can spend $50 in a single PR if uncapped.

16

Cache long-lived context COST

When calling the API directly (not the CLI), use prompt caching for content that doesn't change between calls — your CLAUDE.md, large reference files, system prompts. Cuts costs by 90%+ on cached portions.

17

Don't ship Claude Code output direct to prod SAFETY

Even with hooks and scanning, AI-generated code should go through your normal review pipeline: PR, CI, security scan, human review, staged deploy. 14-point production checklist →

18

For regulated work, run through a gateway COMPLIANCE

If your CISO has to sign off on what AI sees: route Claude Code through a governance layer (Clarista or similar) that enforces BYO LLM, scrubs PII, logs every prompt + diff, and applies policy. Native Claude Code is great for engineering productivity but doesn't include compliance infrastructure out of the box.