Why AI Coding Agents Need Read-Only Evidence Packets Before Editing Legacy Code

To address this, developers are adopting an "AI codebase archaeology" approach. Instead of permitting an agent to refactor a system immediately, teams enforce a disciplined, read-only phase. During this stage, the agent must produce a small, change-specific evidence packet that links every assertion to verifiable artifacts—such as file paths, symbols, commit histories, characterization tests, or runtime logs—while categorizing claims as confirmed, likely, or unknown.

Structure of a codebase evidence packet

A practical evidence packet is a concise document focused on a single behavior rather than a broad repo summary. It consists of six key parts:

1. Boundaries and Change Question: A single sentence defining the scope, pinned to an exact branch and commit SHA, alongside key environment assumptions.
2. Execution Path: A concrete trace following an input to its side effect, naming exact file paths, symbols, line ranges, and confidence ratings.
3. Historical Context: Targeted Git history signals—using commands like git log -S or file history tracking—to explain why unexpected guards or legacy adapters exist.
4. Characterization Tests: Safety probes that document current system behavior as it actually functions today, providing a baseline before any refactoring starts.
5. Unknowns and Disconfirming Checks: An explicit list of unconfirmed items (such as missing production configs) alongside the cheapest methods to disprove key assumptions.
6. Change Contract: A defined perimeter listing allowed file edits, restricted paths, stop conditions, and human checkpoints for high-risk areas like payment logic or schema updates.

What it means for developers

Implementing this workflow requires teams to split agent tasks into two distinct passes. In the first pass, the agent operates strictly in read-only mode to trace dependencies, run safe local commands, and assemble the evidence packet. Only after a human reviewer verifies the packet does the agent move to the second pass to execute bounded edits on an isolated branch.

This structured process prevents common mistakes, such as treating large context windows as a substitute for runtime proof or saving raw agent transcript dumps as permanent documentation. Instead, teams match the depth of the evidence packet to the blast radius of the proposed change.

Tooling selection is critical when establishing these workflows. Developers can try top AI models cheaply through one API at https://apixoai.online to evaluate how different models handle read-only code exploration, symbol tracing, and disconfirming checks.

Ultimately, teams should measure success by whether evidence packets reduce review times, surface missing requirements before editing begins, and keep agents within approved file boundaries. Using continuous evaluation benchmarks—such as SWE Atlas—helps ensure agents deliver verified code maps before making irreversible updates.

Source: AI Codebase Archaeology: The Evidence Packet to Build Before Your Agent Touches Legacy Code — Towards AI. Written by the Apixo team from that report.