How to give Claude Code the right context (and what happens when you don't)

Claude works from what's in context. Get that wrong and you get wrong output — code written for the wrong version, the wrong pattern, or a codebase it doesn't understand.

Here's what actually matters.

What Claude needs before touching code

Before Claude writes anything, it should have read the files it needs to change and the files those files depend on. Not the whole codebase — the relevant parts.

Be explicit about this. "Read these files before you start" is better than letting Claude guess what's relevant. It will usually guess correctly, but when it guesses wrong, the output looks right but doesn't fit.

Versions and environment details

Claude defaults to the most common version of whatever you're working with. If you're on React 18 and haven't said so, it might write React 16 patterns. Same for Node, TypeScript config, database drivers, anything with a version that changed behavior.

The fastest fix: tell Claude to read your package.json first. That puts the actual versions in context without you having to list them manually.

What not to put in context

More context is not always better. Every token you add is a token that could push something important out of attention or slow down the response.

Don't paste entire files when you need one function. Don't include unrelated test files. Don't add documentation that doesn't affect what Claude needs to do. The question is "what does Claude need to know to do this task" — not "what's in the repo."

The difference between task context and background context

Task context: the specific files, the exact error, the current behavior vs. desired behavior. This is mandatory.

Background context: how the codebase is organized, what patterns you use, what you've decided in the past. This goes in CLAUDE.md so it doesn't need to be re-stated every session.

If you find yourself copy-pasting the same context repeatedly, that's a CLAUDE.md item.

When context goes stale

In a long session, the state of the codebase in Claude's context diverges from the actual state on disk. Claude made changes, you made changes, files were edited. The further you get from the start of the session, the more likely Claude is working from an outdated mental model.

For anything important, tell Claude to re-read the files it's about to change. Even if it read them at the start. Two minutes of re-reading beats an hour of debugging output that was based on a stale read.

The most common context mistake

Describing the problem without showing it. "The function is broken" tells Claude almost nothing. "Here's the function, here's the input, here's what it returns, here's what it should return" tells it everything it needs.

Concrete beats abstract every time.