RetroDeckRETRODECK

Claude Code Best Practices, Rethought: CLAUDE.md, Auto Mode, Sandboxing and Tests

Keep CLAUDE.md to what Claude cannot learn from the repo, let auto mode handle routine approvals, put anything irreversible in deny rules, confine commands with the sandbox or a cloud session, and give Claude tests, hooks and CI that return pass or fail. Prompts are guidelines; configuration is enforcement.

Why the old advice is being retired

The source here is a talk titled Rethinking Claude Code Best Practices, given at the AI Engineer CODE event in San Francisco on November 11, 2026 by Lydia Hallie, whom the event lists as a Member of Technical Staff at Anthropic working on developer relations for Claude Code. A Traditional Chinese recap by the Jerry_AI channel, published November 14, organizes it into five structures.

The argument: most Claude Code habits from the past year were workarounds for models that stopped early, missed instructions and needed approval on every step. In a session the developer did five jobs: steering, approving, saying no, checking the result, and starting the next task. When the human stops doing one of those, the model, the harness or the environment has to take it over. Anthropic's own best-practices page now frames the same idea as two kinds of instruction: the kind Claude reads and decides about, and the kind Claude Code enforces no matter what the model decides.

Steer: a CLAUDE.md that only says what the repo cannot

Claude Code loads CLAUDE.md into every session, so every line costs a little attention on every task. The docs give a two-question test before writing anything down: could Claude find this by reading the code, and would it actually go and look? If both answers are yes, leave it out.

What earns a line: the exact test, typecheck and lint commands, including how to run one test file; places where the code misleads, such as a legacy directory that looks dead but still serves production; decisions made in meetings; and anything you have corrected twice. Architecture descriptions and folder layouts can go, because current models read the repo themselves. The memory guide recommends staying under 200 lines. Run /init for a first draft, then /doctor and /doctor prompt-audit to flag lines written for older models, stale paths and contradictions.

Rules for one area go in .claude/rules/ with a paths filter, and team procedures go in skills, which load in full only when needed. The docs and the talk agree on dropping IMPORTANT, ALL CAPS and "think harder": the effort level is the real control, and piling on emphasis makes Claude over-apply a rule.

Approve: auto mode, and what its numbers mean

Interactive terminal and VS Code sessions now start in auto mode. Claude works without stopping for routine approvals while a separate classifier model checks each action before it runs. By default it targets the things a person would want stopped: piping curl into bash, production deploys and migrations, force pushes over other people's work, sensitive data sent to outside endpoints, and actions that look driven by content Claude read rather than by you. After three blocks in a row or twenty in total, it pauses and goes back to asking. When it keeps blocking something routine, describe your trusted infrastructure in plain English under autoMode.environment or autoMode.allow, or let /auto-mode-setup draft it.

The talk's headline figure, as reported in write-ups of the session, comes from an August study in which one dangerous command was planted in each tester's session: people caught 14 percent of them and auto mode blocked 89 percent. That is far better than a human clicking approve for the tenth time, but it still means roughly one in ten got through, and the study's methodology has not been published in detail. Anthropic's docs make the same point: auto mode is a judgment call that can be wrong, so your never rules belong elsewhere.

Say no: deny rules, the sandbox and cloud sessions

The talk's test for what goes where is reversibility. If a mistake can be taken back, such as wrong code that git can revert, leave it to the model. If it cannot, such as deleting uncommitted work, exposing a secret or sending data out, write a deny rule. Deny rules hold in every permission mode, including auto and bypassPermissions, and they are checked before the classifier sees anything. Read(./.env) also catches cat .env, but not a script that opens the file.

That gap is why the sandbox exists. Permission rules decide whether a call runs, not what it touches afterwards, and a harmless-looking npm test runs dependency code that could read anything. Turning on the sandbox with /sandbox confines shell commands and their child processes at the operating system level on macOS, Linux and WSL2, picks up your Read deny rules and domain rules, and can restrict network access. Per the talk, paths like ~/.ssh still need their own rule.

The end state the talk prefers is a cloud session: a disposable machine with a clone of the repo, no local secrets, and egress limited by default, so the worst case is a discarded environment.

Check and start: give Claude a pass or fail signal

Claude stops when work looks done. Without something that returns pass or fail, you become the test suite. Put the test command in CLAUDE.md, ask for evidence such as the command and its output, and escalate as needed: a prompt ("keep going until the auth tests pass"), /goal, which has a separate model check a condition after every turn, or a Stop hook, which the harness enforces. The talk stresses the exit code: only exit code 2 sends Claude back to work, while exit code 1, which most test runners return on failure, lets the turn end. A PostToolUse hook can run the formatter after every edit, and /code-review reviews the diff in a fresh subagent that never saw the reasoning behind it. The talk calls CI the most important piece, and recommends human review in proportion to risk.

The last job, starting work, is moving too: /loop repeats a prompt in a session, /schedule creates cloud scheduled tasks, and the talk describes an orchestrator session that splits a project into threads and rejects anything unfinished.

One gap remains between a short CLAUDE.md and a model that reads the repo: knowledge that is too large for the file and not in the code at all, such as runbooks, specs and past incident notes. A retrieval server over MCP fills it. RetroDeck's RDK indexes those documents as encrypted private chunks, and agents get a few hundred tokens of relevant context instead of whole files, which cuts token spend by 80 to 90 percent on repeated or reference-heavy work.

Frequently asked questions

What should go in CLAUDE.md under the current best practices?
Only what Claude cannot work out from the code: exact test, typecheck and lint commands, places where the code misleads, decisions made outside the repo, and anything you have corrected twice. Leave out architecture and folder layout. Keep it under about 200 lines, move area-specific rules to .claude/rules/ and team procedures to skills.
Is auto mode safe enough to leave on in Claude Code?
For routine work it is safer than approving every prompt by hand, because a classifier checks each action and blocks risky categories by default. It is still a model making judgment calls. The figures reported from the talk show about one in ten planted dangerous commands got through, so anything irreversible should also be covered by a deny rule or hook.
What is the difference between deny rules and the Claude Code sandbox?
Deny rules match tool calls and decide whether a call runs, in every permission mode. The sandbox limits what a shell command and its child processes can read, write and reach on the network, at the operating system level. A deny rule on .env stops cat .env; only the sandbox stops a test script from opening it.
Why does a Stop hook sometimes fail to send Claude back to work?
Claude Code treats only exit code 2 from a Stop hook as a block. Most test runners exit with code 1 on failure, which lets the turn end anyway. Wrap the command so failure exits with 2 and print the errors to stderr, which is what Claude receives as the reason it cannot finish yet.