Context is everything. Too little and Claude makes wrong assumptions. Too much irrelevant context and performance degrades. Managing this well is the difference between Claude being frustrating and Claude being genuinely useful.

CLAUDE.md Files

The /init command analyses your codebase and creates a CLAUDE.md file. Its contents are included in every request, so it should contain the minimum information Claude needs: common commands, code style rules, key architectural patterns, and critical file paths.

Keep CLAUDE.md concise. Under 150 lines is ideal. It's loaded on every request, so 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: High-level map of the codebase — key directories, entry points, important files
• WHY: Business context — what are we 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 is concrete. "Follow best practices" is useless. "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

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." Each correction compounds: today's fix becomes tomorrow's default. 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

The shortcut: 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

• @filename — Mention specific files to include in a request. Tab completion works. This is cheaper and more reliable than asking Claude to search for files.
• # (memory mode) — Add 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. "Always use TypeScript strict mode." You write these rules.
• MEMORY.md is descriptive — it records what Claude has learned. "This project uses Apollo Client 4." Claude updates this automatically.

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

Both persist across sessions. 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, allowing sessions to run for hours.

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:

.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. 500 unnecessary lines × 100 requests in a session = you've paid for 50,000 lines of text Claude didn't need.
• @filename is cheaper than "find the file that handles auth." A direct reference adds one file to context. Asking Claude to search might read dozens of files first.
• /compact pays for itself. The one-time cost of summarising is far less than carrying a bloated conversation forward.

Key Takeaway

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.