Best Practices

Every individual feature in this guide works as described on its own. What separates a session that goes smoothly from one that goes sideways is usually a handful of habits that cut across all of them.

Maintain project memory like real documentation

A CLAUDE.md that's accurate and current removes guesswork from every session that follows. One that's stale actively misleads. Treat it as living documentation: update it the moment something it says stops being true, not as a someday task.

Review diffs, not just outcomes

A change that produces the right-looking result can still be solving the problem the wrong way — working around a root cause instead of fixing it, or fixing it in a way that'll break the next adjacent case. Skimming the actual diff, not just checking that the described outcome happened, catches that while it's still cheap to redirect.

Match oversight to risk

Not every task deserves the same level of scrutiny. A one-line typo fix doesn't need plan mode; a multi-file refactor near a payments system probably does. Calibrate permission modes and how much you check in real time to how reversible a mistake would be, not to a single fixed habit applied uniformly to everything.

Give the why, not just the what

"Fix the login redirect bug" and "fix the login redirect bug — users are getting locked out and contacting support" produce different judgment calls on anything ambiguous in between, because the second version tells Claude what actually matters about the outcome. The more a request explains the goal behind it, the better the judgment calls on the parts you didn't spell out explicitly.

Verify with the real thing, not a description of it

"This should now work" is not the same claim as "I ran the test suite and it passed" or "I reproduced the original bug and confirmed it no longer happens." Insist on the second kind of claim — for yourself when reviewing, and implicitly by structuring tasks so that running the actual verification (tests, a build, reproducing a bug) is part of what "done" means, not an optional extra step.

Scope one coherent task at a time

A request that bundles several unrelated changes together produces a diff that's harder to review and harder to revert if one part turns out wrong. Splitting unrelated work into separate, focused requests — even within the same session — keeps every individual change easy to reason about on its own.

Use version control as the actual safety net it is

Working in a clean git state, committing logical chunks of progress, and reviewing diffs before they land is what makes it safe to let an agent move quickly in the first place. None of the autonomy described throughout this guide trades away the ability to see exactly what changed and revert it if needed — that safety net is what makes the rest of it low-risk to rely on.

None of this is unique to AI agents

Clear task descriptions, reviewing diffs, calibrating risk, verifying claims, and small focused changes are the same practices that make any engineering collaboration go well, human or otherwise. Claude Code doesn't replace good engineering judgment — it executes a lot faster within whatever judgment you bring to how you direct and review it.