Use AI to explain unfamiliar code without trusting invented architecture

An assistant describes a repository as a clean layered architecture with centralized authorization. The description sounds plausible, but the route you are changing performs its own database query and bypasses the named service. A confident overview can make unfamiliar code harder to understand when it replaces evidence with invented structure.

The useful goal is narrower: explain the execution path for one behavior, identify what remains uncertain, and show where each claim comes from. Consider an illustrative account settings page that updates a display name. Understanding that journey provides a reliable starting point for a change.

Choose one question that can be traced

Ask “What happens when this settings form submits?” rather than “Explain the whole application.” The smaller question has observable entry points and outcomes. It also gives the assistant a reason to inspect particular files instead of summarizing directory names.

Start with a visible label, route URL, or handler symbol. Search for that anchor and follow references. A form component may call a mutation helper, which calls an endpoint, which invokes a validator and persistence function. Record that chain with file and symbol names.

Define the question's boundary. If you only need to understand update authorization, frontend styling is probably irrelevant. If you need to understand why the page shows an old name after saving, response handling and cache invalidation become relevant. The behavior determines which parts deserve attention.

Require evidence for each architectural claim

Ask the assistant to attach a source location to statements such as “authorization is enforced here” or “all updates use this service.” A single import proves one caller uses a helper; it does not prove all callers do.

Separate direct observations from inferences. “This route calls requireAccountMember” is an observation. “The application probably uses this helper for all account routes” is an inference until callers are inspected. Both can be useful, but they should not carry the same confidence.

Beware of familiar pattern names. Calling a module a repository or a controller may be harmless shorthand, but the label can hide mixed responsibilities. Describe what the function actually does: validates input, reads identity, updates a row, and shapes a response. Concrete verbs survive unusual architectures.

Follow the data rather than the folder tree

Track the display name from the input to the stored record and back to the UI. Identify transformations: trimming, length validation, normalization, and serialization. A bug may occur because the browser shows its local input while the server saves a normalized value.

Trace identity separately. Which account or user is updated? Does the target identifier come from the session, route parameter, or body? Where is permission checked? A data-flow explanation that omits ownership is incomplete for a mutation.

Look for side effects after persistence. The update might invalidate a cache, enqueue a notification, or update a session claim. These steps can explain why one page reflects the change immediately and another does not. The assistant should identify actual calls rather than assuming a conventional event system exists.

Check static explanations against execution

Run or inspect a representative request when safe. Compare the assistant's claimed response shape with the actual response. Inspect network status and the stored synthetic record. If the explanation says the endpoint returns the updated user but it returns only success, the mismatch changes how the UI should refresh.

Use breakpoints or targeted logs where needed, avoiding credentials and private payloads. A request identifier and function entry can establish which path runs without dumping the entire body. Record environment and configuration conditions that choose alternate implementations.

Static search can miss dynamically selected handlers, middleware, generated code, or runtime configuration. When the observed path differs from the source map, investigate the selection mechanism. Do not discard runtime evidence just because the assistant's architecture summary is neat.

Ask useful follow-up questions

Good follow-ups expose missing relationships: “Which callers bypass this validator?” “What happens if persistence succeeds but cache invalidation fails?” “Where does the target account come from?” Each can produce a checkable search or trace.

Avoid asking the assistant to fill unknowns with its best guess. Ask it to name the missing evidence instead. A statement such as “I found no caller in these files; dynamic usage remains unverified” is more useful than a fabricated assurance that the function is unused.

Build a small evidence table or note with claim, source, and uncertainty. For the display-name journey, record submission, validation, ownership, persistence, response, and refresh. This artifact can become the context packet for implementation, as described in focused repository context.

Turn the explanation into a safe change plan

Once the path is understood, identify the layer that owns the desired behavior. If trimming is inconsistent, input normalization may be the appropriate boundary. If the page displays an old value after success, changing validation will not resolve the refresh path.

Ask the assistant to propose the smallest change and identify callers affected. Require it to preserve behavior outside the target path unless the task authorizes a wider change. An unfamiliar repository is a poor place to combine a bug fix with a sweeping architectural cleanup.

Verify the plan against the evidence note. Every proposed edit should have a reason tied to a traced responsibility. If the assistant adds a new service because it believes the project “should” be layered, ask whether the existing path needs that abstraction to solve the problem.

Keep uncertainty visible as understanding grows

A first explanation is a map of what you inspected, not a complete model of the system. Update it when runtime evidence or additional callers reveal a different path. Keeping explicit unknowns prevents later decisions from treating a partial investigation as a universal guarantee.

Document important exceptions. If one legacy route bypasses the shared validator, that exception matters more than a general statement about centralized validation. The next engineer needs to know which path they are changing.

AI is valuable here as a search companion and summarizer. Its contribution becomes reliable when claims lead back to files, calls, and observed behavior. The final understanding belongs to the engineer who checked those relationships and can explain the proposed change without depending on the assistant's confidence.

Include exceptional paths in the map when they affect the planned change. A validator may reject before authentication completes, or middleware may rewrite a route into a different handler. Search for those branches and describe their conditions. If you cannot run the application locally, label the map as static evidence and identify which runtime assumptions remain unchecked. That honest boundary is more useful than claiming an end-to-end understanding from source inspection alone, and it gives the next verification step a clear purpose.

Sources

GitHub Copilot best practices covers explanation tasks and checking suggested work.

Anthropic: Building effective agents discusses understandable implementations and interfaces.