Effective Prompting with Claude

context management

A conversation has a finite context window. Long sessions eventually get automatically summarized so older turns don't just disappear — but a summary loses detail, so for a genuinely large task it's often better to conclude and start a fresh session with a short, deliberate recap than to let one conversation run indefinitely.

the same request, two ways

Vague:

Fix the bug in the login flow.

Well-scoped:

The sign-in form at /signin redirects to /dashboard instead of
showing "invalid password" when credentials are wrong. Look at
src/auth/login.ts -- probably the catch block around the fetch
call. Don't touch the signup flow, it's unrelated.

Both describe the same bug. The second one answers three questions the first leaves Claude to guess: what's actually broken (not "a bug," a specific wrong redirect), where to start looking, and what's out of bounds. Guessing wrong on any of those costs a full round trip; stating them up front costs one extra sentence.

iterative refinement

Treat the first response as a draft, not a verdict. Correcting course early ("that's close, but do X instead") is far cheaper than letting a wrong assumption compound across several more turns before flagging it — the same principle as catching a bug at the first failing test instead of the tenth.

claude.md: instructions you write

A CLAUDE.md is read automatically at the start of every session — the place for what you'd otherwise re-explain: build/test commands, conventions the linter won't catch, which directories are off-limits. Add to it when Claude makes the same mistake twice, or you type the same correction two sessions in a row.

File	Scope
`./CLAUDE.md`	the project — committed, shared with the team
`~/.claude/CLAUDE.md`	you, every project
`./CLAUDE.local.md`	you, this project only — gitignore it

Keep it under ~200 lines — longer files consume more context and reduce how reliably Claude follows them. Run /init to have Claude read the codebase and generate a starting file; concrete beats vague ("use 2-space indentation," not "format code properly"). It survives /compact (re-read from disk automatically), but a stale CLAUDE.md that contradicts the actual codebase is worse than none at all.

# Build & test
npm run dev          # local server on :3000
npm test -- --watch

# Conventions
2-space indentation, no semicolons.
Components live in src/components/, one per file.

# Off-limits
Never touch src/legacy/ -- scheduled for deletion, not worth fixing.

auto memory: notes claude writes itself

A second, complementary system: Claude saves its own notes as it works — build commands it discovered, debugging insights, a preference you stated once ("always use pnpm, not npm"). Unlike CLAUDE.md, you don't write this; Claude decides what's worth keeping. It lives at ~/.claude/projects/<project>/memory/, shared across every worktree of the same repo, with a MEMORY.md index (only its first 200 lines / 25KB load automatically) pointing at topic files that load on demand.

Run /memory to browse, edit, or turn it off. Since it's plain markdown, nothing about it is hidden — if Claude misremembered something, just open the file and fix it.

The two aren't interchangeable — they answer different questions:

	`CLAUDE.md`	Auto memory
Who writes it	you	Claude, as it works
When it loads	in full, every session	on demand, via the `MEMORY.md` index
Good for	standing rules that never change: build commands, conventions, off-limits paths	things learned along the way: a preference stated once, a gotcha hit mid-session
Edit it	any text editor, committed with the repo	`/memory`, or open the markdown files directly

A quick rule of thumb: if you'd write the same instruction for a new teammate on day one, it belongs in CLAUDE.md. If it only became true after watching Claude actually work in this codebase, let auto memory pick it up.

plan mode

For a non-trivial task, plan mode has Claude propose an approach and get it approved before touching any files — worth using whenever a wrong first guess about architecture would be expensive to unwind. For a small, obvious change, skipping straight to implementation is faster and plan mode would just be overhead.

common ways sessions go sideways

Letting a wrong assumption ride. Noticing the approach is off but waiting to see where it goes "just in case" almost always costs more than stopping immediately — the same reasoning compounds into the next few steps before you get another chance to redirect.

One session for every unrelated task. Context from an earlier, unrelated task doesn't just sit there quietly — it competes for space with the task in front of you and can bias answers toward the wrong problem. A fresh session per unrelated task is cheap; a confused one isn't.

A CLAUDE.md that says something false. An instruction that no longer matches the codebase (a renamed script, a dropped convention) doesn't just get ignored — Claude follows it and produces something wrong with total confidence. Stale beats vague for how convincingly it fails.

Treating memory as a transcript. Auto memory is for durable facts worth recalling next time, not a running log of what happened today. Session-specific details belong in the conversation, not in a memory file that will still be read months from now.

when instructions aren't being followed

CLAUDE.md and memory are both context, not enforced configuration — Claude reads them and tries to comply, but nothing guarantees it. First check /context to confirm the file you expect actually loaded; if it did and Claude still isn't following it, the instruction is probably too vague, or contradicted somewhere else in the tree. For anything that must happen every single time regardless of what Claude decides — run the linter before every commit, no exceptions — that's not a prompting problem at all, it's what hooks are for.

reference

platform.claude.com — prompt engineering overview
code.claude.com — memory