First notes from an unfamiliar codebase
Opening an unfamiliar codebase can feel like arriving halfway through a conversation. Folder names suggest a structure, but they rarely explain where a request begins, which files matter, or why a particular decision was made. An AI assistant can help you find those connections, provided you give it a focused question and check its answers against the code.
The aim of a first session is modest: understand one useful path through the project. You can build a broader picture as you work.
§ Start with a small map
Open the project in your usual editor or terminal. Read the README, then look for the files that describe dependencies and available commands. These often reveal the programming language, framework, test runner, and development setup.
If your assistant can inspect local files, ask it to read those first. If you are using a chat interface, provide the relevant text and a short directory listing. A model can only explain the material available to it; access to your project depends on the tool around it.
A useful opening request is: “Read the README and project configuration. Explain what this application does, how it starts, and which folders I should inspect first. Name the files that support your explanation.”
Keep the answer short enough to verify. Open the named files yourself. When the assistant describes something as likely or conventional, treat that as a question to investigate.
§ Follow one thing through the code
Choose something concrete: a page you can open, a command you can run, or an API request mentioned in the documentation. Ask the assistant to trace that behavior from its starting point to its result.
For a web application, you might ask: “Trace the request that loads a user profile. Show the route, the function that handles it, where the data comes from, and how the response is built. Include file paths and function names.”
This gives you a reading order. Follow it in the editor, checking each connection. Does the route call that function? Is the data loaded from a database, an external service, or a local file? Where are errors handled?
Ask about unfamiliar terms as they appear. “Explain middleware using this file” usually produces a more useful answer than a broad request to explain the entire framework. You learn the concept alongside a real example.
§ Use tests to check your understanding
Tests show examples of behavior the project expects. Ask the assistant to find a test for the feature you just traced and explain its setup, action, and expected result. Read the assertions yourself: they tell you exactly what the test checks.
Run the relevant test using the repository’s documented command. If it fails before you make changes, record that starting condition. An existing failure can otherwise become a confusing distraction later.
Then choose a small change, such as improving a validation message or fixing a reproducible edge case. Before asking for an edit, ask which files need to change and what observable behavior should differ. Review the resulting diff and run the relevant checks. A passing test provides evidence about the behavior it covers; other behavior may still need inspection.
§ Keep a short working notebook
At the end of the session, write down the startup command, the path you traced, the tests you ran, and any unanswered questions. Ask the assistant to draft these notes, then correct them. A few verified sentences will help your next session begin with useful context.
You can use this workflow with tools such as Claude Code, Codex, or Gemini CLI. Vana API works with these tools and provides access through one endpoint at https://api.vanaapi.com, supporting OpenAI-compatible requests, Anthropic Messages, and Gemini’s native protocol. Usage is billed per real token with no monthly fee. Create a Vana API account when you are ready to connect your coding assistant.
As you explore, keep asking for concrete references: a file, a function, a caller, or a test. Each checked answer adds another reliable piece to your understanding of the project.