Understanding Context — How Claude Sees Your Project

Claude does not have omniscient knowledge of your project. It knows exactly what is inside its context window — and nothing outside it. This sounds like a limitation, but it is actually the key to working with Claude effectively: once you understand how context works, you can engineer better interactions.

What Is the Context Window?

Every AI model has a context window — the maximum amount of text it can hold in active memory at once. For Claude 3.5 and 3.7, this window is approximately 200,000 tokens (roughly 150,000 words, or several complete novels worth of text).

Within a session, everything accumulates in the context window:

• Your messages to Claude
• Claude's responses
• Every tool call and its output
• The content of every file Claude has read
• System prompts (you do not see these directly)

The context window is large, but it is not infinite. Long sessions working with many large files can approach the limit. When this happens, Claude's older context gets compressed or truncated, which can cause it to "forget" earlier decisions in the session.

How Claude Reads Files

Claude does not automatically load your entire codebase at session start. It reads files on demand, using the Read and Glob tools.

When you say "fix the bug in app.js," Claude uses the Read tool to load app.js into context. If app.js imports from utils.js, Claude may also read utils.js to understand the dependency. It reads what it needs, when it needs it.

This means:

Good practice: Tell Claude which file is relevant. "In src/components/Header.jsx, the dropdown menu is broken." Claude goes directly to that file.

Less good: "The header is broken." Claude has to search for the right file, which uses more context and may produce a less targeted fix.

The more precisely you direct Claude, the more efficiently it uses context.

The CLAUDE.md File — Persistent Project Instructions

The most powerful context tool in Claude Code is the CLAUDE.md file. This is a Markdown file you place in your project's root directory. Claude reads it automatically at the start of every session — before your first message — and after every /clear command.

Think of it as the standing briefing you give Claude so you never have to re-explain your project from scratch.

A good CLAUDE.md for a beginner project includes:

# My Web Project — Claude Instructions

## What This Is
A personal portfolio website. HTML, CSS, and vanilla JavaScript.
No frameworks. No build tools. Just static files.

## Project Structure
- index.html — main page
- style.css — all styles
- script.js — interactivity
- images/ — all image assets

## Style Conventions
- Colors: #0d1117 background, #10B981 accent, #ffffff text
- Font: Inter (loaded via Google Fonts)
- CSS classes: BEM naming (block__element--modifier)

## What NOT to Do
- Do not add npm packages or node_modules
- Do not create a build step
- Do not use CSS frameworks like Bootstrap or Tailwind

With this file in place, every new session with Claude starts with full project awareness. Claude knows your tech stack, your conventions, and your constraints without being told repeatedly.

Nested CLAUDE.md Files

Claude supports multiple CLAUDE.md files at different levels of your project. A CLAUDE.md in the root gives global context. A CLAUDE.md inside src/components/ gives local context specific to that directory.

When Claude is working in the components directory, it reads both — the root-level context plus the local context. This lets you keep global conventions separate from local specifics.

This pattern is useful for larger projects:

• Root CLAUDE.md: overall project, tech stack, deployment
• src/CLAUDE.md: frontend-specific patterns
• api/CLAUDE.md: backend patterns and API conventions

Session Management Commands

As context fills up through a session, two commands help you manage it.

/clear — Resets the conversation. All messages and tool outputs are wiped. CLAUDE.md is re-read. Your actual files are unchanged — /clear affects only the session context, not your codebase.

Use /clear when:

• You finished one task and are starting something completely different
• Claude seems to be confusing earlier context with the current task
• The session has run long and you want a fresh start

/compact — Compresses the conversation history into a summary. This preserves the key decisions and code state but reduces the token usage significantly. Claude can then continue working without losing the thread of what has been built.

Use /compact when:

• You want to keep working on the same task but the context is getting full
• You have made many iterations and want to consolidate

Context Limits in Practice

A typical beginner session covering one focused task rarely hits context limits. Issues arise in longer, exploratory sessions:

• Reading many large files
• Running commands with verbose output (long test suites, build logs)
• Asking Claude to explain everything as it works (more words = more tokens)
• Sessions spanning hours with dozens of iterations

The signal that you are approaching the limit: Claude starts giving shorter, less thoughtful responses, or forgets things it was explicitly told earlier in the session. Run /compact immediately if you notice this.

For large projects, develop a habit of starting focused sessions. One session = one task. When the task is done, commit the changes, then start a fresh session for the next task.

What Claude Cannot See (And How to Help)

By default, Claude cannot see:

• Your browser's console errors — paste them explicitly
• External API responses — paste the response body or describe it
• Runtime behavior — tell Claude what happens when you run the code
• Your mental model — describe what you intended vs. what is happening

The most effective prompts include context Claude cannot get from the files alone:

I ran `node server.js` and got this error in the terminal:
[paste error here]

The file it references is server.js at line 42. Can you look at that line and fix it?

Claude now has the error text, knows which file and line, and can provide a targeted fix rather than speculating.

Lesson 44 Drill

Create a CLAUDE.md for the web page you built in Lesson 43:

1. Open a Claude session in your project directory
2. Type: "Read my project files and write a CLAUDE.md that captures the project structure, tech stack, color scheme, and any conventions you can infer from the code."
3. Claude generates a draft. Read it, edit anything incorrect or missing.
4. Run /clear to start a fresh session. Notice that Claude now knows your project without any additional context from you.

Then verify: ask Claude "What is the color scheme of this project?" without telling it. It should read CLAUDE.md and answer correctly.

Bottom Line

Claude sees exactly what is in its context window: your messages, tool outputs, file contents it has read, and your CLAUDE.md. It does not see your filesystem, browser, or runtime automatically. The CLAUDE.md file is the most powerful tool for eliminating repeated context-setting — it persists across sessions and /clear commands, giving Claude persistent project knowledge. Manage your context intentionally: keep sessions focused, use /compact when the window fills, use /clear between unrelated tasks.

Lesson 45 covers all the commands, shortcuts, and configuration options that make day-to-day Claude Code use faster and more comfortable.