How I Use AI to Understand a 100,000-Line Codebase

Before you start

You just inherited a 100,000-line codebase. The README is stale, the original team left, and you need to fix a bug by Friday. Opening the project in an editor and reading every file is not an option. You need a map, not a scroll.

This article walks through a reproducible workflow I use to understand large codebases with AI assistance. The goal is to get a high-level architecture, find the entry points, trace a feature, and identify the most important files - without reading everything.

You will need: a checkout of the codebase, a terminal, and access to an AI coding assistant (like Claude Code, GitHub Copilot, or Cursor). I will use command-line tools and scripts that work on any Unix-like system.

git clone <repo-url> && cd <repo-name>
# Install tools (macOS example)
brew install jq tree ripgrep

• Start with a fresh clone or checkout of the repository.
• Install jq, tree, and ripgrep (rg) if you do not have them.
• Have an API key or login for your AI assistant ready.
• Work in a branch or copy of the repo so you can experiment freely.

Step 1: Generate a project map

Before asking AI anything, you need a structural overview. A tree of the top-level directories and a list of the largest files gives you a starting point.

Run these commands to get a quick snapshot. The output will be your first prompt to the AI.

tree -L 2 -d --ignore-case --exclude 'node_modules|.git|dist|build' > project-structure.txt
find . -type f -not -path './node_modules/*' -not -path './.git/*' -not -path './dist/*' -not -path './build/*' -printf '%s %p\n' | sort -rn | head -30 > largest-files.txt

• Save the output to text files so you can paste them into your AI chat.
• Largest files often contain core logic or data models.
• Directory names hint at architectural layers (controllers, services, models, utils).

Step 2: Ask the AI for a high-level summary

Now paste the contents of project-structure.txt and largest-files.txt into your AI assistant. Ask for a concise architecture summary: what the system does, the main components, and how they fit together.

This gives you a map before you dive into code. The AI can infer a lot from file names and structure, but it may hallucinate. Treat it as a hypothesis to verify.

• Prompt: 'Here is the structure and largest files. Summarize the architecture, main modules, and how data flows.'
• Ask for a list of the top 10 files to read first.
• Cross-check the summary against the actual code as you go.

Step 3: Find the entry points

Every application has entry points: main functions, HTTP handlers, CLI commands, or event listeners. Find them with ripgrep and then ask the AI to explain the startup sequence.

For a Node.js app, look for package.json scripts and the main file. For Python, look for __main__.py or app entry points.

# Find main entry points
rg -n "main\(|app\.run|createServer|listen\(|if __name__" --type-add 'code:*.{js,ts,py,go,java}' -t code | head -20
# Show package.json scripts (Node.js)
cat package.json | jq '.scripts'

• For web apps, the HTTP server setup is usually in a file named app.js, server.js, or main.py.
• Look for dependency injection containers or factory functions.
• Ask the AI: 'Explain the startup sequence from these entry points.'

Step 4: Trace a feature end-to-end

Pick a feature you understand (e.g., user login) and trace it from the API endpoint to the database. Use the AI to generate a call graph or sequence.

First, find the route definitions and then follow the imports. You can use grep to see which files reference a function or module.

# Find route definitions (Express example)
rg -n "router\.(get|post|put|delete)" routes/ | head -20
# Trace a specific handler, e.g., login
rg -n "login" --type-add 'code:*.{js,ts}' -t code | head -20

• Use the AI to generate a sequence diagram from the files you found.
• Ask: 'List the files involved in the login flow and the order of function calls.'
• Verify by reading the key functions yourself.

Step 5: Use AI to explain a complex file

When you find a file that is dense, copy its contents (or a large chunk) into the AI and ask for a line-by-line explanation. This works best for files under 500 lines; for larger ones, split by function.

For a 100,000-line codebase, you will do this for the top 5-10 files only.

# Extract a specific function from a file (example using sed)
sed -n '/function authenticate/,/^}/p' src/auth.js > auth-fragment.js
# Then paste auth-fragment.js into the AI chat

• Ask for a summary of what the function does, its inputs and outputs, and any side effects.
• Request a list of potential bugs or security issues.
• Use this to prioritize what to refactor or test.

Step 6: Create a living documentation file

As you learn, write down your findings in a markdown file. This becomes your navigation aid and onboarding doc. Update it as you discover more.

Include a directory map, key flows, and links to important files.

# Codebase Guide

## High-level architecture
- Web frontend: React
- API: Node.js/Express
- Database: PostgreSQL

## Entry points
- `src/server.js` - starts HTTP server
- `src/worker.js` - background jobs

## Login flow
1. `POST /api/login` -> `src/controllers/auth.js`
2. `authenticate()` -> `src/services/auth.js`
3. `verifyPassword()` -> `src/models/user.js`

## Key files to read first
- `src/config.js` - all env vars
- `src/db.js` - database connection

What I would do: recommended setup

If you are starting fresh, set up a dedicated AI context. Create a project-level instruction file that tells the AI to focus on codebase understanding.

Here is a starter configuration for Claude Code or similar tools.

# Create a CLAUDE.md file
cat > CLAUDE.md << 'EOF'
# Codebase Understanding Guide

- Always start by reading the project structure and largest files.
- Provide a high-level architecture summary before diving into details.
- When explaining a file, list its dependencies and callers.
- If asked to trace a feature, produce a step-by-step flow with file paths.
- Flag potential bugs or security issues when you see them.
EOF

• Keep this file in the repo root so the AI picks it up automatically.
• Update it as you learn the codebase.
• Use the same file for new team members.

Troubleshooting

AI tools can make mistakes. Here is how to handle common issues.

• If the AI gives a vague answer, ask it to reference specific file paths and line numbers.
• If it hallucinates a function that does not exist, verify with rg before trusting it.
• For very large files, split them into smaller chunks before asking for explanations.
• If the AI suggests a refactor, run tests before applying it.

FAQ

Answers to the questions that come up most often on this topic.

• Q: Can I use this workflow with any AI assistant? A: Yes, the commands and prompts are tool-agnostic. You can use Claude, GPT, or Copilot.
• Q: How long does this take? A: For a 100,000-line codebase, expect a few hours to get a solid overview, not days.
• Q: What if the codebase is in a language I do not know? A: The AI can still explain the logic; you will learn the syntax as you go.
• Q: Is it safe to paste proprietary code into an AI tool? A: Check your company's policy. Many tools offer enterprise plans with data privacy.
• Q: What if the AI suggests a wrong architecture? A: Always verify with the actual code. Use the AI as a guide, not an authority.

Next action

Your next step is to run the commands in Step 1 on your own codebase. Generate the structure and largest files, then paste them into your AI assistant with the prompt from Step 2.

You will have a high-level map within minutes, and you can start tracing the feature you need to fix.