Mapping Call Sites Before an Agent Edits a Shared Function

Code auditors onboard new codebases weekly or daily, and a study of eight practitioners found they align their cognitive flow with automated extraction, decomposition, and representation of codebase information rather than reading files top to bottom (arXiv). Their prototype, CodeMap, cut reliance on reading LLM responses by 79% and increased map usage time by 90% compared with a static visualization tool. The lesson: a map replaces conversation with the model, not just reading.

So the map is not a chat transcript. It is a durable artifact with structure:

• The target: fully qualified name and file path of the function being changed.
• Direct call sites: file, line, the exact expression, and the argument shape passed.
• Entry points: the smallest set of externally reachable functions that can reach the target, with the path from each entry point.
• Dynamic sites: places where the target is invoked indirectly, through reflection, registries, dependency injection, event handlers, or string-keyed maps.
• Tests that touch it: existing tests that exercise any caller, so the agent knows which ones will move.

Agents that write a plan document and then execute it in a fresh context tend to do better than one-shot edits, which is why writing the map to a file and having the agent re-read it before editing is a repeatable loop rather than a ritual (Hacker News discussion).

A call graph is a directed graph of which function calls which, typically built from profiling data or static parsing (statworx). To protect a shared function you want the static, reverse direction: who calls this, all the way out to the edges.

Two families of tooling get you most of the way:

Graph-based code assistants build a structural model of the repository specifically because file-by-file tools need repeated reads to recover cross-file relationships, which fails once you are tracing call chains (Memgraph). Projects like code-graph-rag parse the repository with Tree-sitter into a queryable graph so call chains and dependencies can be queried rather than rediscovered (GitHub). Dedicated analysis engines argue the same case: per-file ASTs cannot trace data flow between a method in one module and its caller in another (Codeprism).

A build order that works in any language:

1. Locate the definition and record its exported name, including every re-export path.
2. Run a symbol search for direct, statically resolvable call sites.
3. Run a scoped text search for the bare name and any string form, to catch factories, registries, and reflection.
4. Build the reverse graph from each call site up to the nearest exported, routed, or registered symbol.
5. Annotate argument shapes at each direct call: which parameters are passed, which are defaulted, which are forwarded.
6. Mark dynamic sites by hand and note why the tool could not resolve them.

Step 5 is the one agents skip. A caller that passes four positional arguments where the target declares optional fifth and sixth parameters will break silently if the agent reorders parameters. Recording shapes turns the map from a list into a constraint.

Not every caller carries the same risk. The tag determines what the agent may do.

Dynamic dispatch is the trap. The choice of which implementation runs is deferred to runtime, based on the actual type or key (Wikipedia). No static tool can see a call that only exists once the type is known, so a map built purely from search will under-report, and an agent will conclude the function is private. When a function is registered under a string key, or invoked by a framework based on file naming, that site belongs in the map by hand even if the tool found nothing.

Here is what a single map entry should look like, in a format an agent can parse and a human can review. It is plain text, indented as a list so it renders anywhere:

## mask (src/sanitize/mask.ts)  [EXPORTED]
Callers:
- src/api/users.ts:88   mask(user.email)                    internal
- src/api/users.ts:94   mask(user.phone)                    internal
- src/export/csv.ts:41  mask(row.email, {keepDomain: true})  EXPORTED (public)
- src/hooks/audit.ts:12 handlerMap["mask"](record.field)     DYNAMIC (registry key)
Entry points:
- GET /users/:id         -> users.ts:88 -> mask
- GET /export.csv        -> csv.ts:41  -> mask
- audit worker (onEvent) -> hooks/audit.ts -> handlerMap["mask"] -> mask
Tests touching this: tests/mask.spec.ts, tests/export.spec.ts
Frozen: csv.ts call passes keepDomain; option must remain accepted.

That block is the deliverable. It is short, checkable, and it tells the agent exactly which calls must still compile and behave after the change.

The last step converts the map into a contract. For each entry point, record one sentence: what a user does and what they observe. That sentence is what you freeze with characterization tests, because they document what the software does today and protect behavior in exactly that place (Medium).

A worked example. Suppose mask has three entry points: the user detail endpoint, the CSV export, and the audit worker. The agent is asked to change email masking so the domain stays visible. The map says the CSV export passes {keepDomain: true}, so the export already keeps the domain and must not change. The audit worker reaches mask through a registry keyed by string, so renaming the function breaks the worker silently. The endpoint is the only entry point whose observable output should change.

That yields a precise test plan: three characterization tests, one per entry point, written against current outputs before the edit. Regression risk is bounded to one of them, and any failure in the other two proves the agent overstepped. Without the map, the same agent would likely update the CSV export too, and no test would notice because none existed.

This is the reasoning behind the strangler fig approach to legacy change: incremental, contained replacement is safer than wholesale rewrite because old behavior stays in place while you move a small piece at a time (Martin Fowler). Microsoft's version stresses that a façade can route between old and new while both coexist (Microsoft Learn), and AWS frames the benefit as reduced transformation risk because changes can be tested in isolation (AWS). The call-site map is the list of seams you strangle at. A logging wrapper around the old function also gives you production call frequency, a useful tiebreaker when two entry points look equally important (Wikipedia).

Decision rule for the entry-point list: an entry point is frozen if a caller outside the repository, or a scheduled or asynchronous process, can reach it without running the code in a test. Everything else is internal and may move if all its callers move in the same change.

Write the map and the entry-point list into a file in the repository, not into the prompt. Prompt context is discarded, files are not, and agents can be told to read them. Then make the map a gate:

1. The agent reads the map file before proposing any change.
2. The agent states which entry points its change affects and which it claims to leave untouched.
3. The agent writes or updates the characterization tests for the claimed-untouched entry points first.
4. The agent makes the edit and runs the full set, including those untouched entry points.
5. You review the diff against the map: any call site with a changed argument shape must appear in the plan.

Step 4 is where the map earns its keep. The most common agent failure on legacy code is not a wrong implementation but a correct implementation in the wrong place: rewriting a function the codebase has already solved elsewhere. The map shows the agent where the rest of the codebase lives.

If you run many agent sessions over the same shared code, route the work through a consistent setup rather than a fresh prompt every time. The skill library at Quanta Skills can be installed into a coding agent so the read-the-map-first step is part of the routine rather than something you retype.