Skip to content
Back to all notes
AI & Agents

Give Your Coding Agent a Map

≈ 3 min read

Ask a coding agent to change how a user creates a project, and it first has to figure out where that behavior lives. It searches for relevant terms, reads a few files, follows imports and references, and gradually pieces together enough of the application to make a change. Then it edits, runs tests, and goes back to searching when something doesn't work as expected.

The tools available for this are mostly quite basic: grep, file patterns, directory trees, and, depending on the setup, semantic search or symbol lookups. Tests and compiler errors help it work out whether it's on the right track. All of this is useful, but the agent is still building its understanding as it goes.

Eventually, it might work out the whole chain from a user clicking a button, through the frontend handler and API, to the service that writes to the database. The problem is that much of this understanding only exists in the current context. The next time an agent works on the same feature, it may have to figure out those relationships all over again.

Illustration of a coding agent handling the request “Let users archive a project.” The agent lists the repository, searches for related code, reads the service, its route, the menu component, and the tests, and only then edits three files. A failing test points to a type it missed, so it searches for that type, fixes it, and reruns the tests. The run is illustrative, not recorded.

How a coding agent finds its way today

illustration

Let users archive a project.

Agent run

waiting
  1. searchlslook at the repo
  2. searchrg --files | rg -i projectfind entry points
  3. searchrg -i "archive" src/look for related code
  4. readservices/projectService.tsread the service
  5. searchrg "projectService" src/trace references
  6. readroutes/projects.tsfollow the route
  7. readcomponents/ProjectMenu.tsxfind the UI entry
  8. readtests/projectService.test.tscheck the tests
  9. editservices/projectService.ts +2edit after 8 steps
  10. testnpm testProjectDTO lacks field
  11. searchrg "ProjectDTO" src/find the missed type
  12. edittypes/project.ts
  13. testnpm testall tests pass

0 searches · 0 files read · 0 test runs

A typical run: search, read, edit, test, and repeat until the change holds. What the agent learns about the flow along the way stays in its context.

I'd like to try giving the agent a better starting point: a maintained map that connects what a user does to the code that makes it happen. For “Create Project”, for example, the map could show the user flow, the steps involved in the implementation, their dependencies, and the relevant source files. The agent would have somewhere concrete to start looking.

I think this could be especially useful in older codebases. Documentation is often incomplete, patterns have changed over the years, and similar features may have been implemented in very different ways. If the code doesn't follow the conventions an agent expects, even finding the right place to make a small change can take quite a bit of exploration.

The idea would be for the coding agent to maintain this map as it works. That could also make it useful beyond the agent itself. Developers would have a way to trace a feature through the application, while designers and product teams could start from a familiar user action and see how it connects to the implementation.

Animated illustration. A developer asks a coding agent for three features in an example project, one after another. After each feature, a stop hook updates a UX/action map: a flow chart of the codebase that links each user action to the frontend, backend, and data areas it runs through. From the second feature on, the agent reads the map before it changes code. Areas and links added by the latest feature are highlighted.

You request a feature

Let users create a project.

Agent implements it

0 files changed

Hook updates the map

Stop → update-action-map

UX/action map of the codebase

Flow chart of the underlying code, from user action to data

empty map

swipe the map →
1 / 3
After each change, an agent hook (for example a stop hook in Claude Code or Codex) updates the map. Orange marks what the latest change added.

Of course, the agent would still need to check the actual code. A map can become outdated, and a connection recorded during an earlier task may no longer hold. It should help the agent decide where to look and what might be affected, with code search and tests still doing their part before a change is considered complete.

What I'd hope to gain is less time spent rediscovering the same relationships and less context used on getting oriented. If the map also helps the agent see where a feature begins and ends, it might reduce accidental changes to unrelated behavior. That's what I'd want to test.

Illustration comparing two runs of the same request, “Let users archive a project.” Without a map, the agent searches the repository, reads files, edits, and only finds a missing type after a failing test. With the action map, the agent opens the related flow first, verifies it against the code, edits the listed files, and a hook adds the new flow to the map. The runs are illustrative, not measured.

Same request, two starting points

illustration · not a benchmark

Let users archive a project.

Without a map

waiting
  1. searchlslook at the repo
  2. searchrg --files | rg -i projectfind entry points
  3. searchrg -i "archive" src/look for related code
  4. readservices/projectService.tsread the service
  5. searchrg "projectService" src/trace references
  6. readroutes/projects.tsfollow the route
  7. readcomponents/ProjectMenu.tsxfind the UI entry
  8. readtests/projectService.test.tscheck the tests
  9. editservices/projectService.ts +2edit after 8 steps
  10. testnpm testProjectDTO lacks field
  11. searchrg "ProjectDTO" src/find the missed type
  12. edittypes/project.ts
  13. testnpm testall tests pass

0 searches · 0 files read · 0 test runs

With the action map

waiting
  1. mapopen flow "Create project"3 areas · 7 files

    Create projectProjects UIProjects APIProjects table

  2. readservices/projectService.tsverify against code
  3. readtypes/project.tsverify the DTO
  4. editservices/projectService.tsedit after 3 steps
  5. editroutes/projects.ts
  6. edittypes/project.ts
  7. editcomponents/ProjectMenu.tsx
  8. testnpm testall tests pass
  9. hookStop → update-action-mapadds “Archive project”

0 map lookups · 0 files read · 0 test runs

A note on the comparison above: both runs are illustrations of the idea, not recordings or benchmark results. I haven't built or measured this setup yet, so the step counts only show where a map could change the agent's path, not how much it would save.