Find your way around code

A repository becomes easier to read when you have a route through it. Start with an observable behavior, then follow the definitions and calls that explain it.

Find a starting file

Use Command-P when you know part of a file name or path. Use the Explorer’s content search when you know a symbol, a message, or a distinctive string instead.

Search is affected by workspace exclusions and hidden or ignored file settings. If a result is missing, check those settings and confirm that the file is inside the workspace you opened.

Keep the first file open in a tab. It is your reference point while you explore adjacent code.

Follow a symbol

Definition, reference, implementation, and call hierarchy navigation can help explain a symbol’s role. Availability depends on the language, language server, and project configuration.

A definition explains what a symbol can do. Callers reveal how the project actually uses it. Read both before drawing conclusions about a behavior.

When navigation returns several possible targets, look for the implementation selected by the relevant configuration or runtime state. A list of possible implementations is not proof that a particular one runs.

Read references in context

AI responses can link to source locations. Activating a supported source reference opens a bounded preview in Code Quick Look. Use the explicit open action when you want to keep that file in a tab and read further.

The cited lines are a starting point. Look at surrounding branches, callers, and error handling when they affect the explanation.

Keep documentation nearby

Markdown files open in reading mode by default. You can switch to source editing when needed. Keep a README, a design note, or a relevant test alongside the code to compare intent with implementation.

When a document and the current code disagree, record the difference. A document explains what someone intended; the code and observed behavior establish what currently happens.

Leave yourself a small map

Before moving on, summarize the path in a few lines:

Entry point → input validation → state change → result
                               ↘ failure handling

Add the file names that support each step. The goal is a map you can revisit, not a transcript of every file you opened.