Tips

Best practices for working with Claude Code — CLAUDE.md, focused prompts, plan mode, context management, git worktrees, and subagents.

The tools are covered on the other pages. This one is about using them together.

Almost every problem with Claude Code comes down to one of two things: it lacks context or it has too much context. The tips below are ways to hold that balance.

CLAUDE.md

CLAUDE.md is read at the start of every session. It’s the place for the things you’d otherwise explain every time.

Generate the first version

/init analyzes the codebase and writes a draft. Don’t leave it as is — it’s a starting point.

Clean it up

Remove everything Claude can work out from the code itself. Keep only what isn’t obvious.

Maintain it with `#`

Every time you repeat an instruction, write it down with the # prefix.

What belongs in it

Belongs	Doesn’t belong
Build, test, and lint commands (`pnpm test`, not “run the tests”)	A retelling of the folder structure
Conventions that aren’t visible in the code	Things the linter already checks
Explicit prohibitions — “never touch `generated/`”	Long documentation — put it in a file and point at it
Project-specific traps	General programming advice

There are three levels, and all three are read:

~/.claude/CLAUDE.md
project/
- CLAUDE.md
- packages/
  - api/
    - CLAUDE.md

Small, focused prompts

One prompt, one task. If the sentence contains “and then”, it’s probably two tasks.

Good

“Add validation for the email field in RegisterForm and cover it with a test.”

Worse

“Fix the registration form, add tests, update the docs, and open a PR.”

Big tasks aren’t off limits — just give them plan mode or a subagent instead of firing them off directly.

Plan mode for large changes

Shift+Tab into plan mode before you start anything that will touch more than a few files.

You gain two things: you see the approach before any code is written (fixing a plan is one message, fixing code is a new session), and Claude reads the code carefully instead of typing straight away.

A prompt that hands over a decision usually beats one that hands over an instruction. “Write a function that does X” gets you X. “How should we handle X?” gets you the reasoning first — which is where the mistakes surface, while they’re still cheap to fix.

Four habits in that spirit:

Make it ask until it's sure

Plan mode does some of this on its own, but you can ask for it directly: “keep asking me questions until you’re 95% confident you understand exactly what I need.” A round of questions up front costs less than three rounds of revisions after. There’s a packaged version of this habit — the grilling skill, an interview that’s just a prompt.

Bake verification into the to-do list

When Claude plans out its to-dos, ask for the checks to be items too — build the page, then screenshot it and confirm the layout, then open the browser and confirm nothing errors. Adding “don’t move to the next item until you’re 95% confident this one is done” keeps it from sprinting past a broken step.

Cut it off early

The moment it’s heading the wrong way, Esc and re-ask. Every token spent going the wrong direction is context you don’t get back.

Push back on merely-okay output

“That works, but do a more elegant version” is a valid prompt. When the second attempt is the one you wanted, write down why — in CLAUDE.md or the relevant skill — so you don’t have to ask twice next time.

ultrathink

Typing ultrathink in a prompt raises the thinking budget before Claude answers. Worth it for architecture decisions, gnarly debugging, and large refactors — or when two normal attempts haven’t landed. Not worth it for a one-line fix; you’re paying for reasoning tokens either way.

Managing context

/clear between unrelated tasks

A new task with nothing in common with the last one — /clear. Leftovers from the previous work confuse the model. CLAUDE.md is loaded again, so you don’t lose the conventions.

/compact when the context is long

Same work, but the session has grown long — /compact. Give it instructions about what to keep: /compact keep the schema decisions and the list of remaining tasks.

Don't wait until the context runs out

Compacting in the middle of a complex step loses more than doing it earlier, at a natural boundary between tasks.

@ instead of “find the file”

Mentioning a file directly saves a search cycle and puts exactly the right thing in the context.

That’s the short version. Context and cost goes further — why a long session gets both pricier and less capable, why /rewind beats “that didn’t work, try again”, and the handoff pattern that replaces /compact.

Cache the docs you keep re-reading

When you know you’ll consult the same documentation again and again — a feature you’re adopting, a big MCP server’s API, a library you’re learning — have Claude read it once and write the summary into the repo:

Read https://code.claude.com/docs/en/agent-teams and write a reference guide
for it in docs/agent-teams.md. It'll be used to answer questions about this
feature later, so keep the configuration details and the examples.

Every later question then reads a local file instead of fetching the page again — faster, cheaper, and it survives /clear. Point CLAUDE.md at the folder (“reference docs live in docs/”) so Claude knows to look there before reaching for the network.

Git worktrees for parallel sessions

Several Claude sessions in the same directory get in each other’s way — they edit the same files and confuse one another. The answer is git worktrees: a separate working directory per branch.

Claude Code will make one for you:

claude --worktree feature-auth    # or -w

That creates an isolated workspace on its own branch and starts the session in it. Run it again in another terminal with a different name and you have two sessions on the same project that can’t overwrite each other. Add --tmux to open it in a tmux session. When you’re done, the branches merge back like any other.

The manual equivalent, if you want the directories somewhere specific:

git worktree add ../proj-feature-auth -b feature/auth
git worktree add ../proj-bugfix-123 -b fix/issue-123

You then run claude in each directory separately. Either way the sessions are fully isolated — only .git is shared.

When you’re done:

git worktree remove ../proj-feature-auth

Subagents for large tasks

A subagent works in its own context and returns only the result. The intermediate steps — the files it read, the failed attempts, the long output — never enter your session.

When it’s worth it:

Situation	Why a subagent
“Find where X happens” in a large repo	The search reads many files; you only want the answer.
Several independent changes at once	They run in parallel instead of one after another.
Research with an unclear outcome	If it finds nothing, you’ve saved your context from the noise.
Reviewing a large diff	Isolated context, isolated opinion.

They’re managed with /agents; the definitions live in .claude/agents/.

A subagent doesn’t have to run the same model as your session. For work that’s high-volume but not subtle — reading a lot of files, scraping, first-pass triage — put the subagents on a cheaper model and let the main session stay on the expensive one. You pay the low rate for the tokens that get read and the high rate only for the summary that comes back.

In short

Before the task

CLAUDE.md is current, plan mode for the big things, a worktree if you’ll run things in parallel.

During the task

Esc Esc when it goes the wrong way, /compact when the context is long, a subagent for side quests.