AI-Assisted Code Review as a Complement to the Team

1. What AI-assisted code review actually is

AI-assisted code review means a language model like Claude reads a diff or pull request and automatically comments on issues before a human reviewer even opens the code. The difference from classic static analysis lies in contextual understanding: a linter like PHPStan checks types and signatures against fixed rules, while a language model evaluates code in relation to neighboring files, naming conventions, and the visible purpose of a change. That allows comments that go beyond pure syntax errors, for example flagging that a new method serves the same purpose as an already existing class.

It matters to frame this as an additional review layer, not a replacement. In a layered model, linters and type checkers first catch purely mechanical rule violations, an AI review step then catches semantically obvious problems, and only after that does a human evaluate business correctness and architectural decisions. This order saves time because obvious errors no longer land in the human review loop, but it changes nothing about the fact that approval authority for a change still rests with a person who understands the code and stands behind its consequences.

2. The review workflow: AI as a first pass before humans

The practical value of AI review comes from its position in the workflow: it runs automatically on every pull request, not only when a developer explicitly asks for it. As soon as a branch is pushed, a CI pipeline generates the diff against the target branch and sends it to Claude Code in non-interactive mode. The feedback appears as a comment on the pull request before a human is even assigned. Developers fix obvious problems directly, without spending a review round with a colleague on them.

The effect shows up mainly for smaller but frequent mistakes: missing null checks, inconsistent exception handling, forgotten translation functions in templates, or return types that do not match the PHPDoc annotation. When these points are fixed before the human review even starts, the actual review narrows down to questions that genuinely require domain expertise. It is important to place the AI step as a gate before reviewer assignment, not in parallel to it, otherwise it creates duplicated rather than sequential relief.

3. Strengths: style consistency, mechanical bugs, security patterns

AI review is reliable for patterns that can be derived from the code itself, without knowledge of the business context behind it. This includes violations of documented coding standards, such as missing constructor property promotion, using assert() instead of proper type checking, the @ character for error suppression, or addFieldToFilter() called with a raw integer instead of the ['eq' => $value] array form. Such violations are unambiguously detectable in any Magento project with documented conventions, because the rule holds regardless of the specific business case involved.

A language model is equally good at spotting obvious logic errors like swapped comparison operators, missing breaks in switch statements, unchecked array accesses, or resources that never get closed. The advantage over pure linter rules shows up with security patterns: a model detects unsanitized user input flowing into a database query even when the specific function is not on a known blacklist, because it understands the pattern of where data comes from and how it is used. This strength holds for any change, regardless of the size of the diff.

4. Limits: business logic, architecture, and domain knowledge

As soon as the correctness of a change depends on business context, AI review hits a clear wall. One example: a price calculation that tiers a discount differently for a specific customer segment than for others can be implemented with flawless syntax and still be wrong from a business perspective, because it fails to correctly reflect an agreement made with that customer. A language model does not know this agreement and cannot derive it from the code alone, even when variable names and comments give hints.

The same applies to architectural decisions: whether a new service makes more sense as a standalone module or as an extension of an existing plugin depends on the store's planned roadmap, team experience, and the cost of future migrations. This kind of trade-off requires knowledge of roadmap and past decisions that is rarely fully documented in the repository. An AI review comment that unreflectively rates an architectural decision as "cleanly solved" can create false confidence when the actual trade-off analysis never happened in the first place.

5. Claude Code as a reviewer in everyday development

In practice, Claude Code in non-interactive mode (-p) can be wired directly into existing scripts without a developer manually starting a session. For review purposes, a strictly read-only mode makes sense, one that explicitly disallows file edits, so the review step does not accidentally modify code when it is only supposed to comment. The plan mode with restricted permissions is configured exactly for this purpose.

#!/usr/bin/env bash
# Run a read-only review pass on the current PR diff with Claude Code
set -euo pipefail

# Generate the diff against the target branch
git diff origin/main...HEAD > /tmp/pr.diff

# Headless review run in plan-only mode (no file edits allowed)
claude -p "Review this diff for style violations, obvious bugs, missing \
error handling and PHPStan level 5 issues. Do not comment on business \
logic correctness, only on mechanical and stylistic problems. List \
findings with file, line and severity (low, medium, high)." \
  --permission-mode plan < /tmp/pr.diff > /tmp/review-findings.txt

cat /tmp/review-findings.txt

The restrictive permission configuration for this specific use case is what matters most. A review run should be allowed to read, generate diffs, and call analysis tools like PHPStan, but never write files, create commits, or push. This separation prevents a process intended for review from accidentally making production changes, and keeps the bot's behavior traceable and auditable for the whole team.

{
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Read(**)",
      "Grep(**)",
      "Bash(git diff:*)",
      "Bash(bin/analyse:*)"
    ],
    "deny": [
      "Edit(**)",
      "Write(**)",
      "Bash(git push:*)",
      "Bash(git commit:*)"
    ]
  }
}

6. Automated reviews in CI/CD pipelines

For AI review to actually run before every human glance at the code, the step needs to be anchored in the CI pipeline, not treated as an optional local tool. A typical flow: on every push to a feature branch, a CI job first generates the diff, calls Claude Code with JSON output format, and stores the structured findings as an artifact. A second step reads these findings and posts them as inline comments directly on the affected lines in the pull request, similar to how linter integrations already do for PHPStan or ESLint.

name: ai-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Generate the diff against the PR base branch
      - name: Generate diff
        run: git diff origin/${{ github.base_ref }}...HEAD > pr.diff

      # Headless review run in plan-only mode, no file edits allowed
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review this diff for style and obvious bugs only." \
            --permission-mode plan \
            --output-format json < pr.diff > review-findings.json

      # Post filtered findings as inline PR comments
      - name: Post inline comments
        run: node post-ai-review.js
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

Filtering by confidence before posting matters: low-confidence findings should not surface as comments, because a large number of uncertain hints lowers team acceptance and lets real problems get lost in the noise. A merge gate that fully blocks merging on high-severity findings only makes sense for unambiguously mechanical categories like missing error handling, not for comments on architecture or style, which always require human judgment.

// post-ai-review.js: post Claude Code findings as inline PR review comments
const { Octokit } = require("@octokit/rest");
const fs = require("fs");

const findings = JSON.parse(fs.readFileSync("review-findings.json", "utf8"));
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

async function postComments() {
  const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
  const pullNumber = Number(process.env.PR_NUMBER);

  for (const finding of findings) {
    if (finding.severity === "low") continue; // skip low-confidence noise

    await octokit.pulls.createReviewComment({
      owner,
      repo,
      pull_number: pullNumber,
      commit_id: process.env.HEAD_SHA,
      path: finding.file,
      line: finding.line,
      body: `**[AI Review, ${finding.severity}]** ${finding.message}\n\nPlease verify manually before merging.`,
    });
  }
}

postComments().catch((err) => {
  console.error("Failed to post AI review comments:", err);
  process.exit(1);
});

7. Keeping accountability where it belongs

The most important organizational point with AI review is that the approval decision for a pull request still rests with a named person. A comment from Claude Code is a hint, not an approval. If an AI review pass without any findings gets accepted as sufficient grounds for a merge, responsibility quietly shifts from a person to a tool that has no real capacity to judge business correctness in the first place. This shift only becomes visible once a bug reaches production and no one can be clearly identified as having reviewed it, because formally, no one did.

A workable approach is to clearly label AI comments as such in the pull request, for example with a dedicated bot name and a note in the comment text stating that the statement is not based on domain expertise. In addition, the merge rule should still require at least one human approval, regardless of whether the AI step ran without any findings. That keeps the AI a filter that saves review time, without the actual decision-making authority disappearing from the process.

8. Using review prompts and configuration deliberately

A generic prompt like "Review this code" rarely produces useful results, because the model tends to make shallow stylistic remarks instead of specifically searching for the error classes that are actually relevant to the given project. A prompt that explicitly references documented project rules, for example forbidden patterns recorded in a CLAUDE.md file, and that explicitly excludes what the model cannot reliably assess, such as business logic correctness, works significantly better.

In local development environments, the same approach can be used as a pre-commit hook that blocks a commit when high-confidence findings occur, while logging low-confidence hints instead of interrupting the workflow. This gradation prevents developers from disabling the hook after a short time due to too many false positives, which in practice is the most common reason automated review gates fall out of use within a few weeks.

#!/usr/bin/env python3
"""Pre-commit hook: block the commit on high-severity AI review findings."""
import json
import subprocess
import sys


def get_staged_diff() -> str:
    """Return the staged diff as a string."""
    result = subprocess.run(
        ["git", "diff", "--cached"], capture_output=True, text=True, check=True
    )
    return result.stdout


def run_ai_review(diff: str) -> list:
    """Send the diff to Claude Code in headless mode and parse findings."""
    prompt = (
        "Review this diff for obvious bugs, missing null checks and "
        "forbidden patterns like assert() or @ error suppression. "
        "Return findings as a JSON array with severity: low, medium, high."
    )
    result = subprocess.run(
        ["claude", "-p", prompt, "--output-format", "json"],
        input=diff, capture_output=True, text=True, check=True,
    )
    return json.loads(result.stdout).get("findings", [])


def main() -> int:
    diff = get_staged_diff()
    if not diff.strip():
        return 0
    findings = run_ai_review(diff)
    high = [f for f in findings if f.get("severity") == "high"]
    for f in high:
        print(f"[HIGH] {f['file']}:{f['line']} {f['message']}", file=sys.stderr)
    return 1 if high else 0


if __name__ == "__main__":
    sys.exit(main())

9. AI review vs. human review in direct comparison

The following overview sorts typical review tasks by which combination of AI and human review yields the most reliable outcome. It shows that this is rarely an either-or choice, but rather a question of the right order and division of labor between both layers.

The trend in the table is consistent: the more mechanical and rule-based a check is, the more reliably a language model handles it. The more a decision depends on business context, team history, or long-term maintainability, the more clearly it remains a human task, where AI comments serve at most as an additional prompt for thought.

10. Summary

AI-assisted code review works best as a pre-check layer that catches mechanical and stylistic problems before a human reviewer sees the code. Claude Code reliably detects violations of documented coding standards, obvious logic errors, and many security patterns, because these categories can be derived from the code itself. As soon as correctness depends on business context, customer agreements, or long-term architectural decisions, the judgment remains a human task that no language model can reliably make from the diff alone.

For production use, the technical embedding matters most: restrictive permissions for the review bot, clear labeling of AI comments, confidence filtering before posting, and a merge rule that still requires at least one human approval. When this structure is followed, the time teams spend on obvious mistakes drops, without responsibility for business correctness quietly shifting to a tool that has no mandate to bear it.

11. FAQ: AI-Assisted Code Review as a Complement to the Team