Map before you build: a topology-first workflow for AI agents

Every bad agent edit I’ve seen has the same root cause. The model changed one side of a connection without looking at the other side. It renamed a field the API still sends, or added a listener that a parent component already registers. It “fixed” a type and moved the bug somewhere else.

That isn’t a skill problem. Agents are excellent at reading code. It’s a sequencing problem: they’re asked to edit before they’ve been asked to understand.

So I flipped the order. Every session starts with a map.

Anchors, bridges, blast radius

I think of a codebase as three kinds of things:

A good change touches the fewest bridges possible, and checks both sides of every bridge it does touch.

The opening prompt

I don’t start with the task. I start with a mapping request, and I tell the agent explicitly not to edit anything yet.

Before writing any code, map the territory for this task:

1. List the entry points and modules involved.
2. For each, note what it imports and what imports it.
3. Name every bridge this task will cross (API, event, shared state, DB).
4. List anything you can't see both sides of.

Then stop and show me the map. No edits yet.

That last line matters. Asking for a stop gives you a checkpoint where you can correct a wrong assumption for the price of one sentence, instead of untangling forty lines of confident code.

Questions are a feature

Once the map is on screen, I want questions back, not just a plan. If the agent asks “should the progress bar sit above or below the sticky header?”, that’s the workflow working. A question costs a few seconds. A wrong guess costs a review cycle.

I put this into the agent’s standing instructions so I don’t have to repeat it:

If a change requires touching code outside the stated scope,
flag the dependency and stop. Awareness of a dependency is not
an obligation to resolve it.

Verify every bridge you crossed

The map pays off a second time at the end. Before I accept a change, the agent rereads its own diff against the map:

1. Did we cross any bridge that wasn’t on the map? If so, why?
2. For each bridge crossed, are both sides consistent?
3. Did tests or a real browser run confirm it?

This sounds like overhead. In practice it’s a few hundred tokens, and it catches the class of bug that otherwise only shows up in production.

The short version

The agent is still doing the heavy lifting. You’re just making sure it has looked at the whole board before it moves a piece.

If you want the full set of prompts I use for this, it’s Play #1 in the free AI Builder’s Playbook.