# Claude Code best practices: a practical checklist

URL: https://agentvera.dev/en/blog/claude-code-best-practices/ · Published: 2026-10-27

Claude Code best practices that hold up in real projects: a short CLAUDE.md, plan first, give it a check to run, small tasks, /clear, permissions, hooks and worktrees.

**In short:**

- Keep CLAUDE.md short and limited to what Claude can’t learn from the code: the test, typecheck and lint commands, misleading spots and decisions that live outside the repo.
- Give every task a check Claude can run: a test, a typecheck, a build. Ask for the command and its output as evidence, and enforce must-pass checks with a Stop hook.
- Work in small, specific tasks, /clear between unrelated ones, put hard rules in deny rules and hooks, and give parallel work its own git worktree.

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

| # | Practice | The one-line version |
| --- | --- | --- |
| 1 | Short `CLAUDE.md` | Commands, gotchas and decisions only |
| 2 | Specific prompts | Symptom, location, how to prove it’s fixed |
| 3 | Plan first | Plan mode or a written spec for anything multi-step |
| 4 | A check to run | Tests, typecheck, lint; ask for evidence |
| 5 | Small tasks | One goal per session, `/clear` between tasks |
| 6 | Hard rules in config | Deny rules, hooks, sandbox |
| 7 | Steer early | `Esc`, `/rewind`, and `/clear` after two failed corrections |
| 8 | Subagents on purpose | Parallel work and fresh review, not by reflex |
| 9 | Worktrees for parallel work | One checkout per session |
| 10 | Review and commit | Read the diff, commit small, push yourself |

## 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:

```markdown
# 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](/en/blog/claude-md-agents-md/ "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:

```text
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:

```text
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](/en/blog/prompts-for-ai-coding-agents/ "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:

```bash
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](/en/blog/claude-code-plan-mode/ "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`:

```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](/en/blog/claude-code-context-window/ "Claude Code context window").

## 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:

```json
{
  "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:

```json
{
  "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](/en/blog/claude-code-hooks-guide/ "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](/en/blog/claude-code-skip-permissions/ "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`:

```markdown
---
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:

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

More patterns are in [Claude Code subagents](/en/blog/claude-code-subagents/ "Claude Code subagents").

## 9. Run parallel work in worktrees

Two sessions editing one checkout will overwrite each other. Give each its own [git worktree](/en/glossary/git-worktree/ "What is a git worktree"):

```bash
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:

```text
.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](/en/blog/git-worktree-parallel-agents/ "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](/en/blog/claude-code-headless-mode/ "Claude Code headless mode").

## Doing it with AgentVera

Most of this checklist is about discipline; [AgentVera](/en/agents/claude-code/ "Claude Code in AgentVera") makes a few items easier when you run more than one session. Each pane in the [workspace](/en/features/workspace/ "AgentVera 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](/en/features/agent-coordination/ "Agent coordination") warns when two agents edit the same file.

For item 4, [automatic code review](/en/features/code-review/ "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](/en/features/verify/ "AgentVera 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](/en/features/checkpoints-and-replay/ "Checkpoints and session replay") 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](/en/download/ "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.

## Frequently asked questions

**What is the single most useful Claude Code habit?** Giving Claude a way to check its own work. Put the exact test, typecheck and lint commands in CLAUDE.md, name the check in your prompt, and ask for the command and its output when Claude says it’s done. Without a check, “done” only means Claude stopped.

**How long should CLAUDE.md be?** Short. Claude Code loads it into every session, so every line costs a little attention on every task. The official memory guide recommends staying under 200 lines. Run /init for a first draft, then mostly delete: keep commands, gotchas and decisions that aren’t visible in the code.

**Should I use /clear or /compact?** Use /clear between unrelated tasks; it costs nothing and the next task stops paying for the old history. Use /compact with a focus, such as “/compact keep the API changes and the test commands”, when you want to continue the same task with a shorter history.

**Is it safe to let Claude Code run commands without asking?** As of October 2026, interactive sessions start in auto mode, where a classifier reviews risky actions. That is a judgment, not a hard rule, so anything that must never happen belongs in deny rules, hooks or the sandbox. Shift+Tab switches to Manual mode if you want to approve every step.

**How do I run several Claude Code sessions at once without conflicts?** Give each session its own git worktree, for example with claude -w feature-auth. Each worktree is a separate checkout on its own branch, so edits can’t collide. List gitignored files such as .env in .worktreeinclude so they are copied into new worktrees.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/