How automatic file discovery works

When you ask Claude a question, it doesn't read your entire codebase upfront. Instead, it strategically discovers and reads files based on relevance:

1. Starting point: Claude reads files you mention explicitly and files in the current directory
2. Following references: It traces imports, function calls, and type definitions across files
3. Expanding scopeWhat is scope?The area of your code where a variable is accessible; variables declared inside a function or block are invisible outside it. Ask AI for more: If the initial files don't answer the question, Claude searches for related files by name, content, and structure
4. Git awareness: Claude uses git history and file change patterns to find related code

For example, if you ask "how does user authenticationWhat is authentication?Verifying who a user is, typically through credentials like a password or token. Ask AI for more work?", Claude might:

• Search for files containing "auth", "login", "sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more", "middlewareWhat is middleware?A function that runs between receiving a request and sending a response. It can check authentication, log data, or modify the request before your main code sees it. Ask AI for more"
• Read the main auth moduleWhat is module?A self-contained file of code with its own scope that explicitly exports values for other files to import, preventing name collisions. Ask AI for more and follow its imports
• Trace the authentication middleware to see where it's applied
• Check the database schemaWhat is schema?A formal definition of the structure your data must follow - which fields exist, what types they have, and which are required. Ask AI for more for user and session tables
• Read test files to understand expected behavior

This automatic discovery works well for most projects. But for very large codebases, you can help Claude by being more specific.

Using .claudeignore

Just like .gitignore tells git which files to skip, .claudeignore tells Claude Code which files to ignore. Create it in your project root:

# .claudeignore

# Build outputs - never useful context
dist/
build/
.next/
out/

# Dependencies - too large, rarely helpful
node_modules/

# Generated files
*.generated.ts
*.min.js
coverage/

# Large data files
*.csv
*.sql.gz
fixtures/large-dataset.json

# Sensitive files
.env
.env.local
secrets/

The syntax is identical to .gitignore. Some key reasons to use it:

• Build outputs add noise without useful information
• node_modules is massive and Claude doesn't need to read library source code to understand your project
• Generated files (minified bundles, compiled CSS) waste context windowWhat is context window?The maximum amount of text an AI model can consider at once, including your conversation history and any files it has read. Ask AI for more space
• Large data files can consume the entire context window with a single file
• Sensitive files should never be read by external tools

If you notice Claude reading irrelevant files or running out of context space, .claudeignore is often the fix.

Context windowWhat is context window?The maximum amount of text an AI model can consider at once, including your conversation history and any files it has read. Ask AI for more management

Claude's context window is large but not infinite. During a long sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more, it fills up with:

• File contents Claude has read
• Diffs and command outputs
• Your conversation history
• Claude's own responses

When the context window gets full, you'll notice Claude's responses becoming less focused or it may explicitly tell you the context is running low.

The /compact command

/compact is your primary tool for managing context. When you run it:

1. Claude summarizes the entire conversation into a condensed form
2. The original messages are replaced with the summary
3. The context window is freed up for new content

Think of it as archiving the conversation so far. Claude retains the key facts and decisions, but the detailed back-and-forth is compressed.

When to use /compact:

• After completing a major task (before starting the next one)
• When Claude's responses start losing focus
• When you're switching to a completely different topic
• As a habit every 20-30 messages in long sessions

Proactive context management tips

• One task per session for complex work. Start fresh rather than piling on
• Be explicit about what you're done with: "We're done with the auth refactor, now I want to work on the payment moduleWhat is module?A self-contained file of code with its own scope that explicitly exports values for other files to import, preventing name collisions. Ask AI for more"
• Close files mentally: if Claude read 15 files for a previous task, those are still in context. Use /compact to clear them before the next task

CLAUDE.md, persistent project memory

CLAUDE.md is a special file that Claude loads automatically at the start of every sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more. It's your project's instruction manual for Claude.

# CLAUDE.md

## Project Overview
This is a Next.js e-commerce app with a Python microservices backend.

## Commands
- `npm run dev` - start frontend dev server
- `npm test` - run Jest tests
- `cd backend && python -m pytest` - run backend tests

## Architecture
- Frontend: Next.js 14 with App Router, TypeScript, Tailwind
- Backend: FastAPI microservices behind an API gateway
- Database: PostgreSQL with Prisma ORM

## Coding Conventions
- Use functional components with hooks (no class components)
- All API responses follow the { data, error, meta } envelope pattern
- Tests go in __tests__/ directories next to the code they test

CLAUDE.md lives at your project root. It's loaded into Claude's context before any conversation starts, so every session benefits from this baseline knowledge.

What to put in CLAUDE.md:

• Build and test commands Claude needs to know
• Project architecture overview
• Coding conventions and style preferences
• Common gotchas or non-obvious patterns
• File organization rules

What NOT to put in CLAUDE.md:

• Detailed documentation (keep it concise, it costs tokens every session)
• Information that changes frequently
• Sensitive data (APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more keys, secrets)

You can create a starter CLAUDE.md with the /init command.

Working with large codebases

For projects with hundreds or thousands of files, these strategies help Claude stay effective:

Be specific in your questions

# Too broad - Claude may read dozens of irrelevant files
> How does the app work?

# Better - Claude knows exactly where to look
> How does the payment processing work in src/services/payments/?

# Best - points Claude to the exact area of interest
> In src/services/payments/stripe.ts, what happens when a charge fails?

Point Claude to directories

> Look at the files in src/middleware/ and explain the request pipeline

> The bug is somewhere in the worker/ directory - find the race condition

Use CLAUDE.md to map the territory

For very large projects, add a brief directory guide to your CLAUDE.md:

## Key Directories
- src/api/ - REST API route handlers
- src/services/ - Business logic layer
- src/models/ - Database models (Prisma)
- src/workers/ - Background job processors
- src/lib/ - Shared utilities

This helps Claude navigate efficiently without reading every file to understand the layout.