Before an AI Agent Changes Code, It Needs a Map of What Breaks

A three-line change to a utility function looks harmless in a diff. Then a test two packages away fails. Then a permissions check that called the same helper starts behaving differently in staging. Then someone asks why the dependency lockfile moved. None of that was visible in the three lines.

This is the gap I care about when I evaluate autonomous coding agents. The pull request is the output of a reasoning process. It is not the reasoning itself. A diff is necessary context for a reviewer, but it is incomplete context for whoever, or whatever, made the change. Before an agent touches code, it needs a map of what that code is connected to, or it is guessing with write access.

The diff is the receipt, not the reasoning

When a human engineer makes a change, they carry context that never appears in the pull request. They know the ticket's history, which team owns the calling service, which conventions the repository enforces, and which tests are flaky versus load-bearing. Reviewers then reconstruct part of that picture from the diff, the description, and linked issues.

GitHub's own review guidance reflects this. Reviewers are expected to understand the purpose of a change and its linked context, then examine the changed files and the review evidence before approving. The GitHub pull request review documentation treats the diff as one input among several, not the whole story.

An autonomous agent has no hallway knowledge. Everything it needs must be retrieved, indexed, and checked explicitly. If the system cannot reconstruct the context a good human reviewer would want, the agent is producing plausible diffs, not understood changes.

The context stack an agent needs before it writes code

I think about this as a stack of layers. Each layer answers a question the diff alone cannot.

Task intent. What is the ticket actually asking for, and what would count as done? An agent that starts from a vague prompt will produce a vague change. Intent needs to be captured, structured, and traceable back to the source request.

Symbol definitions and references. Where is the function defined, and where is it used? This is the same model behind code navigation tools engineers use daily. GitHub's code navigation documentation describes moving from a symbol to its definitions and references. An agent needs that reachability mechanically, not by scanning files and hoping.

Dependency reach. What does this change pull in, directly and indirectly? A dependency change can have effects well beyond the visible source diff, including indirect updates and security impact that need separate review. GitHub's dependency review guidance exists precisely because the diff understates the blast radius.

Repository conventions. Naming, structure, test placement, error handling patterns. Conventions are rarely written down completely, but they are visible in the codebase, and an agent should follow what the repository already does.

Tests and CI. The change must be exercised by the same pipeline a human change would face. CI is not a formality at the end. It is part of the definition of the change.

Review and merge controls. The output goes through the same review path as everything else. Autonomy upstream does not mean exemption downstream.

Skip any layer and the agent is operating on partial information. The failure mode is not dramatic. It is a steady stream of small, confident mistakes.

How we built this into Workforce

This reasoning shaped how we built Workforce. Synths are coordinated across the repository lifecycle, from ticket intake through pull request review, CI checks, and merge. That lifecycle exists on the public Workforce Build page, and the sequencing is deliberate. Intake comes first because intent comes first.

Before changes are made, the code is indexed into entities and relationships. That index supports semantic search, dependency traversal, and impact analysis. When a Synth approaches a task, it can ask the questions from the context stack: what is this symbol, who references it, what depends on this package, what breaks if this contract changes. The code knowledge graph is how those questions get answered with the repository's own structure rather than with a guess.

I want to be precise about what this does and does not mean. A knowledge graph does not make autonomous changes safe by itself, and no system catches every consequence. What the graph does is give the agent a factual basis for the pre-change questions a senior engineer would ask instinctively. Impact analysis narrows the unknown. It does not eliminate it. That is why review, CI, and merge controls remain part of the lifecycle rather than optional extras.

The principle generalizes beyond our product. Whatever autonomous system you evaluate, ask where its map comes from. If the honest answer is that the model reads the diff and the surrounding files at inference time, you are looking at a fast reader, not a system that understands the repository.

A checklist for evaluating an autonomous coding system

Before letting an agent open pull requests against a production repository, I would want clear answers to these questions.

1. Intent. Does the system capture task intent from the source ticket, and can you trace every change back to it?

2. Symbols. Can it resolve definitions and references across the repository, so it knows who calls what it is changing?

3. Dependencies. Does it analyze direct and indirect dependency impact before changing code, not after a reviewer asks?

4. Conventions. Does it follow the repository's existing patterns, or does it impose the model's defaults?

5. Verification. Do its changes pass through the same tests and CI as human changes?

6. Review. Does its output enter the normal pull request review path, with linked context and inspectable evidence?

7. Blast radius. Can it show you an impact analysis for a proposed change before that change exists?

A system that answers these well is doing something meaningfully different from autocomplete with ambitions. It is treating the repository as a connected structure, and the pull request as the last step of a process rather than the first artifact anyone sees.

The three-line change from the opening is fine, as long as something checked the other side of it first. That is the whole point. The map comes before the edit.