Architecting Intent-Driven Code Review Systems with AI Agents
This article discusses an architectural approach to modernizing code review using AI agents. It proposes shifting verification tasks to AI while retaining human judgment, leveraging 'invariants' and 'acceptance criteria' to guide AI agents. The system focuses on capturing intent, decisions, and evidence to facilitate human review, thereby streamlining the development pipeline and improving code quality through automated, consistent checks.
Read original on The New StackThe traditional line-by-line code review, while valuable, can be slow and inconsistent. This article introduces an intent-driven review system that redefines the roles of humans and AI in the code review process. The core idea is that AI agents should handle the verification of code changes against predefined rules and criteria, while human developers retain the critical role of judgment and accountability.
The Two Layers of Verification: Invariants and Criteria
The proposed system relies on two fundamental layers for automated verification:
- Invariants: Codified rules and standards of an engineering organization or team. These are persistent, always-true rules (e.g., "Use Money type for currency," "No direct writes to the users table"). They act as an "AI slop registry" to prevent recurring mistakes.
- Acceptance Criteria: Specific requirements describing what a particular change should do. These are derived from the coding session, capturing the intent and expected behavior in real-time.
Architecturally, invariants are critical for enforcing consistency across a large codebase and multiple teams. They act as a shared knowledge base for engineering standards, reducing cognitive load on individual developers and ensuring compliance. This shifts a significant portion of quality assurance left in the development lifecycle.
The Seven Parts of an Intent-Driven Review Workflow
- Invariants: Defined before any change, often drafted from existing PR comments and documentation.
- Intent and Acceptance Criteria: Captured directly from the coding session where the engineer and AI agent define the 'why' and 'how' of the change.
- Core Decisions: Records architectural or implementation choices made during development, attributing them to human or AI.
- Test Plan: Automatically generated scenarios from criteria and invariants to validate behavior.
- Evidence: Collected from a running preview environment (screenshots, logs, DB state) to prove compliance with criteria and invariants.
- Review: Human reviewers assess intent, decisions, and evidence (not line-by-line code), focusing on judgment.
- Invariants Refreshed: Continuous improvement of invariants based on waivers and recurring comments, making the system self-optimizing.
This structured approach ensures that the verification is robust and evidence-based, allowing human reviewers to focus on higher-level decisions and trade-offs rather than syntax or common errors. The system effectively leverages AI for scalable, consistent verification, while humans provide the indispensable context, judgment, and accountability.