Understanding Your Codebase

One of the most important tasks for a software engineer is building a mental map of a codebase. Before you can change something effectively, you need to understand how it works.

In the past, exploring a large codebase meant memorizing regex patterns or learning specialized search tools. Now, you can ask questions in natural language and get detailed answers.

Grep and exact search

The most accurate way to find code is to search for exact matches: function names, variable names, error strings, or imports.

Agents can use grep, a tool for exact string search, and they can build precise regex patterns to find what you are looking for. OpenCode also uses ripgrep, a much faster grep implementation.

You do not need to configure anything or change how you work to use these tools. Agents use them automatically when searching code.

Semantic search

When you do not know exactly what you are looking for, semantic search helps you find parts of the codebase by meaning, not just exact text. For example, you can search "where are user sessions validated?" and find middleware/session.ts even if the file does not contain the word "validate".

This is possible because OpenCode turns your codebase into vector representations that allow search by semantic meaning.

Combining semantic search with grep gives much higher accuracy than semantic search alone.

You do not need to configure anything to use it. OpenCode automatically indexes your codebase in the background.

Asking the right questions

How you phrase a question affects which search tools the agent uses and how effective the results are.

Directed search (use when you know what you are looking for):

Find every file that imports from our PaymentService and show how they handle payment errors.

Broad exploration (use when you are exploring an unfamiliar area):

How does our app handle failed payments? Explain the error flow from the checkout form to the user.

Ask for architecture diagrams

For a large or unfamiliar codebase, you can ask an agent to create an architecture diagram. Agents can produce Mermaid diagrams that render in GitHub, Notion, or other tools.

Create a Mermaid diagram showing the data flow for our payment system, including checkout form, validation, processing, and error handling.

These diagrams are useful for onboarding, documentation, and design review. They can also reveal architectural issues that are hard to notice by reading code file by file.

Understand before changing

A common mistake is asking an agent to change code before it understands what already exists. The agent may modify code that looks relevant but miss important context that should change the approach.

Before asking for a change, ask the agent to explore first:

Before making any changes, show me how the existing form validation works.
Call out which components are involved and how errors are handled.

Coding agents interpret your requests literally. When you do not explain the intent explicitly, they fill the gaps with assumptions that may not match your goal.

What you learned

You can find and understand code. In the next lesson, you will learn how to move from understanding to building: creating new features effectively with coding agents.