Context Management Intermediate

Context is king in AI-assisted development. Understanding how Claude Code reads your codebase, managing conversation length, and providing the right context at the right time is what separates good results from great ones.

How Claude Code Reads Your Codebase

Claude Code does not read your entire codebase at once. It uses tools to explore on-demand:

1. CLAUDE.md is read first

   At session start, Claude reads your CLAUDE.md file for project context, conventions, and instructions.

2. Tools are used to explore

   Claude uses Read, Grep, Glob, and Bash tools to find and read relevant files based on your prompt.

3. Context accumulates in the conversation

   Every file read, every command output, and every response adds to the conversation context window.

4. Context window has limits

   When the conversation gets too long, older context may be truncated. Use /compact to summarize and free up space.

CLAUDE.md: The Ultimate Context File

Your CLAUDE.md file is the single most important factor in Claude Code's effectiveness. It is read at the start of every session and provides persistent context.

# Project: E-Commerce API

## Tech Stack
- Node.js 20 + TypeScript 5.3
- Fastify (NOT Express)
- PostgreSQL 16 + Prisma ORM
- Jest for testing
- pnpm (NOT npm or yarn)

## Key Commands
- `pnpm dev` - Start dev server
- `pnpm test` - Run all tests
- `pnpm test:watch` - Watch mode
- `pnpm db:migrate` - Run migrations
- `pnpm lint` - ESLint + Prettier

## Conventions
- Use barrel exports (index.ts) in each directory
- Error handling: throw custom errors from src/errors/
- All dates in ISO 8601 format, stored as UTC
- API responses follow the format in src/types/api-response.ts

## File Structure
- src/routes/ - API route handlers
- src/services/ - Business logic
- src/repos/ - Database queries (Prisma)
- src/middleware/ - Fastify middleware
- src/types/ - TypeScript type definitions

Using /compact to Manage Long Sessions

As your conversation grows, Claude's context window fills up. The /compact command summarizes the conversation and frees up space:

# When you notice Claude forgetting earlier context, or after many turns
> /compact

# Claude summarizes the conversation and frees up context space
# You can continue the session with the summary as context

# Pro tip: use /compact with a custom summary prompt
> /compact Focus on the database migration work we discussed

When to Start a New Session

Sometimes it is better to start fresh rather than compact:

Providing File Paths Explicitly

Every time Claude uses a tool to search for files, it costs tokens and time. Providing file paths saves both:

# Expensive: Claude must search for the file
> Fix the email validation bug

# Cheap: Claude goes directly to the file
> Fix the email regex in src/utils/validators.ts line 23

# Even better: reference multiple files explicitly
> Update the User interface in src/types/user.ts to add an avatar field,
> then update src/services/user.service.ts and src/routes/users.ts to handle it

Using Git History as Context

Git history provides rich context about your project's evolution:

# Use recent commits as context
> Look at the last 5 commits. The feature we added yesterday is causing a regression.
> Find and fix it.

# Use blame for understanding code authorship
> Check git blame on src/services/payment.ts. The logic added in the most recent
> commit is incorrect. Revert just that function to the previous version.

# Use diff for targeted reviews
> Review git diff main...feature-branch. Focus on the database queries.

Reducing Noise: What NOT to Include

Too much context is almost as bad as too little. Avoid these context polluters:

• Generated files: Don't let Claude read node_modules/, dist/, or build/ directories.
• Lock files: package-lock.json and yarn.lock are huge and rarely useful.
• Binary files: Images, fonts, and compiled assets waste context space.
• Verbose logs: Pipe only the relevant portion of logs, not entire files.
• Irrelevant history: Don't dump the entire git log when Claude only needs the last few commits.

The Context Budget Mental Model

Think of your context window as a budget. Every interaction has a cost:

Memory System Usage

Claude Code has a memory system that persists information across sessions:

# Claude automatically remembers project-level preferences
# You can also explicitly tell Claude to remember things

> Remember: this project uses pnpm, not npm. Always use pnpm commands.

> Remember: our API responses always include a "success" boolean field.

# These memories persist in CLAUDE.md or Claude's memory system
# and are available in future sessions