Demo Multi file Project Navigation

In this lesson you’ll learn how to navigate multi-file projects, inspect project structure, and perform cross-file analysis and refactors with Claude Code. We’ll cover how Claude Code reads the working directory, summarizes relationships between files, proposes changes (for example, a DB migration), and verifies refactors across multiple files.

A presentation slide titled "Multi-file Project Navigation" with a dark curved panel on the right that prominently shows the word "Demo." The slide uses a light background and teal/blue accent colors.

What Claude Code provides for multi-file projects

Claude Code can:

Inspect the current working directory and list files and folders.
Produce a project-level summary (entry points, route structure, DB layer, where business logic lives).
Identify which files need changing for a cross-file task (for example, migrating a database driver).
Execute or propose targeted refactors while respecting file-level constraints.
Verify that intended changes were applied to the correct files.

Launching Claude Code from a project directory

Example of starting Claude Code in a local repo:

jeremy@MACSTUDIO Express-login-demo % claude

* Welcome to Claude Code!
/help for help, /status for your current setup

cwd: /Users/jeremy/Repos/Claude Code Course/Express-login-demo

> Try "create a small logging.py that..."

? for shortcuts

Show the file structure

Ask Claude Code to show the repository layout. Example output:

> show me the file structure of this application

• List(~/Repos/Claude Code Course/Express-login-demo)
└ Listed 12 paths (ctrl+r to expand)

• Express-login-demo/
    ├── config/
    │   └ database.js
    ├── examples.md
    ├── node_modules/
    ├── package.json
    ├── package-lock.json
    ├── routes/
    │   └ auth.js
    ├── schema.sql
    └ server.js

>
? for shortcuts

Project-level summary (condensed)

Claude Code can turn a file listing into an actionable summary. The following table captures the information from the example project:

Path	Role / Purpose	Notes
server.js	Main Express entry point	Mounts routers and configures middleware
config/database.js	DB connection pool	Uses pg for PostgreSQL pooling
routes/auth.js	Authentication routes	Contains /login endpoint and inline controller logic
schema.sql	Database schema	Users table, indexes, and timestamps

High-level architecture:

Route-controller pattern: server.js mounts auth routes at /api/auth; auth router contains inline controllers (no separate controller layer).
Database: PostgreSQL with the pg client, connection pooling, bcrypt for password hashing, and JWT for tokens.

Claude Code can answer follow-up questions like:

How are routes connected to controllers?
What database driver and pooling strategy are in use?

Example workflow: migrating PostgreSQL → MariaDB

When planning a migration (for example PostgreSQL → MariaDB), Claude Code lists affected files and the exact types of changes required. Files likely to need direct modification:

File	Change Required
package.json	Replace `pg` with `mysql2` or `mariadb` dependency
config/database.js	Reimplement connection pooling using the chosen MariaDB client
routes/auth.js	Update parameter placeholder syntax (Postgres `$1` → `?`) and any client-specific query handling
schema.sql	Convert Postgres-specific SQL to MariaDB/MySQL equivalents

Schema-level adjustments to review:

SERIAL PRIMARY KEY → AUTO_INCREMENT PRIMARY KEY
Remove or replace \c database commands (use USE dbname or omit)
Review timestamp defaults, UUID usage, and any Postgres-specific data types

Environment updates:

.env: change default port (MariaDB usually 3306 vs Postgres 5432) and driver-specific connection variables.

Example text output Claude Code might produce when identifying required changes:

Based on the codebase analysis, these files would need changes for MariaDB migration:

Direct changes required:
- package.json: replace pg dependency with mysql2 or mariadb
- config/database.js: rewrite to use MariaDB client and connection pooling
- routes/auth.js: update parameter placeholder syntax ($1 -> ?) and any client-specific query code

Schema changes:
- schema.sql: convert PostgreSQL-specific syntax
  - SERIAL PRIMARY KEY -> AUTO_INCREMENT PRIMARY KEY
  - \c database commands -> USE statement (or remove if not needed)
  - adjust defaults and data type specifics if required (timestamps, uuid usage, etc.)

Environment variables:
- .env: update connection parameters (default port 3306 for MariaDB vs 5432 for Postgres)

Existing PostgreSQL connection pool (example)

Here is the typical pattern you might find in config/database.js when using Postgres. This is the code you would replace when migrating to MariaDB:

const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT) || 5432,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
});

pool.on('connect', () => {
  console.log('Connected to PostgreSQL database');
});

module.exports = pool;

Note: When migrating, swap this implementation for a MariaDB client (for example, mysql2 or mariadb) and adapt pooling and query methods accordingly.

Parameterized queries separate values from SQL, improving safety. Placeholder syntax differs between drivers — Postgres uses

1,

2, …; many MySQL/MariaDB clients use ? or named placeholders. Update your query placeholders and any client-specific methods when switching drivers.

File-level instructions and safety controls

Claude Code accepts precise file-level instructions:

Tell it exactly which files it may modify (e.g., only auth-related files).
Or explicitly list files that must not be changed; Claude will warn if a requested modification would require touching those files.

Best practices:

Provide contextual information about how files relate (for example: “server.js mounts the routers; auth logic lives in routes/auth.js”).
Limit the list of files you paste — Claude Code already knows the repository layout and can focus on the relevant files.

Verifying refactors

After a refactor, ask Claude Code to:

Confirm which files were modified.
Show diffs or summarize the applied changes.
Run static checks (lint/test) or provide commands to run tests locally.

Do’s and don’ts

Do	Don’t
Provide relationships between files for context	Paste huge unstructured file lists and expect manual sorting
Specify which files can or cannot be modified	Mix incompatible contexts without clear adaptation instructions
Ask for verification after changes	Assume a large refactor is safe without testing or review

Summary

Claude Code helps you navigate multi-file projects by:

Mapping file structure and relationships,
Summarizing architecture and responsibilities,
Proposing and implementing targeted cross-file refactors (like DB migrations),
Respecting file-level constraints, and
Verifying the results.

This workflow accelerates working with legacy codebases, multi-file apps, and incremental migrations while reducing human error.

Introduction

Getting Started with Claude Code

Working with Claude Code

Code Review with Claude Code

Security Auditing with Claude Code

Advanced Features

Demo Multi file Project Navigation

What Claude Code provides for multi-file projects

Launching Claude Code from a project directory

Show the file structure

Project-level summary (condensed)

Example workflow: migrating PostgreSQL → MariaDB

Existing PostgreSQL connection pool (example)

File-level instructions and safety controls

Verifying refactors

Do’s and don’ts

Summary

Links and references

Watch Video

​What Claude Code provides for multi-file projects

​Launching Claude Code from a project directory

​Show the file structure

​Project-level summary (condensed)

​Example workflow: migrating PostgreSQL → MariaDB

​Existing PostgreSQL connection pool (example)

​File-level instructions and safety controls

​Verifying refactors

​Do’s and don’ts

​Summary

​Links and references

Watch Video

What Claude Code provides for multi-file projects

Launching Claude Code from a project directory

Show the file structure

Project-level summary (condensed)

Example workflow: migrating PostgreSQL → MariaDB

Existing PostgreSQL connection pool (example)

File-level instructions and safety controls

Verifying refactors

Do’s and don’ts

Summary

Links and references