Claude Code best practices
Almost every practice worth having follows from one constraint: the context window fills up, and quality drops as it fills. The rest is consequences.
Checked against the official documentation in August 2026. These tools change quickly, so the date is part of the answer.
# Weak
implement a function that validates email addresses
# Better
write a validateEmail function. test cases: user@example.com is true,
"invalid" is false, user@.com is false. run the tests after implementing.Weak
implement a function that validates email addresses
Better
write a validateEmail function. test cases: user@example.com is true, "invalid" is false, user@.com is false. run the tests after implementing.
Without a check it can run, "looks done" is the only signal available and you become the verification loop.
# Weak
fix the login bug
# Better
users report login fails after session timeout. check src/auth/,
especially token refresh. write a failing test that reproduces it,
then fix it.Weak
fix the login bug
Better
users report login fails after session timeout. check src/auth/, especially token refresh. write a failing test that reproduces it, then fix it.
Explore, plan, code, commit
Letting the model code first produces code that solves the wrong problem. Separate the phases: read and understand in plan mode, ask for a plan, approve it, then implement, then commit. Planning earns its overhead when the change spans several files or you are unfamiliar with the code. If you could describe the diff in one sentence, skip it.
The failure patterns worth recognising
| Pattern | What it looks like | The fix |
|---|---|---|
| Kitchen sink session | One task, then an unrelated one, then back again | /clear between unrelated tasks |
| Correcting over and over | Same mistake corrected three times | After two, /clear and write a better prompt with what you learned |
| Over-specified CLAUDE.md | Rules ignored because the file is long | Prune ruthlessly, or convert the rule into a hook |
| Trust-then-verify gap | Plausible code that fails on edge cases | Provide a check; if you cannot verify it, do not ship it |
| Infinite exploration | "Investigate X" with no scope, hundreds of files read | Scope it, or send a subagent so it does not eat your context |
Two habits that pay immediately
Course-correct early. Stopping at the first wrong turn beats letting it run and fixing the result. A session where you corrected twice already has a context full of failed approaches, and a fresh session with a better prompt beats it.
Let it interview you. For anything larger than a single change, ask it to interview you first and write a spec, then start a new session to build from that spec. The time goes into making the spec precise instead of watching the implementation.
What usually goes wrong
- A reviewer asked to find gaps will find some, whether or not they matter. Tell it to report only what affects correctness or the stated requirements, or you will get abstraction layers and tests for cases that cannot happen.
- Verification by assertion is not verification. Ask for the evidence: the command, the output, the screenshot. Reading evidence is faster than re-running the check yourself.
- Hooks and CLAUDE.md are not interchangeable. CLAUDE.md is advice and a hook is a guarantee, so anything that must happen before every commit belongs in a hook.
- Long sessions are not free. When the context fills, earlier instructions start slipping, and that looks like the model getting worse rather than the window getting full.
The commands that matter
| Command | What it does |
|---|---|
/clear | Empties the context between unrelated tasks. The cheapest fix for a session that has started making things up. |
/compact <instructions> | Keeps the thread but drops the noise, when clearing would lose too much. |
Escape, twice | Once stops mid-action and keeps context. Twice opens the rewind menu, as does /rewind, restoring an earlier conversation and code state. With text already in the prompt, the second Escape clears the prompt instead. |
claude -p "prompt" | Runs non-interactively for CI, pre-commit hooks and scripts, with JSON output for parsing. |
Questions
What is the single highest-value thing to set up?
Something the model can run to check its own work: a test, a build, a linter, a script that diffs against a fixture. It converts a session you have to watch into one you can walk away from.
When is plan mode worth the overhead?
When the change touches several files, when you are unsure about the approach, or when you do not know the code being modified. For a typo or a renamed variable it is pure cost.
How do I stop it from making the same mistake every session?
That is exactly what CLAUDE.md is for. The trigger is: you typed the same correction last session too. If the rule must hold without exception, make it a hook rather than a line in a file.