Claude Code best practices: a practical checklist

The Claude Code best practices that matter most are simple: keep CLAUDE.md short, plan before big changes, give Claude a check it can run, work in small tasks, clear the context between them, enforce hard rules with configuration instead of prose, and run parallel work in separate git worktrees. Then read the diff and commit often.

This page is a checklist. Each item says what to do, shows the command or config, and links to a deeper guide where one exists. Everything here follows the official Claude Code documentation as of October 2026; details that change between versions are marked.

The checklist at a glance

1. Keep CLAUDE.md short and factual

Claude Code loads CLAUDE.md into every session, so every line in it takes a little attention on every task, relevant or not. The file works best when it holds only what Claude can’t work out from the code:

• How to confirm work in this repo: the exact test, typecheck and lint commands, and how to run one test file.
• Places where the code misleads: an old pattern that new code must not copy, a directory that looks dead but isn’t.
• Decisions that aren’t in the repo: which error helper the team chose, how deploys work.
• Anything you’ve had to correct twice.

A file that passes that test stays small:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

You don’t need to describe your architecture or folder layout; Claude reads the repo. /init writes a first draft, and from there the work is mostly deleting. The official memory guide recommends staying under 200 lines. /context confirms the file was loaded, and /doctor suggests cuts. Personal preferences go in CLAUDE.local.md, which you add to .gitignore.

Two related tools keep the main file lean. Rules that only matter in one area go in .claude/rules/*.md with a paths: filter, so they load only when Claude works there. Team procedures, such as a release checklist, go in a skill at .claude/skills/<name>/SKILL.md; Claude sees only its name and description until it needs the full text. The full walkthrough is in How to write CLAUDE.md and AGENTS.md.

If Claude keeps ignoring a line, writing IMPORTANT in capitals rarely helps. Either the file is too long or the line is a rule with no exceptions, which belongs in a hook (see item 6).

2. Write prompts that say where, what and how to check

A vague prompt makes Claude guess. A specific one names the symptom, where to look and how to prove the fix:

Users report that login fails after the session times out. Look at the token refresh in src/auth/, write a failing test that reproduces it, then fix it.

Point at files with @, paste screenshots, and pipe logs in instead of describing them. When you don’t know what you want yet, let Claude interview you first:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

Then start a fresh session that builds from SPEC.md. The build begins with a clean context and a written definition of done, and the spec is what the reviewer checks against later. More prompt patterns are in How to write prompts for AI coding agents.

Two habits you can drop: phrases like “think hard” don’t raise reasoning effort (use /effort high or put ultrathink in a single prompt), and ALL CAPS emphasis mostly makes Claude over-apply a rule.

3. Plan before multi-step changes

For anything that touches several files, separate thinking from editing. Plan mode lets Claude read the code and propose a plan without changing anything. You can cycle into it with Shift+Tab or start a session in it:

claude --permission-mode plan

Read the plan, correct it, and only then let Claude build. A wrong assumption caught in the plan costs one message; caught in the diff, it costs a rewrite. Small, obvious fixes don’t need a plan. The details, including how to edit a plan before approving it, are in Claude Code plan mode.

4. Give Claude a check it can run

This is the habit with the biggest payoff. Claude can only know it’s done if it has something to run: a test suite, a typecheck, a lint command, a build’s exit code, a script that diffs output against a fixture. If your repo has one, the most useful line in CLAUDE.md is the command that runs it.

You choose how strictly the check is applied:

• In the prompt. “Run the auth tests after, and keep going until they pass.” Works for any task with no setup.
• As a goal. /goal all tests in tests/auth pass and lint is clean sets a condition that a separate model checks after every turn. Most useful for long runs.
• As a Stop hook. Claude Code runs your script when Claude tries to end its turn and sends it back if the script exits with code 2.
• With an independent reviewer. /code-review reviews the diff in a fresh subagent that never saw your conversation.

The Stop hook version of “typecheck must pass” lives in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Stderr goes back to Claude as the reason it can’t stop yet, which is why the compiler output is redirected there. If the hook blocks eight stops in a row with no tool call in between, Claude Code ends the turn anyway; CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises that cap.

Whatever you choose, ask for evidence: the command Claude ran and its output. “All tests pass” on its own tells you little. After a UI change, /verify has Claude build and run the app and look at the result.

5. Keep tasks small and the context clean

One session, one goal. A conversation that has collected three unrelated tasks re-sends all of them on every turn of the fourth, which costs more and makes answers less focused.

• /clear between unrelated tasks. /clear oauth-migration also names the session you’re leaving so you can come back to it.
• /compact keep the API changes and the test commands shortens a long session while keeping what matters. On a long session /compact is itself a big request.
• /usage shows where your usage goes, including by subagent, skill and MCP server on subscription plans.

As of October 2026, most current models have a 1M-token window and compaction runs on its own, so running out of context is rare. Clearing is about focus and cost, not survival. The prompt cache lasts about an hour on a subscription and about five minutes on an API key, so a session that sat idle over lunch is more expensive to continue than a fresh one. The mechanics are in Claude Code context management.

6. Put rules that can’t bend in configuration

CLAUDE.md holds guidelines, and Claude is allowed to decide a guideline doesn’t apply. For the few rules where “almost always” isn’t enough, use controls Claude Code applies itself.

Permission rules. Allow what is safe and frequent, ask for what is risky, deny what must never happen:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Deny rules apply in every permission mode, and the Read rule also catches common file-reading shell commands like cat .env. It won’t catch a script that opens the file, so for security-sensitive work also turn on the sandbox with /sandbox, which confines shell commands at the OS level on macOS, Linux and WSL2.

Hooks. A formatter that runs after every edit no longer depends on Claude remembering:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Use hooks only for rules with zero exceptions; “prefer named exports” stays in CLAUDE.md. The Claude Code hooks guide covers every event and exit code.

Permission modes. As of October 2026, new interactive sessions start in auto mode, where a classifier reviews risky actions instead of prompting you for each one. It is good, but it is a judgment, so your “never” rules still belong in deny rules and hooks. If you’d rather approve every step, Shift+Tab cycles to Manual, or start with claude --permission-mode manual. When Manual asks too often, /fewer-permission-prompts adds your common read-only commands to an allowlist. Why skipping permissions entirely is a bad trade is covered in Claude Code skip permissions.

7. Steer early, reset instead of arguing

Watch the first minute of a task. The controls are few:

• Esc stops Claude mid-action and keeps everything so far, so you can redirect.
• /rewind, or Esc twice on an empty prompt, rolls the code, the conversation or both back to an earlier prompt.
• /clear starts over. After two failed corrections, a third mostly adds another failed attempt for Claude to re-read. Clear, and write one better prompt that includes what you learned.

Checkpoints cover files Claude changed with its own edit tools; a file only a Bash command touched isn’t restored. They work alongside git, not instead of it. For work that spans days, /rename oauth-migration names the session and claude --resume oauth-migration picks it up later.

8. Use subagents on purpose

Claude Code already delegates on its own: broad searches go to the built-in Explore agent, and subagents run in the background by default. Every subagent sends its own requests, so it costs tokens, and it doesn’t make an answer smarter. Use them for:

• Independent pieces of work that can run at the same time.
• Keeping long output, like a full test run, out of the main conversation.
• A reviewer that hasn’t seen how the code was written.
• A task that should have fewer tools than the main session.

A read-only reviewer is one short file at .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

For simple jobs such as collecting the files that import a module, add model: haiku to the definition. Then ask:

Have the reviewer compare the rate limiter against SPEC.md.

More patterns are in Claude Code subagents.

9. Run parallel work in worktrees

Two sessions editing one checkout will overwrite each other. Give each its own git worktree:

claude -w feature-auth

A worktree is a fresh checkout, so gitignored files such as .env aren’t there and dependencies aren’t installed. List small gitignored files in .worktreeinclude at the repo root and Claude Code copies them into every worktree it creates:

.env
.env.local
config/dev-credentials.json

Don’t put node_modules there; it copies rather than links. Keep the install command in CLAUDE.md instead, or use the worktree.symlinkDirectories setting. When you exit an unnamed worktree session with no changes, Claude Code removes it; otherwise it asks. For one large mechanical change, /batch splits the work into units, runs each in its own worktree and opens a PR per unit. More in Git worktrees for parallel agents.

10. Read the diff, commit small, push yourself

The agent writes; you approve. Before you accept a turn, read git diff, not the summary. Commit after every working step so a bad next step is one git reset away. Keep pushes, merges and deploys behind a person: the ask rule on git push * above does exactly that. A second session that reviews @src/middleware/rateLimiter.ts without having watched it being written is the cheapest independent reviewer you have.

Bonus: before you leave Claude unattended

The official docs list five questions for any run nobody is watching. They make a good final check:

1. Does it know what done looks like? A goal, a spec file, a failing test.
2. Can it check its own work? Tests, a Stop hook, a review step.
3. What may it touch? Permission rules, dontAsk, the sandbox, a worktree.
4. What stops it? --max-turns, --max-budget-usd, a spend limit.
5. Where does the result go, and who signs off? A PR and a person approving the merge.

For scripted and CI runs, see Claude Code headless mode.

Doing it with AgentVera

Most of this checklist is about discipline; AgentVera makes a few items easier when you run more than one session. Each pane in the workspace is the real Claude Code terminal, so Shift+Tab, plan mode, hooks and your CLAUDE.md work as usual. You can create a worktree per agent from the Git panel, and agent coordination warns when two agents edit the same file.

For item 4, automatic code review has a Claude model you choose review each turn’s changes and list findings with severity and file:line, and can send them back to the agent. Verify (Pro and Team) turns your message into acceptance criteria and has a separate verifier check them with evidence when the turn ends. For item 7, checkpoints snapshot every turn to a hidden git ref and keep the last 60 per agent. Grid, worktrees, code review and checkpoints are on the free plan; download AgentVera to try them.

Wrapping up

If you adopt only three items, take these: a short CLAUDE.md with your real commands, a check Claude runs before it says “done”, and /clear between tasks. Add deny rules and hooks for the things that must never happen, worktrees once you run sessions in parallel, and keep the final review and the push for yourself.