5 Code Review Checklist Items for Agent and Human Teams

A pull request lands with 400 changed lines and no clear goal. You open the diff, scan the tests, and wonder whether to start with database calls, permissions, or the feature itself. An agent might have written the code, but you're still responsible for deciding whether it should ship.

A short, shared code review checklist gives agents and people the same starting point. The agent gathers evidence and flags mismatches. The human checks intent, trade-offs, and anything the agent can't verify.

I'd rank these checks by the rework they can prevent, starting with spec adherence. That's a practical priority order, not a universal benchmark of minutes saved. Your repository may need a different order, especially for sensitive changes.

Use the same questions for agents and humans. Give them different responsibilities, not different standards.

1. Spec Adherence

Check that the code implements the approved design, without expanding or changing it. There's little value in polishing an implementation of the wrong behavior.

Say the design requires workspace owners to invite members. The pull request lets every member send invitations. The code may be readable and the tests may pass, but the implementation still misses the requirement.

The OWASP Web Security Testing Guide recommends validating code against business requirements, including availability, confidentiality, and integrity. That gives reviewers a stronger basis for approval than whether the implementation looks reasonable.

In Loupe, a second agent checks each pull request against the approved technical design before human review. Failed reviews go through fix rounds until they pass. Spec adherence is our first priority for saving review time, because reviewers shouldn't spend their attention on code that's off-target.

Make the Design Checkable

Write requirements that name the actor, action, constraints, and expected result. Replace vague phrases such as support invitations with the actual permission rules and failure behavior.

• Require evidence. Ask the reviewer to connect each requirement to a changed file, test, or preview behavior.
• Identify extra scope. Separate necessary implementation details from unrelated features and refactors.
• Escalate ambiguity. Let a person decide unclear product behavior rather than letting an agent invent an answer.

This matters when choosing AI code generation tools: generating code and verifying its intent are different jobs.

Track fix rounds per card, and read the reasons behind them. An early correction is useful. Repeated corrections for the same vague requirement mean the design needs work, not another checklist question.

2. ADRs and Known Patterns

A developer adds a direct payment-provider call inside a request handler. It works, but the project already routes payment operations through background jobs so retries don't depend on an open browser request. The reviewer needs to catch the architectural mismatch, not debate indentation.

An Architecture Decision Record, or ADR, is a short document explaining a technical choice and why the team made it. Michael Nygard popularized ADRs in his 2011 blog post, Documenting Architecture Decisions. Keep them in a docs folder in the Git repository so reviewers can read them alongside the code.

Compare Against Decisions, Not Preferences

The OWASP testing guidance includes manual inspection of documentation, requirements, security policies, and architectural designs during development. Use those artifacts to explain why a change conflicts with the system.

Keep each ADR focused on context, decision, and consequences. Link relevant ADRs from the technical design, and include nearby examples of accepted patterns.

A project-specific skill can tell an agent where those documents live, which modules demonstrate the preferred approach, and when to ask for human approval. That keeps repository details out of the shared checklist while making them available during review.

Practical rule: Ask for the existing pattern before asking for a new abstraction.

Don't enforce history blindly. A previous decision may no longer fit the product. Review ADRs every few months and mark replaced decisions as superseded.

Your software design review process should make exceptions explicit. If the payment change needs synchronous execution, ask the author to explain the trade-off and update the decision record rather than bypassing it.

3. N+1 Queries

Loading 100 orders and then fetching each order's customer separately means 101 queries. That's an N+1 query: a query loads a collection, then additional queries load related records for each item.

Small development fixtures can hide this pattern. A list page looks fine until the reviewer tries a fuller dataset or checks the query log.

Start with loops that access ORM relationships. Check serializers, templates, computed properties, and helper methods too. The database call may sit behind a harmless-looking field access rather than an obvious query statement.

Measure Before Approving

Give the agent a concrete task: identify changed collection endpoints, inspect relationship access, and provide query-count evidence.

• Rails. Use the Bullet gem to warn about N+1 queries in development. Consider includes for needed associations.
• Django. Use django-debug-toolbar to inspect query counts. Choose select_related or prefetch_related according to the relationship.
• Java. Use Hibernate statistics to inspect statement counts, then review fetch joins or batching where appropriate.

Add a query-count assertion to tests for important list endpoints. Use fixtures with enough related records to expose repeated fetching. Check query logs on preview deployments before merging, especially when rendering logic differs from the unit test setup.

Don't eager-load every relationship as a blanket fix. That can fetch unused data and increase memory use. Load what the response needs, preserve pagination, and check the resulting SQL.

An agent can identify suspicious access patterns and propose a fix. A human should judge whether the endpoint needs all that data at all. Sometimes the better change is a smaller response, not a more complicated query.

4. Security

A clean scan isn't proof that a change is safe. Automated tools can flag dangerous code patterns, but they can't decide every permission rule or understand every sensitive business action.

Use the OWASP secure code review guidance as a baseline. It covers authentication, authorization, input handling, secrets, sensitive data, and other security review areas. The OWASP Top 10 helps identify common risk categories, while the Application Security Verification Standard provides verifiable requirements.

Split Scanning From Permission Decisions

Run static analysis on every pull request. Semgrep, CodeQL, and Bandit are options for code scanning, depending on your stack. Dependabot on GitHub can alert the team to vulnerable dependencies.

Then review the changed behavior directly:

• Authorization. Check server-side access rules for every new route and object lookup.
• Input handling. Validate external input at the boundary and parameterize database queries.
• Secrets. Keep credentials out of code, logs, and error messages. Use environment variables or a secret manager.
• Sensitive changes. Give authentication, sessions, permissions, and data exports explicit human attention.

For example, a new invoice-download endpoint might require login but still accept any invoice identifier. Test whether a user can retrieve another workspace's invoice. Authentication alone doesn't establish permission.

A security finding should explain who can do what, which boundary they cross, and where the evidence appears.

Hosting choices don't replace these checks. Teams considering self-hosted project management still need to review application permissions, secret handling, and dependency changes.

Treat security as a merge gate, even though it appears later in this time-saving order. Priority by review effort isn't priority by potential harm.

5. Test Coverage for Changed Code

Ask what behavior the tests prove, not just which lines they execute. A test can run the changed code without checking the outcome that matters.

For a duplicate-payment bug, require a regression test that reproduces the duplicate request and fails before the fix. Then check the response and the persisted payment state. A test that merely completes without throwing doesn't establish that the bug is gone.

Put Repository Rules in a Skill

Use a project-specific skill to define test commands, fixture conventions, required integration checks, and acceptable mocking boundaries. Agents and people should follow the same standard, without remembering another set of unwritten rules.

A developer survey reported by The Register found that roughly 60% of AI users for testing, writing, or review said the assistant misses relevant context. Give the agent that context explicitly, and allow it to report that a behavior isn't verifiable from the diff.

• Cover outcomes. Test the main path, relevant edge cases, and expected failures.
• Inspect test changes. Look for removed assertions, skipped cases, and snapshots updated without explanation.
• Verify execution. Record the command, result, and anything that couldn't run.
• Protect real boundaries. Mock external services where needed, but don't mock away the behavior under review.

Don't demand the same test mix everywhere. A permission change needs access-control tests. A migration needs checks against representative existing data. A copy update may need a build and preview review rather than another unit test.

Require tests in the same pull request as the behavior change. When a test isn't practical, ask for a specific explanation and alternative evidence, not a promise to add it later.

How the five code review checklist items compare

Start With Two Checks and Grow From There

Start with spec adherence and tests. Run them on your next five pull requests and track fix rounds, then add ADR checks, N+1 checks, and security scans individually. Keep existing security gates in place while you test the new review process.

Use a short review record: the requirement checked, the evidence, the finding, and its resolution. Separate blocking defects from optional suggestions. Don't count completed boxes or comment volume as proof of a better review.

Track Waiting as Well as Rework

A large pull-request analysis described by LinearB found that half of pull requests remained idle for 50.4% of their lifespan. A more thorough checklist won't fix a review that nobody picks up.

Assign a reviewer and measure pickup time separately from active review. Compare similar changes when checking fix rounds and hours to merge. A complex migration shouldn't be judged against a small interface edit.

Keep the core short: Put shared expectations in the checklist and repository-specific instructions in skills.

Give each skill an owner. Update it when commands, architecture, or deployment practices change, and remove prompts that generate repetitive noise. Let agents return not verifiable when they lack evidence rather than forcing a reassuring answer.

The goal isn't to remove people from review. It's to give them a change that's already been checked against its purpose, project rules, database behavior, security boundaries, and tests. Humans can then focus on the decisions that still need judgment.

---

Loupe connects coding agents to a staged workflow with approved designs, agent review, human checkpoints, and fix-round analytics. Visit Loupe to explore using a shared code review checklist from technical design through live review.