Claude Code: the best practices that hold up in production

CLAUDE.md is a file Claude Code loads automatically at the start of every session. It is the project's memory: the build and test commands, the conventions you cannot guess by reading the code, the known pitfalls, what must never be touched. The /init command generates a first version from the repository.

The file is versioned with the code, at the root of the repository, so the whole team shares the same context. A CLAUDE.md in a subfolder adds local rules, and a personal file in the ~/.claude folder keeps each person's preferences out of the repository.

The most common mistake is to fill it up. Every line is read again in every session and costs context; an instruction buried in three pages is an ignored instruction. Keep what the agent cannot find on its own, write it as a checkable rule ("run npm run typecheck before concluding", not "write clean code"), and delete what no longer applies. When the agent makes the same mistake twice, a line is missing.

Left to itself, a coding agent starts writing straight away. On a one-line task, that is fine. On a task that touches several files, it is the surest way to solve the wrong problem with confidence.

The order that works is well known: have it read the relevant files without changing anything, ask for a plan, review and correct it, then start the implementation, and finally the commit. Plan mode (Shift+Tab in the terminal, until the status bar shows it) makes that split explicit: the agent explores and proposes, and writes nothing until you have approved.

The plan is the cheapest moment to fix a mistake. A poor architecture choice spotted in a ten-line plan is fixed in one sentence; spotted in a six-hundred-line diff, it is paid for in review and rollback. If you cannot describe the expected result in a few sentences, the plan is not ready, and neither is the agent.

This is the practice that changes the result most. An agent that can run a test, a typecheck, a build, or compare a screenshot with a mock-up fixes its own mistakes before showing them to you. An agent that cannot hands you plausible code, and you do the checking.

So tell it how to check, in the request or in CLAUDE.md: which command, which expected result, which edge case. Test-driven development fits particularly well: have the tests written first, see them fail, commit them, then ask for the implementation without changing the tests. The agent has a fixed target, and you know when it has reached it.

Be wary of the test it writes for itself after the fact. An agent can make a test pass by weakening it, or conclude "done" on a skipped test. The definition of done has to come from you, or be frozen before the implementation.

"Add tests for foo.py" produces tests. "Add a test for foo.py covering the case where the user is logged out, without mocking the database" produces the test you needed. The precision of the request shows up in the precision of the result.

Point to files rather than describing them, paste the full error message rather than a summary, attach the screenshot or the mock-up when the subject is visual, and name the existing file whose style should be followed. The agent reads the code; it does not read your mind.

Correct early. Escape interrupts the agent mid-task without losing what has been done, and a double Escape lets you go back to an earlier message and rephrase. A correction at step three costs a sentence; at step thirty, it costs a session.

The context window is the resource that degrades fastest. Every file read, every command output, every dead end stays in it. As it fills up, the agent follows the early instructions less well and mixes up tasks.

One task per session. /clear between two unrelated subjects, rather than chaining a bug fix and a page redesign in the same conversation. /compact when a long task has to continue, to summarise the history instead of dragging it along.

For broad searches ("where is payment handled?", "who calls this function?"), hand the exploration to a subagent. It reads what it needs in its own context and reports only the conclusion. The main session keeps its room for the work that matters.

Since version 2.1.283, Claude Code starts in auto mode: a second model, the classifier, reviews actions in your place and blocks only what looks risky. In Manual mode, it asks before every file edit or command. Either way, the protection that counts is the one you write down: explicitly allow the safe, repetitive commands (lint, tests, git status) in the project settings file, and deny what must never happen, such as reading .env files or pushing to the main branch.

The option that skips every permission exists. It belongs only in an isolated container, with no secrets and no network access, not on a developer machine connected to production.

An instruction in CLAUDE.md is advice: the agent follows it most of the time. When a rule must apply every time, make it a hook, a command Claude Code runs at a precise moment (after each file edit, before a command). Formatting the code, running the linter, blocking a write to a protected folder: those are hooks, not sentences.

A diff accepted without review. The agent writes fast; the person who merges remains responsible for the code. Review it as you would a colleague's pull request, and ask a second session for a review when the change is large: an instance that did not write the code judges it better than the one that did.

Several agents in parallel before mastering one. Git worktrees let several sessions work on separate branches, and non-interactive mode (claude -p) lets you plug Claude Code into a script or a CI pipeline. That is useful once the practices above hold on a single session. Before that, it multiplies errors instead of throughput. The setup that makes them safe, a preview environment per branch, is covered in our article on multi-agent and multi-staging.

Secrets or customer data in the context. What the agent reads goes to the model. Sensitive configuration files are excluded through permissions, and production data has no business in a development repository, agent or not.

A "done" without proof. A task is not finished because the agent says so, but because the tests pass, the build succeeds, and the expected behaviour has been seen.

The practices above cross-check the recommendations published by Anthropic. No productivity figure is put forward in this article: it depends too much on the project and the team to be generalised.

Claude Code documentation, "Best practices for Claude Code", reread 20 October 2026 (Anthropic's earlier article on the subject now redirects to this page): self-verification, explore then plan then code, CLAUDE.md and /init, permissions, hooks, subagents, Escape and /rewind, /clear and /compact, non-interactive mode, worktrees. Best practices.

Claude Code documentation: memory and CLAUDE.md, permission modes, settings, hooks, reread 20 October 2026. Memory, Permission modes, Settings, Hooks.

Anthropic, "Building effective agents", 19 December 2024, reread 20 October 2026: the distinction between workflow and agent used in the introduction. Anthropic article.