Establishing Operational Zones

To safely introduce agents into legacy codebases, categorize the repository into zones based on risk and quality.

• Green Zone: High-quality tests, modern conventions, and isolation. Agents can operate here in tight loops.
• Yellow Zone: Mixed quality. Agents may work here only after characterization tests are written and the module owner reviews initial changes.
• Red Zone: Sensitive areas like authentication, billing, or permissions. These require human pairing for every step.

Crucially, humans must define these zones, not agents. Zones should only be promoted (e.g., yellow to green) once characterization tests exist and human review is established.

Building a Durable Harness

Agents often lose their "research" (understanding of flows, owners, and dependencies) when a session ends. To prevent repeated archaeology, require agents to produce durable artifacts like comprehension memos.

Treat the agent's environment as a harness. If an agent makes a mistake, do not just fix the code; update the harness—add lint rules, type checks, or tests—so the team never pays for that failure twice. If a correction is repeated, it is a missing piece of the harness.

Prioritizing Verification Over Generation

Agents have lowered the cost of attempting multiple implementation paths, but they have not changed the evidence required to choose one.

• Characterization Tests: Before refactoring, lock current behavior with tests that pin down existing functionality, even the "ugly" parts.
• Complete Units: Avoid partial migrations. A migration is only complete when the new path works and the old dependency is demonstrably removed. Leaving both patterns alive creates "migration blindness" and confuses future agents.
• Parallelization: Only parallelize agent workflows once a single unit has a dependable judge, recovery path, and review format. Parallelizing too early simply multiplies the bottleneck of human review.

Managing Ambiguity

Agents make the cost of tribal knowledge and ambiguous conventions visible. When an agent struggles with undocumented trade-offs or team-specific nuances, it is a signal to document those constraints explicitly. Write down what the code cannot say—historical context, trade-offs, and domain rules—to provide the agent with the necessary context that static analysis cannot infer.