A review checklist for AI coding agent output (7 things I check before trusting a change)

Every software development team that employs an AI coding agent encounters a common challenge: the sheer volume of agent output becomes a bottleneck. Reviewing this output is no longer a simple task. To address this issue, I have devised a comprehensive checklist that ensures the trustworthiness of any change generated by the agent. The checklist consists of seven essential criteria, each accompanied by the tooling required for its implementation.

1. Diff-based verification: The first step is to ensure that the change can be presented as a diff rather than just a prose summary. This verification is crucial because reviewing a claim rather than actual code is insufficient for trust. If the only result is a summary, requesting a diff should be the first action taken.

2. Directory specificity: It is vital to determine the precise directory in which the agent operates. Ambiguity in the working directory can lead to unfortunate incidents where the agent unintentionally modifies the wrong file. Explicitly pinning the path and documenting it within the job record helps prevent such errors.

3. Isolated ref check: The change generated by the agent should be isolated within a reference that can be checked out. This isolation can be achieved through a branch or a worktree. By isolating the change, one can independently test it, revert any modifications, and compare the results without risking the integrity of the main codebase.

4. Command execution and network interactions: It is crucial to identify the commands run by the agent and determine whether any of them involve network interactions. Scripts that install dependencies or execute curl commands are particularly prone to introducing vulnerabilities or unintended behavior. Logging the tool activity, rather than solely focusing on the final text, provides a comprehensive view of the agent's activities.

5. Credential management: The source highlights the importance of understanding the origin of credentials used by the agent. If the agent requires access to a private remote, the associated token should be scoped to the specific host and limited in duration. Providing broad credentials to an autonomous process increases the risk of incidents, as a minor mistake can escalate into a significant security breach.

6. Reproducibility by a second person: To ensure the reliability of the agent's output, the task should be reproducible by a second individual. The setup should involve the same image, runtime, and starting commit. If replicating the task proves challenging due to verbal explanations or nuances, it indicates that the process is not yet fully established.

7. Termination states: The checklist emphasizes the significance of identifying the termination states of the agent's session. Whether the termination is due to a time limit, token limit, an approval gate, or completion, it is essential to capture this information unambiguously. A shared status glossary can help eliminate ambiguity during handoffs and ensure a clear understanding of when the task is finished.

The implications of implementing this checklist are far-reaching. It necessitates the adoption of explicit working directories and state management, ensuring that each agent task operates within a disposable and isolated workspace. This approach prevents a malicious or faulty run from compromising subsequent tasks. Furthermore, utilizing native workspaces for Git reviews rather than bolt-on solutions enhances the overall workflow.

Automations that repeat routine tasks should have their own dedicated audit trail, ensuring accountability and traceability. Lastly, running the entire setup in an environment that mirrors the production codebase is crucial to address the credential question effectively.

Once this checklist is documented, its requirements naturally follow. The checklist influences the design of the system, driving the need for a control plane that provides each task with its own workspace, reviewable sessions, and the ability to generate Git changes as branches or worktrees for further testing. The TaskHandoff framework, which adheres to the Apache-2.0 license, encapsulates these principles.

It offers a self-hosted solution with documentation available at docs.thandoff.com, starting with installation instructions and a frequently asked questions section.

As I reflect on this checklist, I am acutely aware of the lessons learned from past experiences. The initial approach of employing the agent directly within a critical checkout proved to be problematic. The lack of isolation and visibility led to unnoticed dependency changes, manifesting only during deployments. This oversight went undetected for weeks until the impact became apparent.

Since that realization, I have adopted the recommended workflow of running every agent task within a disposable workspace, utilizing the diff as the primary deliverable. This approach ensures greater control, reliability, and a higher level of trust in the agent's output.

In summary, the checklist serves as a comprehensive guide for reviewing AI coding agent output, addressing potential pitfalls and ensuring the integrity of the resulting changes. By adhering to these criteria, teams can mitigate risks, enhance reproducibility, and establish a robust and trustworthy development process.