Use Gemini Long Context to Understand a Codebase You Did Not Write

This post is for a mix of builders. Maybe you exported your app from Lovable, Bolt or another AI builder, or you inherited a project from a freelancer. You can run it, but you did not write it and you do not know where anything lives. Now something is broken.

Gemini models can take in a very large amount of text at once (Google lists a 1 million token context window for its current flagship), which is enough for many small and medium apps in one go. That makes Gemini a good fit for the first job with an unfamiliar codebase: reading all of it before touching any of it.

First, a tooling update

If you read older guides, they will tell you to use Gemini CLI. In 2026 Google moved most users to a new tool. Per Google's announcement, Gemini CLI stopped serving free and consumer subscription users on June 18, 2026, and was replaced by Antigravity CLI. Gemini CLI still works with paid Gemini API keys and on enterprise licenses.

So you have two practical options:

• Antigravity CLI (the command is agy). Runs in your terminal, inside your project folder. Best if you have the code on your computer.
• Google AI Studio Build mode. Runs in the browser and can import a project from GitHub. Best if you do not want to touch a terminal.

The prompts below work in either.

Step 0: Make a safe copy

Before you let any agent near the code, make sure you can undo everything.

• Put the project in a Git repository if it is not already. AI builders that sync to GitHub have done this for you.
• Create a new branch for this work, like fix-checkout-bug.
• Remove any .env files with real keys from the folder, or confirm they are listed in .gitignore. You do not need production secrets to read code.

Step 1: Get a map before a fix

The worst first prompt is "fix the bug." The agent will guess, change five files and maybe fix it. Start by asking for a map, and tell it not to edit anything:

Read this entire project. Do not change any files.

Give me:
1. What the app does, in 3 sentences.
2. The tech stack (framework, database, auth, payments, hosting).
3. A folder-by-folder map: what lives where, one line each.
4. The main data tables or models and how they relate.
5. Every place the app calls an outside service (APIs, database,
   payments, email), with file paths.
6. Anything that looks risky: secrets in code, missing auth checks,
   duplicated logic, dead code.

Write it so a non-developer can follow it.

Save the answer to a file in the project, like docs/codebase-map.md. In Antigravity CLI, project rules and context go in an AGENTS.md file (an older GEMINI.md still works). Add a short summary of the map there so every future session starts with the same understanding.

Step 2: Check the map against reality

Long context helps the model see everything. It does not guarantee it reads everything correctly. Spot-check:

• Open two or three of the files it named and confirm they do what it said.
• Ask: "Which file handles user sign-up? Quote the function that creates the user." If the quote does not match the file, the map is wrong somewhere.
• Look at item 6 carefully. Exported AI-built apps often have an API key in front-end code or a database table without access rules. Those are worth fixing even if they are not your current bug.

Step 3: Trace the bug before fixing it

Now describe the bug the way a user would, and ask for a trace, still without edits:

Bug: when a logged-in user clicks "Upgrade" on the pricing page,
the Stripe checkout opens, payment succeeds, but their account
still shows the free plan.

Do not change any files yet.
Trace every step from the button click to where the plan should
be updated. List each file and function involved in order.
Tell me the 2 or 3 most likely places it fails and why.
Tell me what I can check (logs, database rows, dashboard) to
confirm which one it is.

Then do the checks yourself. In this example you might look at your Stripe dashboard for webhook errors, or at the user's row in the database. Confirming the cause takes ten minutes and saves you from a fix that changes the wrong thing.

Step 4: Ask for the smallest possible fix

Once you know where it breaks:

The cause is confirmed: [what you found].
Make the smallest change that fixes it. Touch as few files as
possible. Do not refactor, rename or reformat anything else.
Before editing, show me the plan: which files, what changes, why.
After editing, tell me exactly how to test the fix.

Read the plan before you approve it. If it wants to edit eight files to fix one webhook, push back and ask why.

Step 5: Test and commit

1. Run the app and follow the testing steps it gave you.
2. Test the thing next to the fix too. If you fixed upgrades, check that downgrades and cancellations still work.
3. Commit with a clear message, like "Fix plan not updating after Stripe checkout."
4. If the app came from an AI builder that syncs with GitHub, push the branch and merge it, then confirm the builder picked up the change.

Tips for big or messy projects

• Leave out what does not matter. Folders like node_modules, build output and lock files add noise. Most tools skip them, but check.
• Split by area if needed. If the project is too large to review well in one pass, map one area at a time: auth, then payments, then the main feature.
• Use a second opinion on risky changes. For anything touching payments or user data, I like to have a second model, such as Claude, review the diff. Different models catch different mistakes.
• Do not trust "I tested it." An agent saying a fix works is not the same as you seeing it work.

When this approach is not enough

If the map in step 1 shows the app is badly tangled, with the same logic copied in several places and no clear data model, fixing bugs one at a time may cost more than a planned rebuild. Long context is useful here too: ask Gemini to write a spec of what the app does today, and use that as the starting point for a cleaner version.

Where to go next

If you want to rebuild a messy export cleanly, the recipes give you build specs to start from. For help reading your own codebase map, bring it to a cohort and we will go through it together.