lockstep
8 min readNaman Jain

Claude Code best practices (2026): what still matters

Anthropic's Claude Code best practices, condensed: tell Claude what it can't see, give it a check to run, enforce what can't bend, and old advice to drop.

A lot of Claude Code advice from a year ago is now wrong. Writing IMPORTANT in capital letters, telling the agent to "think harder", describing your file layout in CLAUDE.md: Anthropic's own best practices page now lists these as habits to drop.

This post condenses that page, checked on 16 November 2026, into what to do, what to enforce, and what to stop doing.

Know which instructions are guaranteed

Anthropic splits every instruction into two kinds:

  • Claude decides: your prompt, CLAUDE.md, and skills. Claude usually follows them, but there's no guarantee.
  • Claude Code enforces: hooks, deny rules, and managed settings. The harness applies them every time, whatever the model decides.

Most of the time you want Claude to decide, because it judges the code in front of it better than a rule written in advance. Use the enforced kind only for things that must always or never happen. The page's rule of thumb: if you keep adding emphasis to a CLAUDE.md line and Claude still misses it, that line belongs in a hook.

1. Tell Claude what it can't see

Claude reads code well. It finds your layout, conventions, and test framework on its own. What it can't find is what was never in the repository: a decision made in a meeting, a deploy process in someone's head, the environment variable your tests need.

Before writing anything down, ask two questions: could Claude find this by reading the code, and would it actually look? If both are yes, leave it out.

In practice:

  • Write specific prompts. Name the file, the symptom, and what fixed looks like. "Users report login fails after the session times out; look at token refresh in src/auth/, write a failing test, then fix it" beats "fix the login bug."
  • Brainstorm first when you're unsure. Ask Claude to interview you until it could write the spec, then build from that spec in a fresh session.
  • Keep CLAUDE.md short, move area-specific rules into .claude/rules/, and put team procedures in skills. See CLAUDE.md examples and Claude Code skills: 6 examples.
  • Connect the tools Claude needs over MCP instead of pasting data in. See Claude Code MCP setup.

2. Give Claude a check to run

Claude stops when the work looks done. Without a check that says whether it is done, you become the test suite. Give it something that returns pass or fail, such as a test file, a build's exit code, a linter, or a script that compares output to a fixture, and it can close the loop itself.

The page calls the command that runs your tests the single most useful line in your CLAUDE.md. Then choose how strict to be:

StrictnessHow
Claude decidesIn the prompt: "run the auth tests and keep going until they pass"
A goal/goal all tests in tests/auth pass and lint is clean; a separate model checks after every turn
EnforcedA Stop hook that exits with code 2 until the check passes
Independent/code-review, which reviews the diff in a fresh subagent that never saw your reasoning

Whichever you use, ask for evidence: the command it ran and the output. "All tests pass" alone tells you little. To review against a plan rather than hunt for bugs, ask a subagent to check the diff against your spec, and tell it to skip style, because a reviewer asked to find problems always finds something.

3. Enforce the rules that can't bend

For rules with no exceptions, such as "never edit the generated client in src/gen/", use the enforced layer:

The page adds the reverse: if you have hooks for things that are only preferences, delete them and let Claude decide.

Steer the session

No configuration replaces watching the first minute. Anthropic's advice: press Esc the moment Claude drifts, and after two failed corrections, run /clear and write a better prompt instead of a third correction.

  • Esc stops Claude and keeps the work so far.
  • /rewind, or Esc twice on an empty prompt, rolls code, conversation, or both back to an earlier point. That makes it cheap to try the bold approach first. Checkpoints cover files Claude edited with its own tools, not files a shell command changed, so they work alongside git, not instead of it.
  • /clear starts over. For every command, see the slash commands cheat sheet.

Keep cost and context down

With a 1M-token window on most current models and automatic compaction, running out of context is rare. Paying for context you don't need is not. Every request sends the whole conversation, so a session that has collected three unrelated tasks re-reads all of them on the fourth.

  • Run /usage first. On paid plans it breaks usage down by skill, subagent, plugin, and MCP server. A status line can keep context and cost visible all the time.
  • /clear between unrelated tasks. It costs nothing.
  • /compact with a focus when a session runs long, knowing compaction is itself a large request.
  • Watch background work: loops, goal checks, and subagents keep sending requests while you aren't typing.

Twelve specific tactics are in how to reduce Claude Code token usage.

Before you leave Claude running alone

Anthropic lists five questions for any unattended run:

  1. Does it know what done looks like? A goal, a spec file, or a failing test.
  2. Can it check its own work? Tests, a Stop hook, a review step.
  3. What is it allowed to touch? Permission rules, the sandbox, a worktree, one branch.
  4. What stops it? A cap on turns or spend.
  5. Where does the result go, and who signs off? A pull request and a person approving it.

For runs in CI, see Claude Code GitHub Actions. For scripts, see Claude Code headless mode.

For parallel work, give each session its own worktree with claude -w <name>, and list small gitignored files like .env in .worktreeinclude so they're copied in. The full workflow is in Claude Code worktrees.

Old advice to drop

Paraphrased from the page's own list:

Old habitWhy to drop it
Manage the context window aggressively1M-token windows and automatic compaction make running out rare. Still /clear between tasks
IMPORTANT or ALL CAPS in instructionsCurrent models follow plain lines; emphasis causes over-application. Use a hook for hard rules
Subagents to protect contextRarely needed for that now; still useful for parallel work, noisy output, and independent review
Delegating to a subagent for a better answerDoesn't improve the answer. A fresh reviewer helps; delegating isn't the same thing
"Think hard" or "be thorough"Ordinary text. Effort level is the real control; ultrathink still asks for deeper reasoning on one turn
"Keep going, don't be lazy"Usually causes over-work. Give a check to pass, or use /goal or a Stop hook
Describing architecture and file layout in CLAUDE.mdClaude reads the repo. Write only what isn't there

The one thing that's never in the repository

Anthropic's first example of what Claude can't see is a decision your team made in a meeting. That category grows with the team: product calls in Slack, exceptions approved in reviews, scope changed in a planning session. You can write a few into CLAUDE.md, but they change, and a file doesn't know when they have.

Where Lockstep fits

Lockstep captures those decisions from PRDs, Slack, and pull requests, makes each binding when its owner approves it, and briefs Claude Code on the ones that apply at the start of every session, so the agent sees them without anyone editing a file. When a decision changes, the old version is marked replaced. An opt-in check can flag code changes that may conflict with a decision; it's advisory, not a block.

Session briefings work with Claude Code today. See how it works.

Sources checked 16 November 2026

For rolling these practices out to a team, see how to roll out Claude Code to an engineering team. For choosing between extensions, see CLAUDE.md vs skills vs hooks vs subagents. For memory, see how Claude Code memory works. For permission modes, see Claude Code plan mode vs auto mode vs accept edits. For the difference between reviewing agents and vibe coding, see vibe coding vs agentic coding. For why setup matters as much as the model, see what an AI coding agent harness is. For when to use Claude instead, see Claude Code vs Claude. For other agents, see Claude Code alternatives.

Frequently asked questions

What are the most important Claude Code best practices?
Tell Claude what it can't find by reading the repo, give it a check that returns pass or fail so it can verify its own work, and enforce rules that can't have exceptions with hooks, deny rules, or managed settings. Watch the first minute of a task and stop it early if it drifts.
Should I use IMPORTANT or ALL CAPS in CLAUDE.md?
No. Anthropic's best practices say current models follow plainly worded lines, and extra emphasis mostly makes Claude over-apply the rule. If a rule can't bend, use a hook or a deny rule; if it gets lost, shorten the file.
How do I reduce Claude Code token usage?
Use /clear between unrelated tasks, compact with a focus when a session runs long, and watch background work such as loops and subagents. Check /usage, which on paid plans breaks usage down by skill, subagent, plugin, and MCP server.
Do I still need to manage the context window carefully?
Less than before. Most current models have a 1M-token window and compaction runs automatically, so running out is rare. Clearing between tasks still gives better answers and costs less.
How should I prepare Claude Code for unattended runs?
Make sure it knows what done looks like, can check its own work, can only touch what it should, has a cap on turns or spend, and sends the result somewhere a person approves, such as a pull request.

Keep reading