Skip to main content
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:
PathRole / PurposeNotes
server.jsMain Express entry pointMounts routers and configures middleware
config/database.jsDB connection poolUses pg for PostgreSQL pooling
routes/auth.jsAuthentication routesContains /login endpoint and inline controller logic
schema.sqlDatabase schemaUsers 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:
FileChange Required
package.jsonReplace pg with mysql2 or mariadb dependency
config/database.jsReimplement connection pooling using the chosen MariaDB client
routes/auth.jsUpdate parameter placeholder syntax (Postgres $1 → ?) and any client-specific query handling
schema.sqlConvert 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,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

DoDon’t
Provide relationships between files for contextPaste huge unstructured file lists and expect manual sorting
Specify which files can or cannot be modifiedMix incompatible contexts without clear adaptation instructions
Ask for verification after changesAssume 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.

Watch Video