Skip to main content

Lesson 3: Working with Your Codebase

Learning Objectives​

After completing this lesson, you will be able to:

  • Understand how Claude maintains project context
  • Search files using Grep and Glob tools
  • Use @ to reference specific files
  • Ask intelligent questions about your code
  • Perform simple refactoring tasks
  • Navigate unfamiliar codebases effectively

Prerequisites​

  • Completed Lessons 1-2 - Basic operations and permissions
  • A project to work with - Use the sample project or your own
  • Basic file system knowledge - Understanding of directories and paths

Estimated Time: 30 minutes

Project Context and Awareness​

Claude Code doesn't just process individual commands—it maintains awareness of your entire project structure and conversation history.

How Claude Maintains Context​

  1. Conversation History: Remembers what you've discussed
  2. File Operations: Tracks which files have been read or edited
  3. Directory Structure: Understands your project layout
  4. Git History: Can access commit history (when available)

Why Context Matters​

Without Context:
You> "Fix the bug in the user function"
Claude: "Which user function? Which file?"

With Context:
[You've been working on authentication.py]
You> "Fix the bug in the user function"
Claude: "I see the issue in the validate_user function..."

Conversation Continuity​

Claude remembers across exchanges:

You> "Read the User class in models.py"
[Claude reads the file]

You> "Add an email field"
[Claude knows you mean the User class from models.py]

Searching Files: Grep and Glob​

When working with codebases, you often need to find specific code patterns or files. Claude uses two powerful search tools.

Grep: Search File Contents​

Grep searches inside files for specific text or patterns.

Basic Usage:

You> Search for "TODO" comments in all Python files

More Specific:

You> Find all functions that start with "get_user" in the src/ directory

Pattern Matching:

You> Search for email validation patterns using regex

Claude uses grep-like search to find:

  • Function definitions
  • Variable names
  • Comments and annotations
  • Import statements
  • Error messages

Glob: Find Files by Pattern​

Glob finds files matching name patterns.

Basic Usage:

You> List all test files in the project

Specific Extensions:

You> Find all TypeScript files in the src/ directory

Complex Patterns:

You> Show me all config files (*.json, *.yaml, *.toml)

Combined Searches​

You can combine search strategies:

You> Find all files that import React (Grep) in the components directory (Glob)

Claude will:

  1. Use Glob to find files in components/
  2. Use Grep to search for React imports
  3. Present the results

Understanding File Operations​

Claude has three primary file operation tools.

Read Tool​

Purpose: View file contents without modifying

When Claude uses it:

  • You explicitly ask to read a file
  • Claude needs context to answer a question
  • Understanding code before making changes

Example:

You> What does the calculate_total function do?
[Claude uses Read to view the function]

Edit Tool​

Purpose: Modify existing files

When Claude uses it:

  • Updating functions
  • Fixing bugs
  • Refactoring code
  • Adding imports

Example:

You> Add error handling to the API call
[Claude uses Edit to modify the function]

How Edit works:

  • Shows you the exact diff (changes)
  • Only modifies specific sections
  • Preserves the rest of the file

Write Tool​

Purpose: Create new files

When Claude uses it:

  • Creating new modules
  • Adding configuration files
  • Writing test files
  • Generating documentation

Example:

You> Create a test file for the User class
[Claude uses Write to create user_test.py]

Using @ for File Paths​

The @ symbol lets you reference specific files directly in your messages.

Basic Usage​

You> What does @src/main.py do?

This tells Claude to read src/main.py and explain it.

Multiple Files​

You> Compare @src/utils.py and @src/helpers.py

Claude will read both files and compare them.

File Paths with Spaces​

If your path has spaces, use quotes:

You> Read @"my folder/file.py"

Relative Paths​

@ supports relative paths from your current directory:

You> Check @./config.json
You> Look at @../shared/utils.js

Advantages of Using @​

  • Explicit: Claude knows exactly which file you mean
  • Fast: Skips "which file?" questions
  • Precise: No ambiguity about which file to read

Example without @:

You> "Read the authentication file"
Claude: "Which authentication file? auth.py? login.py?"

Example with @:

You> "Read @src/auth.py"
Claude: [Immediately reads the correct file]

Asking Questions About Your Code​

One of Claude's strengths is explaining and analyzing code.

Types of Questions You Can Ask​

Understanding Code:

You> How does the authentication flow work in @src/auth.py?

Finding Relationships:

You> Which functions call the process_payment function?

Identifying Issues:

You> Are there any potential bugs in @models/user.py?

Explaining Concepts:

You> What design pattern is used in the controller classes?

Code Reviews:

You> Review @api/endpoints.py for security issues

Effective Question Strategies​

Be Specific:

  • ❌ "What does this code do?"
  • ✅ "How does the validate_token function work?"

Provide Context:

  • ❌ "Fix this"
  • ✅ "The login function isn't handling empty passwords correctly"

Reference Files:

  • ❌ "The user model"
  • ✅ "@models/user.py"

Explain Your Goal:

  • ❌ "Change the database"
  • ✅ "I want to add a created_at timestamp to all user records"

Simple Refactoring Tasks​

Refactoring means improving code structure without changing behavior. Claude excels at this.

Common Refactoring Tasks​

Rename Variables/Functions:

You> Rename the 'd' variable to 'user_data' for clarity in @src/process.py

Extract Functions:

You> Extract the email validation logic into a separate function

Simplify Complex Code:

You> Simplify the nested if statements in @utils/parser.py

Add Type Hints:

You> Add type hints to all functions in @calc.py

Improve Naming:

You> Rename the function 'proc' to something more descriptive

Organize Imports:

You> Organize and sort the imports in @main.py

Refactoring Workflow​

  1. Read the code - Claude analyzes current implementation
  2. Propose changes - Claude suggests improvements
  3. Review diffs - You see exactly what will change
  4. Approve - Changes are applied
  5. Test - Verify the refactored code works

Example:

You> The handle_request function is too long. Can you break it into smaller functions?

Claude: [Reads the file]

Claude: I'll break this into three functions:
- parse_request()
- validate_request()
- process_request()

[Claude shows the proposed refactoring with diffs]

You: [Approve the changes]

Claude: [Applies the refactoring]

Practical Example: Exploring a Sample Project​

Let's practice with a real project structure.

Step 1: Navigate to Sample Project​

cd ~/claude-tutorial/docs/examples/sample-project

Step 2: Start Claude Code​

claude

Step 3: Explore the Project Structure​

You> What files are in this project? Show me the directory structure

Claude will show you the organization.

Step 4: Find Specific Functions​

You> Find all functions that handle user input

Claude will use Grep to search for relevant functions.

Step 5: Understand a Specific File​

You> Read @src/calculator.py and explain how it works

Step 6: Identify Relationships​

You> Which files import the Calculator class?

Claude will search for imports and show dependencies.

Step 7: Suggest Improvements​

You> Look at @src/calculator.py and suggest any improvements

Claude will analyze and propose refactoring ideas.

Step 8: Make a Simple Change​

You> Add a square root function to @src/calculator.py

Review the proposed change and approve if it looks good.

✅ Check Your Understanding​

  1. What's the difference between Grep and Glob?

    • They're the same thing
    • Grep searches file contents, Glob finds files by name
    • Glob searches file contents, Grep finds files by name
    • Neither searches anything

  2. What does @src/main.py do in a message?

    • Creates a new file
    • Tells Claude to read that specific file
    • Deletes the file
    • Runs the file

  3. Which tool should Claude use to modify an existing file?

    • Read
    • Edit
    • Write
    • Bash

  4. True or False: Claude remembers your conversation context.**

    • True
    • False

  5. How would you ask Claude to find all test files?

    • "Search for tests"
    • "Find all files with 'test' in the name"
    • "Glob for test files"
    • All of the above could work

Answers: 1-b, 2-b, 3-b, 4-True, 5-d

Summary​

In this lesson, you learned:

  • Project context - Claude maintains awareness of your codebase
  • Grep - Search file contents for patterns
  • Glob - Find files by name patterns
  • File operations - Read, Edit, Write tools
  • @ symbol - Reference specific files directly
  • Asking questions - Get explanations and analysis
  • Refactoring - Improve code structure with Claude's help

Next Steps​

In Lesson 4: Permissions and Safety, you'll learn:

  • Why different permission modes exist
  • How to use Plan mode
  • Switching between permission modes
  • Setting up allowed/denied operations

Further Reading​

Continue to Lesson 4: Permissions and Safety →