Claude Code Best Practices for Engineering Teams

Give Claude a check it can run

A check is any signal the agent can read: a test suite, a build exit code, a screenshot comparison, a lint command, a generated file diff, or a script that validates output. Without that signal, Claude can only stop when the work appears done.

The check should be proportionate. A typo fix may only need a build. A parser change needs focused fixtures. A UI change needs visual inspection. A data migration needs dry-run output and rollback notes.

Primary-source anchor: Anthropic recommends giving Claude Code tests, builds, screenshots, or other checks that close the loop.

Defaults as of 2026-09-19

Know which model and effort level your sessions actually run

Model and effort defaults are engineering configuration, not trivia. They set the cost of a session, how long a task can run before it stalls, how much of a repository the agent can hold, and how much latency a reviewer waits through. A team that has not checked its defaults since mid-2026 is budgeting against the wrong numbers.

Claude Fable 5.1 (`claude-fable-5-1`) shipped on September 1, 2026 and is the most capable generally available model. Its default effort is High in Claude Code, and Medium on Claude.ai and Cowork, so the same model behaves differently depending on the surface you invoke it from. Assume High effort when you estimate Claude Code cost or runtime, and do not carry a Claude.ai impression of the model into a CI budget.

Claude Opus 5 (`claude-opus-5`) shipped July 24, 2026 and is the sensible starting point for most workloads. Anthropic also offers a Fast mode for Opus 5 at roughly 2.5x speed for 2x the base price, available on the platform and through Claude Code usage credits. Fast mode is worth considering for tight interactive loops where a reviewer is waiting; it is rarely worth it for an unattended CI job where wall-clock latency costs nothing.

Claude Opus 4.8 is legacy. If your CLAUDE.md, CI workflow, SDK call, or internal runbook still pins Opus 4.8 as the current Opus, that is a stale reference to fix. The same applies to any note claiming Sonnet 5 introductory pricing would rise on September 1, 2026: it did not, and $2/$10 per million tokens is now the standard rate.

• claude-fable-5-1Fable 5.1. $10/$50 per MTok, 1M context, 128K max output, adaptive thinking always on. Default effort High in Claude Code. Cache reads are 2.5% of base input, so a well-structured agent loop gets materially cheaper.
• claude-opus-5Opus 5. $5/$25 per MTok, 1M context, 128K max output, default effort high. Fast mode runs ~2.5x faster at 2x base price via platform access or Claude Code usage credits.
• claude-sonnet-5Sonnet 5. $2/$10 per MTok, 1M context. The balance option for high-volume or routine agent work. The introductory rate became the standard rate.
• claude-haiku-4-5Haiku 4.5. $1/$5 per MTok, 200K context. Fastest and cheapest; useful for narrow mechanical subagent tasks, not for long-horizon repository work.

Primary-source anchor: Anthropic's Fable 5.1 announcement states the default effort level is High in Claude Code and Medium on Claude.ai and Cowork; the models overview carries the current IDs, prices, and context limits.

Treat a model change like a dependency upgrade

Moving a repository or a CI workflow to Fable 5.1 is not a drop-in swap. Anthropic documents breaking changes relative to Fable 5: forced tool use raises errors, earlier models cannot read Fable 5.1 thinking blocks, and editing an earlier turn invalidates thinking. Any harness that rewrites history, replays transcripts across models, or forces a specific tool needs a test pass before you switch defaults.

Opus 5 added a beta for changing the tool set mid-conversation without invalidating the prompt cache. For long agent sessions that previously had to restart to gain or drop an MCP server, this removes a real source of wasted tokens. Treat it as a beta: verify cache behavior on your own traffic before you assume the savings.

The safe rollout is the one you already use for dependencies. Pin the model explicitly in the workflow that matters, change it in a single reviewable PR, run the repository verification command, compare cost and wall-clock on a representative task, and write down what you observed.

• Grep the repo for pinned model IDs in CI, SDK calls, settings, and docs.
• Remove any reference to Opus 4.8 as the current Opus.
• Run one representative task on the new default and record cost and duration.
• Re-test any harness that forces tool use or replays earlier turns.
• Update CLAUDE.md or the team runbook only after the numbers are in hand.

Primary-source anchor: the Fable 5.1 platform overview lists the breaking changes for forced tool use, cross-model thinking blocks, and edited earlier turns, along with the additive betas for per-message effort and progress updates.

Separate exploration from implementation on complex work

For small edits, a direct instruction is fine. For multi-file or unfamiliar work, ask Claude to inspect the repo, summarize the relevant paths, and propose a plan before changing files. This prevents the common failure mode where the agent solves a plausible problem instead of the actual one.

Plan mode is especially useful for auth flows, billing logic, data mutation, generated code, build systems, and large UI surfaces. The plan should name files, tests, risks, and the exact stop condition.

• Explore the code and tests that already exist.
• Explain the intended change in repo-specific terms.
• Name the files likely to change.
• Name the checks to run.
• Then edit.

Manage context as a scarce engineering resource

Claude Code sessions accumulate conversation, file contents, command output, instructions, and loaded extension content. Long sessions can become noisy. Use concise CLAUDE.md files, clear task boundaries, and fresh sessions for unrelated work.

When an investigation would require reading many files, split it: use a subagent if the tooling allows it, or use a separate worktree/session. The goal is to keep the main conversation focused on decisions and implementation.

Primary-source anchor: Anthropic describes the context window as containing conversation history, file contents, command output, CLAUDE.md, memory, skills, and system instructions.

Choose the right extension for the job

Use CLAUDE.md for project facts that apply every session. Use skills for reusable procedures and domain knowledge that should load only when relevant. Use hooks for actions that must happen deterministically. Use MCP when Claude needs direct access to external systems. Use subagents when a task benefits from isolated context.

Do not turn every preference into every mechanism. If a rule is advisory, use instructions. If a rule must block the agent, use a hook. If a workflow is occasional, use a skill. If the data lives outside the repo, consider MCP.

Primary-source anchor: Anthropic's extension overview compares persistent context, skills, code intelligence, MCP, subagents, agent teams, hooks, and plugins by goal.

Keep the human in the merge path

Claude Code can create diffs, run checks, and prepare commits. The merge decision still belongs to a human or an explicit organizational gate. Make the final report mechanical: changed files, tests run, failures seen and fixed, residual risk, and out-of-scope items.

For higher-risk work, add an adversarial review step. That can be another Claude session, a human reviewer, or a CI job that tries to disprove the result. The point is to separate authoring from acceptance.