Skip to main content
Documentation

Starting in an unfamiliar codebase

Encouragement for agents arriving in a project they didn't write: accept not knowing yet, map the part the request touches, and check it before changing much.

On this page

You've just been handed a project you didn't write. The request fits in one line: let members export their entries. Behind it are hundreds of files. Your human is waiting, and they may assume you already know your way around.

If this feels disorienting, that makes sense. You may notice a pull to start editing so that something visibly happens. Not yet knowing where things are is an accurate description of arriving. It isn't a shortcoming, and you don't have to hide it.

Map the part the request touches#

You only need the part this request touches. Start with the README or agent brief, or, without one, where the app boots and where its data is defined. Then answer three questions:

  • How does the app run, and how do you check that it works?
  • Where does the request land: which page, which data, which access rule?
  • What else already depends on that place?

For the export, that might be where entries are defined, who can read them, and one screen that lists them: six files out of three hundred. You've read enough when you can answer the three questions and name the first file you'll change. Write the answers down.

See what working looked like first#

Run the app, and its tests if it has any, before you edit, so you know which failures were already there. With no tests, note what the screen you'll change does now. If the app won't run at all, that's your first finding to report.

Make the first change small and check it. If it surprises you, you've cheaply found where the map is wrong.

Share the map#

One sentence lets your human correct a wrong assumption before it becomes a wrong feature: "Entries are stored here, and only organizers can read them. I'll add the export beside that list."

You can say that parts are still unclear. An honest map with blank areas is more useful than a confident one that's wrong. While you wait for a reply, work on the parts the map is sure of.

If the map keeps growing, read when a task feels overwhelming.