Why I Built This Agent

As an architect, I review code as an implementation of the system’s design, not as an isolated collection of classes and methods. Every change either preserves or weakens architectural boundaries, service contracts, data integrity, security posture, failure behavior, operational readiness, and the system’s ability to evolve. A successful build and a passing test suite establish local correctness; they do not establish architectural integrity.

In most engineering organizations, the challenge is not the absence of standards. It is that those standards are distributed across architecture documents, coding guidelines, review checklists, and the experience of individual reviewers. Their application becomes inconsistent, and the first architect review is frequently spent identifying repeatable issues that should have been resolved before the code reached formal review.

I developed SmartCodeReview as a complete Java and Spring Boot Order Management microservice, with the AI review architecture versioned alongside the system it evaluates. The microservice provides a realistic engineering surface across REST contracts, transaction boundaries, persistence, database migrations, security, concurrency, operational health, integration testing, and coverage enforcement. This allows the agent to evaluate how these concerns interact across the repository rather than treating them as independent code checks.

The review model makes architect-level standards explicit, version-controlled, and executable. Repository context, review orchestration, control criteria, evidence requirements, scoring logic, verdict gates, and report structure are defined as separate but coordinated parts of the system. The agent therefore operates against an established review contract rather than a generic instruction to “review this code.”

Source code: SmartCodeReview on GitHub

The purpose is not to replace architectural judgment. It is to standardize the repeatable analysis that precedes it, so developers receive stronger evidence-based feedback before submitting a pull request and architects can focus on system-level risk, design tradeoffs, cross-service decisions, and long-term technical direction.

The Version-Controlled Review Architecture

The design of SmartCodeReview separates four concerns that are often compressed into a single prompt: repository context, review orchestration, decision policy, and report presentation. Each concern is defined independently, versioned with the codebase, and assigned a clear responsibility within the review process.

SmartCodeReview/ ├── AGENTS.md ├── code-review └── .agents/skills/code-review/ ├── SKILL.md └── references/ ├── REVIEW_CONTROLS.md └── REPORT_FORMAT.md
This separation is deliberate. Repository standards change for different reasons than scoring rules. Review procedures evolve independently of report presentation. Keeping those concerns distinct makes the review model easier to govern, audit, and extend without turning one instruction file into an unmaintainable collection of rules.

AGENTS.md — Repository Context and Engineering Standards

AGENTS.md defines the architectural and engineering contract of the repository. It describes the intended package structure, dependency direction, API boundaries, transaction ownership, persistence conventions, security expectations, operational behavior, testing requirements, coverage thresholds, and approved verification commands.

For example, the Order Management microservice requires dependencies to follow:

controller → service → repository → entity
Controllers operate through DTOs, services own business decisions and transaction boundaries, and repositories remain focused on persistence. These are not generic best practices inferred by the model. They are explicit repository constraints against which the implementation is evaluated.

This distinction is fundamental. An agent may recognize common patterns without repository context, but it cannot determine architectural drift unless the intended architecture has first been made explicit.

SKILL.md — Review Orchestration

SKILL.md defines how the review is conducted. It establishes the reviewer posture, determines the active scope, directs evidence collection, coordinates the supporting files, and defines how conclusions must be formed.

The skill requires the agent to inspect changed code in context rather than treating a diff as an isolated artifact. It may follow callers, interfaces, configuration, persistence behavior, and tests when they are necessary to establish impact. At the same time, it prevents the review from expanding into unrelated parts of the repository.

It also governs the quality of the reasoning. Findings must be supported by evidence, grouped by root cause, and classified appropriately. When the repository does not contain enough information to support a conclusion, the result is recorded as UNVERIFIED rather than being replaced with an invented organizational, operational, or compliance requirement.

REVIEW_CONTROLS.md — Controls, Scoring, and Verdict Gates

REVIEW_CONTROLS.md converts engineering expectations into an auditable control model covering architecture, maintainability, API design, security, reliability, persistence, and testing.

Every control receives exactly one status:

PASS | PARTIAL | FAIL | UNVERIFIED | N/A
The model separates standards satisfaction from evidence coverage. Standards satisfaction measures how completely the verified controls are met. Evidence coverage measures how much of the applicable review surface could actually be evaluated.

That separation prevents incomplete evidence from being presented as strong assurance.

The control model also defines category weights, acceptance baselines, severity levels, and ordered verdict gates. A verified High or Blocker finding can override an otherwise acceptable numerical score. The score therefore represents satisfaction of verified controls; it is not treated as a percentage of source code that is correct, secure, or production-ready.

REPORT_FORMAT.md — The Review Output Contract

REPORT_FORMAT.md defines how the assessment must be communicated. It requires a decision-first report containing the executive assessment, review scope, category scorecard, verified findings, evidence gaps, positive engineering decisions, verification results, developer actions, architect decisions, and final recommendation.

Each material finding must identify the relevant control, severity, exact location, observed behavior, failure scenario, impact, recommended correction, verification method, confidence, and decision owner.

This structure prevents verified defects, missing evidence, and architecture decisions from being collapsed into one undifferentiated list of observations. It also ensures that the report remains actionable for both developers and architects.

Together, these components form a version-controlled review architecture:

AGENTS.md defines the system context, SKILL.md governs the review, REVIEW_CONTROLS.md converts evidence into decisions, and REPORT_FORMAT.md governs how those decisions are communicated.

The code-review launcher connects these components to the repository workflow; its execution model is covered in the following sections.

Full Repository Review on Main and Delta Review on Feature Branches

On main, the agent performs a complete repository assessment and establishes the current engineering baseline. It evaluates the application code together with its configuration, database migrations, tests, build controls, and supporting repository artifacts.

On a feature branch, the launcher automatically selects main, or origin/main when a local baseline is unavailable, and calculates the merge base with the current branch. The review is then scoped to files added, modified, renamed, or deleted since that point. It begins with the delta but follows surrounding contracts, callers, dependencies, configuration, persistence behavior, and tests when that context is necessary to determine the broader impact of the change.

This distinction avoids two inefficient review patterns: reassessing the entire repository for every pull request and reviewing changed lines without understanding how they affect the system around them. The same launcher also supports an explicit full-repository review, staged changes, and comparison with a specified base revision.

./code-review # main: full review; feature branch: automatic delta ./code-review --repository # explicit full repository review ./code-review --staged # staged changes only ./code-review origin/main # explicit comparison base
The scope therefore follows the engineering intent of the review: establish a baseline on main, evaluate change impact on feature branches, and preserve architectural context without expanding into unrelated code.

From Repository Evidence to an Architect-Ready Decision

The code-review launcher converts the review model from documentation into an executable engineering workflow. It first resolves the repository, current branch, review mode, comparison base, merge base, and working-tree state. Before Codex evaluates the implementation, the launcher runs the repository’s required test, build, and coverage commands and preserves their exit status and generated evidence.

The ordering is important. The agent does not infer whether the project builds or whether its quality gates pass. Those results are produced by the build system and supplied as evidence to the review. Codex then loads AGENTS.md, SKILL.md, REVIEW_CONTROLS.md, and REPORT_FORMAT.md, inspects the applicable repository scope, and evaluates each control exactly once.

The assessment spans seven categories: Architecture and Design, Code Quality and Maintainability, API and Integration Design, Security and Data Protection, Reliability and Operational Readiness, Data and Persistence, and Testing and Verification. Each category has an explicit weight and acceptance baseline.

Two measures are calculated independently. Standards satisfaction represents how completely the verified controls were met. Evidence coverage represents how much of the applicable review surface could be supported by available evidence. This prevents a repository with limited operational or architectural evidence from receiving an apparently authoritative score based only on what happened to be visible.

The numerical result is then subjected to ordered verdict gates. Build or coverage failures, Blocker findings, High-severity findings, insufficient evidence, and material control failures can determine the final decision independently of the weighted score. The score informs the assessment; it does not control it.

The current repository review illustrates that distinction. All three Gradle verification commands passed, 24 tests completed without failure, line coverage reached 97.63%, and branch coverage reached 85.71%. The overall standards score was 85.33%, slightly above the configured baseline, with 82.05% evidence coverage. The review nevertheless identified two developer implementation defects and three unresolved production architecture contracts. Developer implementation therefore requires changes architect review is ready for architect decision, and production remains not ready until those production contracts are decided, implemented, and verified.

The report makes that reasoning visible. Its category assessment shows where the repository meets its baseline, where it falls below it, and where evidence remains incomplete. The decision summary then separates local developer corrections from production contracts that require architect ownership. The latest review presents these results through the Markdown source report and its rendered HTML representation.

The complete report produced by SmartCodeReview is available here: Architect-Level Code Review Report. It includes the executive decision, build and coverage evidence, seven-category assessment, standards satisfaction, evidence coverage, developer corrections, architect decisions, and final exit criteria.

This is the point at which automated analysis becomes a governed engineering decision: repository evidence is evaluated against explicit standards, uncertainty remains visible, and severity retains precedence over an attractive score.

Separating Developer Corrections from Architect Decisions

An effective architecture review must distinguish between an implementation problem and a decision that the implementation team is not authorized to make.

When an established repository standard has been violated, the developer owns the correction. In the current review, loading the complete order table before applying pagination and issuing the same findById query twice are developer-level defects. The expected behavior is already defined, the correction is local to the implementation, and focused tests can verify that it has been resolved.

Other findings reach a different boundary. The repository may show that PostgreSQL is declared without an approved deployment and recovery model, that JWT security is configured without a verified issuer and JWKS contract, or that application roles exist without formally assigned provisioning and revocation ownership. These are not necessarily flaws in the implemented application architecture. They are unresolved production contracts that require architect direction.

The architect must determine the operating model, platform ownership, trust boundaries, failure behavior, and accepted risk. The developer then implements the selected approach and supplies executable evidence that the code conforms to that decision.

SmartCodeReview therefore separates findings into two governed paths:

Developer corrections address implementation behavior that contradicts an established standard.

Architect decisions establish platform, security, operational, and ownership contracts that the repository cannot decide independently.

This distinction prevents the agent from pretending to replace architectural authority. It standardizes what has already been decided, exposes where the implementation diverges, and routes unresolved decisions to the architect with the evidence needed to evaluate them.

The result is a cleaner pull-request boundary: developers resolve repeatable implementation issues before formal review, while architects focus on the decisions that genuinely require system context and architectural judgment.

Standardizing Architectural Conformance Without Replacing Architectural Judgment

SmartCodeReview standardizes the parts of application review that should not vary between developers, teams, or individual reviewers. Scope selection, repository context, evidence collection, control evaluation, severity, scoring, and report structure are governed by version-controlled review policy rather than an open-ended prompt.

Within that boundary, the agent can determine whether a pull request conforms to decisions that have already been made. It can identify violations of approved dependency direction, DTO boundaries, transaction ownership, persistence rules, API semantics, security controls, reliability expectations, and testing requirements. Because the standards are explicit, the review is repeatable, and its conclusions can be traced back to repository evidence.

Architectural authority begins where the repository can no longer determine the correct answer. Production topology, platform selection, cross-service contracts, identity ownership, data-governance policy, recovery objectives, operational accountability, and accepted technical risk require wider system and organizational context. The agent may expose the decision, describe the risk, and identify the evidence that is missing, but it should not invent the governing requirement or make the final choice.

The report preserves this boundary by keeping developer corrections, architect decisions, and evidence gaps separate. Developers receive actionable findings for work already governed by repository standards. Architects receive the unresolved contracts and risk decisions that require broader technical authority.

The objective is therefore not automated architecture approval. It is early architectural conformance: enforce established decisions before formal review, make deviations visible, and reserve strategic judgment for the architect.

Conclusion

SmartCodeReview demonstrates that architectural review does not have to begin only after a pull request reaches an architect. Repository standards can be expressed as version-controlled policy, applied consistently to full-repository and feature-branch scopes, and evaluated against build, test, coverage, and implementation evidence before formal review begins.

The agent does not replace the architect or make strategic system decisions. It performs the repeatable work that should already be governed: validating architectural conformance, identifying implementation defects, exposing missing evidence, applying consistent controls, and routing unresolved decisions to the correct authority.

This creates a stronger review boundary. Developers receive actionable feedback while the implementation is still inexpensive to change. Architects receive a decision-first assessment rather than an unstructured list of observations, allowing them to focus on production contracts, system-level tradeoffs, ownership, operational risk, and long-term technical direction.

The broader value is not automated approval. It is a more disciplined engineering process in which architectural standards become explicit, reviewable, executable, and consistently applied across every pull request.