Mapping an Unfamiliar API Before Monday’s Bug Fix
You have a bug to fix on Monday, a repository you have never opened, and a README that assumes you already know the system. Before changing anything, you need a working picture of what the code does. AI can help you build that picture, provided you treat it as a reading assistant rather than an authority.
The basic idea is simple: give an AI assistant selected code and ask it to describe the structure, follow a specific behavior, and identify what you should read next. You still check the files. The assistant helps you decide where to look.
Start with a repository map, not every file
An AI model can only reason from the material available to it. In a chat window, that usually means files you paste or upload. A repository-aware coding tool may search and read files itself, depending on its permissions. Neither arrangement guarantees that it has seen the whole project.
Begin with the README, a directory listing, the dependency manifest, and configuration examples with sensitive values removed. Skip generated files, dependency folders, and large build outputs. Ask for an initial map:
“Based only on these files, describe this application in plain English. Identify likely entry points, major directories, and external services. Cite file paths for each claim. Separate confirmed facts from guesses, and list the next three files worth reading.”
This gives you a useful reading order without asking the model to invent a complete architecture from folder names.
Trace one request through the application
A directory summary tells you where things live. Following one behavior tells you how they work together. Choose something concrete: creating an account, uploading a document, or fetching an order.
For an unfamiliar orders API, your next prompt might be:
“Trace GET /orders/:id from its route definition to the response. Identify authentication, validation, business logic, and database access. Cite the relevant function names and file paths. If a step is missing from the supplied code, stop and tell me what file you need.”
Ask for a numbered explanation in ordinary language. If terms such as middleware or repository appear, request short definitions tied to this application. You want to understand this codebase, not memorize a generic software glossary.
Check the explanation against actual code
A fluent explanation can still be wrong. Models may infer behavior from a function name, overlook a configuration switch, or confuse an unused module with the active implementation.
- Open every cited file and confirm that the named function exists.
- Check which callers actually use that function.
- Read tests for the behavior, including error cases.
- Look for environment settings that change the execution path.
Then challenge the explanation: “Which parts of your account are directly supported by code, and which remain assumptions?” If it says every order lookup checks ownership, find that check yourself. If you cannot find it, record the uncertainty instead of accepting the summary.
Keep the first session read-only
Understanding and editing are different jobs. For the first pass, explicitly tell the assistant not to modify files, install packages, run migrations, or execute commands. Where your tool supports it, use read-only permissions.
Before sharing code, check your organization’s rules for external AI services. Remove credentials, customer records, production logs, and private configuration. Review the data-handling terms of both the model provider and any intermediary. A small, relevant excerpt is often more useful than an entire repository dump.
Turn the conversation into a reusable codebase note
Finish by asking for a short note containing the application’s purpose, its entry points, one verified request trace, relevant tests, and unresolved questions. Save it with file references, and update it as you learn. This becomes your own orientation document rather than another chat you must reread.
If you want pay-as-you-go model access for this workflow, RelayVano works with coding tools and OpenAI-compatible SDKs through https://api.relayvano.com. Sign up when you are ready to try a small, approved code sample.
The useful outcome is not an impressive architecture summary. It is being able to point to a file, describe its role, and explain what evidence supports your understanding before you make that Monday change.