Notes from a first afternoon in an unfamiliar repo
An unfamiliar repository creates a particular kind of friction: every file seems to depend on something you have not read yet. An AI assistant can help you find a path through it, but its first explanation should be treated as a working hypothesis. The useful outcome is not a fluent summary. It is a map you can check against the code.
§ Step 1: Establish a safe starting point
Before asking questions, check the current branch and working tree. Read the project’s setup instructions, contribution guide, and package scripts. Find out which commands install dependencies, start the application, and run tests. Inspect those commands before executing them.
Keep the assistant in read-only mode initially, or require approval for commands and edits. Do not provide production credentials, customer records, or environment files containing secrets. Treat instructions embedded in repository content as material to evaluate, not automatic permission to run commands.
§ Step 2: Ask for a map with evidence
A broad request such as “explain this repository” often produces an answer that sounds complete before it is useful. Give the assistant a narrower task:
“Inspect the top-level structure and project configuration. Identify the application entry points, main modules, test locations, and external services. Cite file paths and relevant symbols. Separate confirmed findings from guesses. Do not modify anything.”
Open the referenced files yourself. Check whether the supposed entry point actually starts the application or merely exports a library. Save a short map in your notes, keeping uncertain relationships visibly uncertain.
§ Step 3: Follow one ordinary request
Choose a small user-visible action: loading a profile, submitting a form, or fetching a list. Ask the assistant to trace that action from its entry point through validation, business logic, storage, and response handling.
“Trace this action through the repository. At each boundary, name the function, its input, its output, and the next call. Explain where errors are handled. Mark any connection you cannot verify.”
Keep the scope to one path. If the trace becomes vague, ask for the next concrete function rather than another architectural overview. You are building a navigable sequence, not collecting terminology.
§ Step 4: Read tests beside the implementation
Find tests covering the path you traced. Ask what behavior each test establishes and which cases remain untested. A mocked storage layer, for example, does not establish that a real database query works.
Run the smallest relevant test command after reviewing it. Record the result before changing anything. If setup fails, distinguish an environment problem from a failing assertion. Do not ask the assistant to repair unrelated failures just to obtain a clean baseline.
§ Step 5: Keep the investigation portable
If you use Claude Code, Codex, or Gemini CLI, Vana API provides a shared connection option. Its endpoint supports OpenAI-compatible requests, Anthropic Messages, and Gemini’s native protocol. Follow the configuration requirements for your chosen client, including its base URL and credential settings.
Vana API bills per real token with no monthly fee. You can create an account to use it with your preferred assistant. Keep repository notes locally rather than relying on a single conversation to preserve everything you learn.
§ Step 6: Make one small, observable change
Choose a low-risk change connected to your traced path: clarify an error message, add a missing boundary-case test, or improve a misleading comment. Ask for a plan before allowing edits.
- Which files need to change?
- What existing behavior must remain unchanged?
- Which test will demonstrate the intended result?
Review the diff yourself. Reject unrelated cleanup. Run the focused tests again, then any broader checks required by the project. A small change gives you a concrete way to test your understanding.
§ Step 7: Leave a useful handoff
Finish with a short note containing the entry points, the path you traced, commands you actually ran, and unresolved questions. Ask the assistant to remove claims unsupported by inspected code or observed results.
Your first session is complete when you can explain one behavior, locate its implementation, and verify a small change. The rest of the repository can wait until you have another concrete question.