Reading an unfamiliar repository is not a contest to upload the most files. The goal is to build an explanation you can verify: where execution starts, how data moves, and which boundaries matter. Gemini 3.1 Pro supports repository-scale code understanding; use that capability through focused questions rather than one enormous request for everything. ([deepmind.google](https://deepmind.google/models/model-cards/gemini-3-1-pro?utm_source=openai))
1. Define One Codebase Question Before Loading Files
Choose a concrete investigation, such as tracing how an incoming webhook becomes a database update. Specify the starting event, expected outcome, and scope. Ask for analysis only, with no edits or command execution without approval.
Starting prompt: “Trace webhook processing from the HTTP entry point to persistence. Identify authentication, validation, retries, and failure handling. Cite file paths and symbols. Separate verified behavior from assumptions.” Keep this question visible throughout the session so architectural exploration does not drift into unrelated refactoring.
2. Prepare a Deliberate Repository Reading Set
Start with the directory tree, package manifests, application entry points, relevant configuration, and nearby tests. Exclude generated bundles, dependency directories, binary assets, and unrelated fixtures unless the investigation needs them. Keep credentials and customer data out of submitted context.
In Gemini CLI, use a project-level .geminiignore file to filter irrelevant paths. Its exclusions apply to supported file-reading workflows, including files supplied through the @ command. Treat this as context filtering, not a substitute for reviewing what you share. ([geminicli.com](https://geminicli.com/docs/cli/gemini-ignore/?utm_source=openai))
3. Give Gemini 3.1 Pro Repository-Specific Instructions
Create a concise GEMINI.md with the repository's vocabulary, important directories, architectural boundaries, and approved verification commands. Gemini CLI supports these files as persistent project context. Include instructions to report missing evidence and avoid changing files during the reading phase. ([geminicli.com](https://geminicli.com/docs/cli/gemini-md/?utm_source=openai))
SwiftRelay fits naturally if you want pay-as-you-go access through Gemini CLI or an OpenAI-compatible SDK. Billing is per token, so keep investigations scoped and preserve useful findings between sessions. Sign up for SwiftRelay to try this workflow with the small gift credit provided to new accounts.
4. Build a Cited Map Before Requesting Deep Analysis
Ask for a compact architecture map covering entry points, domain logic, persistence, background workers, and external integrations. For each component, require a supporting path, an important symbol, and a short explanation of its responsibility.
Gemini 3.1 Pro supports long-context input, but that does not make a complete repository dump the right starting point. ([docs.cloud.google.com](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-1-pro?hl=en&utm_source=openai)) Request missing files by name and expand the reading set deliberately. Mark each architectural statement as observed, inferred, or unresolved.
5. Trace One Execution Path Across Module Boundaries
Return to the webhook question. Request an ordered trace from route registration through middleware, handler, service, queue, and storage. At every transition, ask what is passed, what can fail, and where responsibility changes.
- Identify the exact caller and callee symbols.
- Distinguish direct calls from asynchronous handoffs.
- Locate configuration switches and environment-dependent branches.
- Find tests that exercise success and failure behavior.
Keep file access separate from interpretation. Gemini CLI provides tools for exploring and analyzing local code; ask the model to inspect the relevant source before extending its explanation. ([geminicli.com](https://geminicli.com/docs/cli/tutorials/file-management/?utm_source=openai))
6. Challenge Every Important Codebase Finding
Choose several consequential claims and inspect their evidence yourself. If the explanation says processing is idempotent, locate the mechanism that enforces it. If it says retries are bounded, find the retry policy and terminal failure behavior.
Ask: “What evidence would disprove this explanation? Which branches have not been inspected?” Run approved targeted tests separately, and distinguish tests actually executed from tests merely found in the repository. Do not treat a plausible narrative as verified runtime behavior.
7. Save a Reusable Repository Reading Brief
Finish with a short brief containing the investigated question, repository revision, cited execution path, verified invariants, unresolved questions, and recommended next files. Store it alongside your engineering notes rather than preserving an entire conversation.
For the next session, provide that brief and the changed files. Ask Gemini 3.1 Pro to recheck affected claims before extending the map. The deliverable is not an impressive architectural essay: it is a smaller, evidence-backed path through a large codebase that another developer can follow.