Context is everything when working with Claude Code. Give it too little and it makes wrong assumptions. Give it too much irrelevant information and performance degrades. The difference between Claude being frustrating and Claude being genuinely useful mostly comes down to how well you manage this.

CLAUDE.md Files

When you run /init, Claude Code analyses your codebase and creates a CLAUDE.md file. The contents of this file are included in every single request you make, so it should contain the minimum information Claude needs to work effectively – things like common commands, code style rules, key architectural patterns, and critical file paths.

CLAUDE.md files can live at several levels, with higher levels taking priority:

Keep your CLAUDE.md concise – under 150 lines is ideal. Because it's loaded on every request, bloat costs tokens. For detailed documentation, reference files rather than inlining them.

Writing a Good CLAUDE.md

The best CLAUDE.md files follow a WHAT-WHY-HOW structure:

• WHAT: A high-level map of the codebase – key directories, entry points, important files
• WHY: Business context – what you're building and for whom
• HOW: Concrete rules – commands to run, style conventions to follow, libraries to use (and not use), plus environment details like dev server ports, required running services, and active MCP configurations

The critical word here is concrete. Something like "follow best practices" is useless because it gives Claude nothing to act on. "Always use bun run test – never npm test" is actionable. Similarly, "dev server runs on port 3000" prevents Claude from guessing, and guessing wrong.

# Project Info
This is a web application. Please follow best practices and write clean code.
Use modern JavaScript patterns. Make sure tests pass. Be careful with the
database. We use React and Node. There are many components. The API is in
the api folder. Try to keep things organised.

# Cognito Course Platform
 
## What
Next.js 14 app with MDX content pipeline. Key paths:
- `src/app/` – pages and API routes
- `src/components/` – React components (use existing UI primitives)
- `content/modules/` – course content as MDX files
 
## Commands
- `bun run dev` – start dev server (port 3000)
- `bun run test` – run test suite
- `bun run lint` – lint and format
 
## Environment
- Dev server: http://localhost:3000
- Database: PostgreSQL on port 5432 (run `docker compose up db` first)
- Required MCP: GitHub, Playwright
 
## Rules
- TypeScript strict mode, no `any` types
- Use server components by default, client components only when needed
- All new components need a corresponding test file
- Never import from `@/lib/internal` – use the public API in `@/lib`

The Compounding Engineering Habit

This is arguably the most impactful practice in the entire course.

Whenever Claude makes a mistake – uses the wrong command, picks the wrong library, ignores a convention – don't just correct it in chat. Update CLAUDE.md so it never happens again. This is called "compounding engineering," and it's exactly what it sounds like: each correction compounds over time. Today's fix becomes tomorrow's default behaviour. Over weeks and months, your CLAUDE.md becomes an increasingly precise instruction set that makes Claude's output better with every session.

Claude uses npm instead of bun →
  You correct it →
    You add "Always use bun, never npm" to CLAUDE.md →
      Claude never makes that mistake again

There's a shortcut for this: type # followed by the rule you want remembered. For example, # always use bun instead of npm. Claude adds it to CLAUDE.md automatically.

The @ Symbol and # Memory

Claude Code has two quick-reference shortcuts that are worth building into your muscle memory:

• @filename mentions specific files to include in a request. Tab completion works, and it's both cheaper and more reliable than asking Claude to search for files itself.
• # (memory mode) adds persistent notes to CLAUDE.md with natural language. Type # then describe what to remember: # always use bun instead of npm.

CLAUDE.md vs MEMORY.md

This is a subtle but important distinction. CLAUDE.md is prescriptive – it tells Claude what to do. You write these rules yourself: "Always use TypeScript strict mode." MEMORY.md is descriptive – it records what Claude has learned about your project. Claude updates this automatically: "This project uses Apollo Client 4."

CLAUDE.md  → Rules     → You write them
MEMORY.md  → Knowledge → Claude writes them

Both persist across sessions and both are loaded into context, but they serve different purposes. Don't mix rules into MEMORY.md or facts into CLAUDE.md.

Context Compaction

For long sessions, Claude Code automatically summarises older conversation when the context window fills up. This happens transparently – it preserves essential information while freeing space, which allows sessions to run for hours without hitting a wall.

You can also trigger this manually with /compact when the conversation has accumulated noise but Claude has learned valuable context you want to preserve.

Agent Memory

Agents configured with memory: project build persistent knowledge that carries across sessions:

.claude/agent-memory/code-fix-scout/
  └── memory.md  ← "Last review found missing error handling on Apollo queries"

This memory gets injected into the agent's system prompt on future runs. Over time, agents become more precise and focused on your specific codebase patterns. We cover this fully in the agents module.

Context and Cost

Context size directly impacts cost. Every message you send includes the full conversation history plus CLAUDE.md – all of it tokenised and billed.

A bloated CLAUDE.md costs you on every single request. If you've got 500 unnecessary lines and you send 100 requests in a session, you've paid for 50,000 lines of text Claude didn't need. Using @filename is cheaper than asking Claude to "find the file that handles auth" – a direct reference adds one file to context, while a search might read dozens of files first. And /compact almost always pays for itself, because the one-time cost of summarising is far less than carrying a bloated conversation forward.

What to Take Away

Context management is the meta-skill of Claude Code. A well-crafted CLAUDE.md file, the compounding engineering habit, strategic use of @ references, and aggressive /clear and /compact together determine the quality of everything Claude does for you.