Claude Code Best Practices — A Checklist — Claude Code

Summary#

This is the one-page reference. Fifteen habits, ordered roughly by how early in your Claude Code adoption you encounter the pain they remove. Each one is elaborated in its own writeup — links inline. Read the page once end-to-end, then bookmark it. The compounding effect of running all fifteen is much larger than the sum.

A working summary you can paste into a teammate’s CLAUDE.md or onboarding doc: Start with CLAUDE.md. Use plan mode for non-trivial tasks. Be specific. Verify after every step. Commit small. Watch the context window. Hooks for risky ops. Close the loop.

Why it matters#

The 15 habits below are the ones that separate week-one frustration from month-three flow. Most of them are small — “always read the diff,” “commit small,” “use slash commands for repeated workflows” — but the cumulative effect is huge. A team that runs eight of fifteen is roughly twice as productive with Claude Code as one that runs three.

Beyond raw productivity, the checklist serves three operational purposes:

Onboarding. New teammates land here, read it, and skip a month of trial-and-error.
Audit. During a retro, “did we hit the checklist?” is a faster diagnosis than re-reading every session.
Calibration. When something feels off — a long session went sideways, a refactor produced churn — work down the list and find the habit you skipped.

How it works#

1. Start with CLAUDE.md#

CLAUDE.md is auto-loaded into every Claude Code session run in the project root. It is the highest-leverage customisation point in the entire system. Put project conventions, naming rules, “don’t use this library,” “deploys go via X,” and any other repeated context in there. The rule of thumb: if you’d write the same caveat twice in two different sessions, it belongs in CLAUDE.md.

Expanded in CLAUDE.md and Memory Files.

2. Use plan mode for non-trivial tasks#

Plan mode disables all side-effecting tools; Claude can read, search, and reason, but cannot edit. The output is a structured plan you review before execution. Use plan mode for anything spanning more than three files, any schema or migration work, and any refactor where the destination is the question.

Expanded in Plan Mode.

3. Be specific; show examples#

Vague prompts burn tokens on rework. Name files, name functions, name what “done” looks like. Show before/after examples for structural changes. The opening prompt should leave no room for a wrong interpretation. If a senior teammate would need three clarifying questions, your prompt is three examples short.

Expanded in Advanced Prompting Strategies.

4. Break complex tasks into stages#

Don’t ask for a full migration in one prompt. Stage it: “First, list every call site of oldFunction. Then propose a replacement signature. Then migrate one call site as a proof. Then the rest in batches.” Stages give you checkpoint commits and let Claude verify each stage before drifting in a later one.

Same principle that underlies Plan Mode.

5. Read the diff before accepting#

Claude is not infallible. The diff is the source of truth, not the natural-language summary. Skim every accept-edits cycle; read every diff before a commit. The cost of one second of skimming is much less than the cost of merging a wrong edit that takes 20 minutes to track down.

6. Run tests after every meaningful change#

Closing the loop on a change means: read the diff, run the relevant tests (or the type-checker, or a smoke test), and confirm green before moving on. Claude can run the tests itself — pnpm test, cargo test, whatever — and report back. If you keep the test loop tight, the conversation loop tightens with it.

7. Commit small#

Small green commits are cheap save points. They turn “Claude got the third file wrong” from a 30-minute recovery into a single git checkout. They also let you review your own Claude Code session weeks later by reading the commit log. A useful rule: commit at every green checkpoint, not when the whole task is done.

8. Use sub-agents for parallelism#

When you need three independent searches, three independent reviews, or three independent code-paths examined, spawn sub-agents in parallel rather than running them serially in the main thread. Sub-agents also protect the main session’s context window — large research drops live in the sub-agent, not in your main loop.

Expanded in Sub-Agents.

9. Use slash commands for repeated workflows#

When you find yourself typing the same prompt three times in three sessions, it’s a slash command. Markdown file in .claude/commands/, immediate value. Team-shared slash commands compound — one well-written /release-notes saves the whole team time every Friday.

Expanded in Slash Commands and Writing Custom Slash Commands.

10. Use the Task tool for hands-off background work#

Long greps, slow builds, batch operations — give them to the Task tool and let them run in the background while you keep typing. The harness will notify you when they finish. No polling, no sleeping; the notification is the signal. This is the single biggest unlock for productivity in long sessions.

Expanded in The Task Tool — Background Work.

11. Watch the context window#

Past ~150K tokens, retrieval gets fuzzy and the model starts to skim early context. Long sessions need a strategy: summarise mid-session, write key decisions to memory, or start fresh with the summary as input. The hard limit is the soft limit minus your margin for safety.

Expanded in Context Window and Token Budget and Long-Running Sessions and Context Management.

12. Steer mid-task — interrupt early, restart when noisy#

When Claude takes a wrong direction, hit Escape, add the missing constraint in one sentence, resume. Catch wrong turns at the first wrong file read, not at the final diff. Past three corrections in one session, scrap and restart — the cumulative drift makes everything noisier than a clean re-prompt would be.

Expanded in Guiding the Conversation Mid-Task.

13. Set up hooks for security-critical commands#

Operations that should never run without a human eye on them — rm -rf, git push --force, anything that touches production — deserve a PreToolUse hook. The hook can block, prompt, log, or audit. Set up the security hook before the first scary moment, not after.

Expanded in Hooks Overview and Building a Security Hook.

14. Keep secrets out of CLAUDE.md and prompts#

Tokens, API keys, customer data, internal hostnames — none of it goes in CLAUDE.md (which is committed) or in prompts (which are logged). Use environment variables, gitignored .env.local files, or a UserPromptSubmit hook that scrubs known patterns before submit. The cost of leaking a secret is much larger than the inconvenience of one more setup step.

Expanded in UserPromptSubmit Hooks.

15. Finish the loop — diff, tests, commit, summary#

The end of every meaningful change has four steps in order: read the diff, run the relevant tests, commit with a clear message, and write a one-sentence summary back to yourself (or the next session, via memory). Skipping any of them costs you later. The summary in particular is what lets a long-running project survive your own forgetfulness across days.

Variants and trade-offs#

A few habits are team-shape-dependent, not universal:

Habit	Strong default	When to relax it
Plan mode	Use for anything > 3 files	Solo throwaway scripts; experimentation in scratch repos
Commit small	Every green step	Spike branches that will be squashed
Read the diff	Always	Auto-formatters and known-safe refactors (e.g. `prettier --write`)
Hooks	Mandatory for security-critical	Optional for personal repos with no destructive surface
Slash commands	After the third repeat	Solo work where the prompt is different every time

Trade-offs to be aware of:

Too much process slows you down. All 15 habits at once on a 5-minute task is over-engineering. Match the ceremony to the stakes.
CLAUDE.md drift. A 200-line CLAUDE.md is being skimmed; audit and prune quarterly. Old conventions that no longer apply are noise.
Slash-command proliferation. Five commands per teammate × ten teammates = fifty rarely-run commands. Curate as a team, not per-person.

When this is asked in interviews#

The checklist is most valuable in three situations:

First two weeks on Claude Code. Read it. Run sessions while explicitly thinking “which of the fifteen am I doing?” Within two weeks most of them are reflex.
After a session went sideways. Retrospect with the list: “I skipped plan mode” or “I didn’t watch the context window” is usually the answer.
When onboarding a teammate. Share the link. Better than re-explaining the same lessons from your own painful first month.

What Is Claude Code? — start here if you haven’t already; the foundation the checklist builds on.
The Conversation Loop — the loop the fifteen habits run inside.
CLAUDE.md and Memory Files — habit #1, deepest dive.
Plan Mode — habit #2, deepest dive.
Advanced Prompting Strategies — habit #3, deepest dive.
Guiding the Conversation Mid-Task — habit #12, deepest dive.