A Short Code Tour Helps AI Find the Right Files

The problem

An AI assistant trained on millions of open-source projects will confidently suggest a change to the first file that looks like a match, even when the real logic lives two steps away in a file you never named. Research by Sergeyuk, Golubev, Bryksin, and Ahmed in 2024 found that developers use AI far more often for writing and summarizing code than for figuring out where a change belongs. The most common complaints-inaccurate suggestions, weak understanding of the project, and misplaced confidence-point to the same problem: the model never learned which parts of your application connect to each other. It sees a function name or a folder and guesses, then presents the edit with the same certainty it would show for a textbook example.

What a code tour is

A code tour traces one user action through the files that matter, giving AI assistants the project context they need. A short code tour fixes that by walking through one visible feature from start to finish. It is not a full design document. It is a deliberate trace through the handful of files that matter for one specific behavior: what the user does to start it, where the decision happens, where information gets saved or retrieved, what the user sees at the end, and what checks are already in place. When you hand that map to an AI, it stops guessing and works from the evidence you collected.

Choose one feature

One feature means one action and one result the user can see. Choose something narrow enough to describe in one sentence.

• A profile page has a Save button that writes a name, a short description, and a picture reference, then shows a confirmation message.
• A search box takes a few words, fetches matching results, and displays a list.
• An administrator flips a switch that changes a setting and records who made the change.

The boundary is what the user experiences. If clicking Save also sends an email or clears a temporary file, those are separate behaviors. Trace the profile update first. Include the other pieces only if they share the same decision point or touch the same stored information. Mixing multiple behaviors into one tour creates the same confusion you are trying to prevent: the assistant sees several goals and picks the wrong one to optimize.

A narrow feature keeps the file list short. Updating a profile might involve a form component, a function that checks the input, a handler that processes the request, a module that writes to storage, and a piece of code that formats the response. Five files, a short reading session, one clear chain. That gives the AI enough to suggest a new field, a stricter rule, or a small change without rewriting the wrong function.

Trace the flow

The tour starts where the user acts and ends where the user sees proof.

Begin at the trigger. For a browser interface, that is usually a button or a form submission. For a scheduled task, it is the job definition. For an external request, it is the entry point that listens for incoming calls. Write down the file name and the function or line range. If the first function just calls a second one, follow that call and note the second file. A complete tour starts at the user trigger and follows the chain to the visible result.

Next, locate the main decision. This is where the code checks a condition, picks a path, or turns input into an action. It could be a function that returns errors if something is missing, a check that looks at permissions, or a routine that builds a command for storage. Note the file, the function name, and any setting or fixed value it depends on. If the decision relies on a feature toggle, a user role, or an environment setting, include that.

Then follow the information. Where does the system read it? Where does it write it? Is there a temporary holding area or a call to another service? Trace the path until the data reaches permanent storage or leaves your application. Record each file and the key function. If the information passes through a converter or a cleanup step, add that stop.

Finally, identify what the user sees. For a web form, that is the success message, the list of errors, or a redirect to another page. For an incoming request, it is the response body and status. For a background job, it might be a log entry or a change in a dashboard. Write the file and line that produces that output.

You now have a complete tour. Five or six files, each with a clear role, connected by function calls or network requests. You have your map.

Facts versus assumptions

File names and function names are facts; everything else is inference.

A useful tour separates what you know from what you assume. Facts are file names you opened, function signatures you read, and variable names you saw in the code. Assumptions are things you guess from a comment, a README, or a naming pattern. Facts are file names and function names you read; assumptions are guesses. Both matter, but only facts should guide edits.

When you write "the Save button in the profile editor calls updateProfile in the profile service," you are stating a fact. When you write "the service probably checks permissions," you are guessing. Both have value, but only one should guide an edit. Mark assumptions clearly. Write "I did not find the permission check; it may be elsewhere or missing" rather than "permissions are handled upstream." The model needs to know what you verified and what you skipped.

Function names and their inputs are especially reliable. If updateProfile takes a user identifier, a display name, a short bio, and a picture reference, list them. If it returns an object with a success flag and a list of errors, note the structure. If the storage call updates specific fields by identifier, describe the pattern. These details anchor the AI to your project's real contracts instead of generic examples it saw during training.

Comments and documentation are secondary. A comment that says "checks email format" is a claim; the function body is proof. If a comment contradicts the code, trust the code and note the mismatch. If project documentation describes a feature that does not align with the behavior you traced, write that down. Conflicting information often shows where a change will break an expectation.

Open questions

Unanswered questions belong in the tour because they shape the work. A tour is not a certification that you understand every detail. It is a record of what you learned and what remains unclear. Open questions make the tour more useful, not less.

Common examples:

• Where is the old value recorded before the update?
• What happens if two people save the same profile at the same time?
• Does the input check happen in the browser, on the server, or both?
• Is there a length limit on the bio field?
• What triggers a refresh of temporary data?

If you cannot answer these from the files you read, write them down. An AI that knows you are uncertain will qualify its suggestions or propose a focused look. An AI that thinks you have complete context will confidently edit the wrong layer. Open questions shape the change by revealing gaps and highlighting areas that need investigation. Questions also help you define the scope. If you want to add a location field to the profile, the tour might reveal that you need a storage change, a validation rule, an update to the response format, a refresh of temporary data, and a new label in the interface. Some steps are straightforward; others need a design choice. Separating them is easier when you list what you do not know.

When you give the tour to an AI, include the questions in plain terms. "I want to add a location field to the user profile. I traced the Save button through the profile editor, the profile service, the user storage module, and the data structure definition. Open questions: Is there a length limit enforced? Do we validate location format? Should other users see this field?" The model can now offer answers, suggest a plan, or ask for clarification. Without the questions, it will assume the simplest path and skip the details that matter.

Existing checks and error paths

Existing checks and error paths reveal what the code already guards against. A feature that handles user input usually has validation, error branches, and tests. Finding them is part of the tour because they show the edge cases the original author anticipated. A test called "rejects bio longer than five hundred characters" tells you there is a length limit. A validation routine that checks whether the display name contains at least one character tells you empty names are blocked. An error handler that returns a forbidden status when the identifier does not match the session tells you the code enforces ownership.

Existing validation, tests, and error handling reveal edge cases the code already anticipates. List these safeguards in the tour. Note the file, the function, and the condition. If there are automated tests, include the test file and the cases that exercise the feature. If there are no tests, write that down too. A missing test is not a flaw in your tour; it is information the AI needs. When you ask the model to add a field or change a rule, it can follow the existing style or point out the gap in coverage.

Error messages are another form of evidence. If the system returns "Display name is required," you know the validation runs on the server and faces the user. If a log entry says a profile update failed, you know failures are tracked. If there is no error handling, the code might rely on a default or fail silently. Note what you observe.

Checks also mark the boundary of safe changes. Adding a field to a structure that already validates and formats other fields is low risk if you follow the same pattern. Changing a validation rule that many tests depend on is higher risk. The tour gives the AI enough background to estimate impact and suggest a verification approach.

A tight boundary

A tight boundary keeps the tour short and the outcome predictable. Once you finish tracing a feature, frame a change that touches only the files you mapped. If the tour covered five files, the change should affect five or fewer. If it needs a sixth, either the tour missed a step or the change is too broad. A narrow scope makes review faster and lowers the chance of invisible breakage.

If you ask an AI to add a location field and hand it a tour of the save flow, it will propose edits to the data structure, the service, the form, the validation, and the test. You can read and verify each because you already understand the path. If the model suggests changes to an