Skip to content
Recipes Ecosystem Source Code Docs

Explore an Unfamiliar Codebase

When you inherit a project nobody has explained, OpenCode becomes your tour guide. It reads the import graph, identifies the entry points, and produces a map you can act on within an hour.

When to use this recipe

  • You joined a new team or are taking over an unmaintained repo.
  • The codebase is large enough that reading every file is impractical.
  • You need to make a confident change but don’t yet know where the boundaries are.

Prerequisites

  • OpenCode installed and pointed at the project root.
  • A working build or test command you can run.
  • Permission to read the entire repo (no encrypted submodules).

Steps

  1. Get the lay of the land

    Ask OpenCode to summarize the project shape, tech stack, and entry points in a few paragraphs.

    Read the project root and summarize: the language and framework, the directory structure, the main entry points, and the build/run commands. Highlight anything unusual.

  2. Map the architecture

    Request a one-page architecture map: modules, their responsibilities, and how they talk to each other.

    Draw a module map: which directories own which concerns, and which top-level files import from which. Show the dependency direction (UI → service → data) if it exists.

  3. Find the entry points

    Identify where requests, jobs, or commands enter the system. This is where most bugs and feature work happens.

    List every entry point: HTTP routes, CLI commands, cron jobs, message handlers, scheduled tasks. For each, give the file path and a one-line description.

  4. Trace a representative request

    Pick one end-to-end flow and walk through it. This is the fastest way to build intuition.

    Trace a single user request from the HTTP route through the service layer to the database. Show the call chain and explain each layer’s responsibility.

  5. Write a navigation guide

    Ask OpenCode to turn the findings into a CODEBASE_MAP.md you and your teammates can reference.

    Write CODEBASE_MAP.md in the repo root: 1) one-paragraph project summary, 2) module map, 3) entry points list, 4) one traced example flow, 5) conventions observed (naming, error handling, logging).

  6. Verify by making a small change

    Make a tiny, real change (fix a typo, improve a log message) and confirm the build, lint, and tests still pass.

    npm run build && npm test

Key prompt

I’m new to this repo. Read the whole project root and produce: (1) a one-paragraph project summary, (2) a module map with the dependency direction, (3) every entry point with file paths, (4) one end-to-end request flow traced through the layers, (5) the conventions you observe for naming, errors, and logging. Output as CODEBASE_MAP.md in the repo root.

Verify

  • CODEBASE_MAP.md is committed and shared with the team.
  • The traced example flow matches reality when you follow it manually.
  • A small intentional change builds and tests green.

Common pitfalls

  • Trust the map blindly: Treat it as a hypothesis, not ground truth. Verify before refactoring.
  • Skipping the entry points: Most bugs live at the boundary. The list is more useful than the diagram.
  • Outdated conventions: Older parts of the code may follow patterns the team has since abandoned. Note the date of the latest file in each area.

Next up