Map a codebase with AI before editing: entry points, ownership and dependencies

A worked example: where the task becomes difficult

A fictional project contains a website, an API package and shared types. The developer wants to add an order-history filter but has only opened the page component. The filter may already exist in a server query or shared library. Start by locating the application root and tracing a current order request. A tree of filenames alone cannot show which package executes or which service owns the result.

Decisions to make before implementation

Record entry point, request contract, data ownership, authorization and presentation separately. Mark generated files, vendored dependencies and build output so they are not edited accidentally. For a monorepo, identify package boundaries and the command used to run the relevant app. Keep confidence proportional to inspected source: a model should not claim an entire repository has been audited after reading a handful of files.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Locate package manifests, entry points and repository instructions.
• Trace a controlled order-list request through actual handlers and data access.
• Build a small ownership table with file path, responsibility and unresolved dependency.
• Use the map to select the smallest change location and required tests.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Map the order-history journey in this repository without changing files. Identify the running package, route, authorization, data query and rendering component. Cite paths you inspected. Separate confirmed ownership from inferred dependencies. Finish with the likely location for a date filter and the additional source needed before editing.

Failure modes that an attractive preview can hide

A plausible architecture diagram can invent a backend that is not present. Require file references for every concrete component and mark external services as configured, referenced or actually observed. Avoid sending a complete repository to a model just because context is missing. Load relevant source progressively, especially files that contain credentials, private fixtures or large generated artifacts.

Technical references: GitHub: getting useful results from coding tasks

Acceptance checks and the evidence to retain

Keep a compact code map with observed paths and outstanding questions. A useful map guides the next edit and can be updated after architectural changes; it is not a certificate of repository completeness.

Specific answers

Common questions