Chapter 2 · Part 1

Context beats cleverness

Every session starts the same way: Claude Code knows a great deal about programming and nothing at all about your repo. It can find things out — it reads files, greps, follows imports — but finding out costs time, and guessing costs you a bad diff.

Almost every frustrating session traces back to missing context, not a missing prompt trick.

It can find things — but pointing is faster

Given "the login is broken," it will go hunting: grep for "login", read a few files, form a theory. That often works. It's also slower and less certain than just saying where to look.

❌Makes it hunt

"The login is broken, can you fix it?"

✅Points it at the truth

"Login fails with a 401 for Google users only — see the handler in src/auth/callback.ts. It started after we upgraded the SDK last week. Repro: run npm test auth and watch the google callback case fail."

Same request. The second one skips the hunting phase entirely and hands it a failing test to aim at. Two things to notice: a file path and a way to reproduce. Those two ingredients turn a vague bug report into a task an agent can actually close.

💡The four things worth including
  • Where — the file, folder, or function. Paths beat descriptions.
  • What "done" looks like — a passing test, a working command, an expected output.
  • What to match — "do it like X does it" is the fastest way to get your conventions.
  • What's off-limits — "don't touch the schema", "don't add a dependency."

The context window is finite — and it fills up

Everything in a session — every file it read, every command's output, every message — occupies a context window. It's large, but it isn't infinite, and it fills faster than you'd think: one npm install log or a dumped 4,000-line file can eat a serious chunk of it.

When it fills, the session gets summarized to make room. Summaries are lossy. This is why a long session starts strong and slowly turns vague — the details it needs quietly got compressed away.

The fix is unglamorous: start fresh often. A new session for a new task is not wasted setup; it's the cheapest way to keep it sharp. Claude Code gives you a way to clear the conversation and a way to compact it — check /help for the current commands — but the habit matters more than the syntax:

  • New task? New session. Don't let a debugging session bleed into a feature.
  • Long session going sideways? Clear it, and open again with a crisp summary of where you got to. You'll usually beat the flailing session in two minutes.
  • Don't paste giant blobs when a path will do. It can read the file itself, and it can read only the part it needs.
⚠️More context isn't automatically better

Dumping the whole repo in isn't the win it sounds like. Relevant context sharpens; irrelevant context dilutes — the signal it needs is now buried in noise, and you've spent the window on files that never mattered. Point precisely.

Write the context down once

If you're typing the same background every session — "we use pnpm, not npm", "tests live next to the source", "never edit the generated folder" — that's not a prompting problem. That's a missing file.

A CLAUDE.md at the root of your repo is loaded automatically at the start of every session. It's the difference between explaining your project daily and explaining it once:

CLAUDE.md — a starter that earns its keep
# Project notes

- Package manager is **pnpm**. Never run npm or yarn.
- Tests: `pnpm test` (vitest). Tests live next to the source as `*.test.ts`.
- `src/generated/` is generated from the schema — never edit it by hand.
- We use tabs, and the linter is the source of truth: `pnpm lint`.
- Don't add a dependency without asking.

Keep it short and true. A CLAUDE.md that has drifted out of date is worse than none, because now it's confidently wrong — and it gets read every single session. Chapter 5 goes deeper on this and the rest of the setup that pays you back.

💡A useful test

If you find yourself typing an explanation you've typed before, stop. That sentence belongs in CLAUDE.md, not in this session.

Context is the foundation. With it in place, the next question is what the agent does first — and the answer should almost never be "start editing files."