Why This Matters#

Real projects aren’t just one file — they’re dozens or hundreds of files connected to each other. A web page may depend on a stylesheet, a database, and several modules. Claude Code can work with your entire project at once — but it needs to know where to look.

In this lesson, we’ll learn how to direct Claude’s attention to the right files and work with large projects.

Project Context — What Claude Sees#

When you launch Claude Code in a project folder, it doesn’t read all files at once. That would be too slow for large projects. Instead, Claude:

1. Reads CLAUDE.md files (project rules)
2. Loads auto-memory (its own notes about the project)
3. Then reads files as needed — when you ask about them or they’re needed for a task

💡 Think of it this way: Claude is like a new employee. It knows the general rules (CLAUDE.md), but opens specific files when needed.

@-Mentions for Files#

The simplest way to point Claude to a specific file is to use the @ symbol before the filename.

How It Works#

You: Look at @src/app.js and add error handling

Claude will immediately open that exact file and work with it.

You Can Mention Multiple Files#

You: Compare @src/old-utils.js and @src/new-utils.js —
    which functions were removed?

You Can Mention Folders#

You: Analyze all files in @src/components/
    and find unused components

Examples of @-Mentions#

Working with Large Codebases#

Strategy 1: Start with an Overview#

If the project is large and unfamiliar, ask Claude to understand the structure first:

You: Look at the project structure and explain:
    - What the main folders are and what they're responsible for
    - Where the entry point (main file) is
    - What technologies are used

Strategy 2: Work in Parts#

Don’t ask Claude to “rewrite the whole project.” Break it into tasks:

--- Step 1 ---
You: Explain how authentication works in the project.
    Which files are involved?

--- Step 2 ---
You: Now add Google sign-in capability
    to @src/auth/login.js

--- Step 3 ---
You: Update @src/auth/config.js for Google OAuth support

Strategy 3: Provide Context Through CLAUDE.md#

For large projects, describe the structure in CLAUDE.md:

# Project Structure

## Main Folders
- src/api/ — server side (API endpoints)
- src/components/ — React UI components
- src/models/ — database models
- src/utils/ — utility functions

## Key Files
- src/app.js — entry point
- src/routes.js — routing
- src/database.js — database connection

## Module Dependencies
- Components use API functions from src/api/
- API uses models from src/models/

Additional Directories#

If your project consists of multiple folders (e.g., frontend and backend in different locations), you can add extra folders:

claude --add-dir /path/to/another/folder

Now Claude sees both the main project and the additional folder.

Practical Example: Adding a New Page#

Suppose you have a website and need to add an “About Us” page.

--- Step 1: Learn how other pages are structured ---
You: Show the file structure for the homepage.
    Which files are involved?

Claude: The homepage consists of:
        - src/pages/Home.js (component)
        - src/styles/Home.css (styles)
        - src/routes.js (route)

--- Step 2: Create by analogy ---
You: Create an "About Us" page following @src/pages/Home.js as a model.
    Content: company history, team, contacts.

Claude: [creates src/pages/About.js and src/styles/About.css]

--- Step 3: Connect ---
You: Add a route for the "About Us" page in @src/routes.js
    and a link in the navigation menu in @src/components/Navbar.js.

Claude: [updates both files]

Tips#

• ✅ Use @ to precisely point to files — it’s faster than waiting for Claude to find the right one
• ✅ Describe the project structure in CLAUDE.md — especially for large projects
• ✅ Work step by step: overview → specific file changes → verification
• ✅ When working with an unfamiliar project, start by asking “explain the structure”
• ⚠️ Don’t try to change too many files in one request — better to break it into parts

Lesson Summary#

• Claude Code doesn’t read all files at once — it opens them as needed
• @-mentions (@src/file.js) are the fastest way to point Claude to a specific file
• For large projects, describe the structure in CLAUDE.md
• Work step by step: first an overview, then specific changes
• You can add extra folders with --add-dir