Understanding an Unfamiliar Codebase With AI

Joining a new project, or inheriting an old one, usually means days of reading before you can change anything safely. AI can shorten that a lot. It reads quickly and explains patiently. Your job is to ask good questions and confirm the answers in the code.

Start with the map

If you use a coding agent or an in-editor assistant that can see the repository, ask for an overview first:

Give me an overview of this repository for a new developer:
- what the application does
- the main projects/folders and what each is responsible for
- the entry points (Program.cs, controllers, background jobs)
- how data access works
- how configuration and secrets are loaded
- how to build and run it locally
Point to the exact files for each answer.

With a chat assistant, paste the folder tree and key files instead. In a terminal, tree /f on Windows or git ls-files gives you a list of files to paste.

Always ask for file references. An answer like "authentication is configured in Program.cs, lines 30 to 45" can be checked in seconds. An answer without references might be a guess.

Trace one request end to end

Understanding one real flow teaches more than reading every file. Pick a feature you will work on:

Trace what happens when a user submits POST /api/orders, from the
controller to the database and back. For each step, name the class and
method, and explain what it does in one line. Mention validation,
transactions and anything that runs asynchronously.

Then open each file the AI names and follow along. Where the code differs from the explanation, the code wins, and you have found something worth noting.

Explain the confusing parts

For a dense method or a clever piece of legacy code:

Explain this method step by step. Then tell me:
- what inputs could make it fail or behave unexpectedly
- any hidden side effects (database writes, static state, caching)
- what I would need to test before changing it
[paste method]

For old code, also ask: "What was this probably written to work around? Are there signs it is no longer needed?" Treat the answer as a hypothesis to check with the team or git history (git log -p or git blame on the file).

Find where to make a change

I need to add a discount code to orders. Based on this codebase, which
files would I need to change, in what order, and what existing patterns
should I follow? Do not write code yet.

This gives you a starting list. Check it against the code before editing: AI can miss a second place where the same logic is duplicated.

Write it down for the next person

When you have understood something, ask the AI to turn your notes into documentation:

Turn my notes below into a short "How orders work" section for our
README: overview, main classes, request flow, and gotchas. Max 300 words.
[paste notes]

Review it for accuracy, then commit it. The next new developer, possibly you in six months, will thank you.

Be careful with company code

Pasting large parts of a proprietary codebase into a personal AI account may break company policy. Use the tools your company approves (lesson 1), and never include secrets from config files (lesson 8).

Practice task

Pick a repository you do not know well. Ask for a map with file references, trace one real request end to end, and verify every step in the code. Write a 200-word "how this works" note and share it with your team.

Key takeaways

• Ask for an overview with file references, then verify in the code.
• Trace one real request end to end instead of reading everything.
• Use AI explanations of legacy code as hypotheses, checked against the code and git history.
• Turn what you learn into short docs for the next developer.