---
title: "How to write custom AI code review rules for a repository | Proofline"
description: "A reviewer sees a migration that drops a column. What should it look for before it comments? Give it a rule that names the failure, the files where it can happen, and the evidence that would justify a finding."
url: https://proofline.sh/learn/write-custom-ai-code-review-rules/
---

[Learning center](/learn/)

# How to write custom AI code review rules for a repository

A reviewer sees a migration that drops a column. What should it look for before it comments? Give it a rule that names the failure, the files where it can happen, and the evidence that would justify a finding.

Code review The Proofline team November 18, 2026 3 min read

## Write the instruction before choosing the file pattern

Consider a service that deploys database migrations before replacing its workers. A pull request removes `orders.status` and updates the new worker to read `orders.state`. The new code and schema agree, yet a worker from the previous release still needs the column the migration removes.

“Check migrations for breaking changes” leaves the reviewer to guess what counts as a break. Give the reviewer a question it can answer from the change.

> For a column rename or drop, find readers and writers that can still run when the migration takes effect, including the rollback version. Cite the SQL and the affected query. If deployment order is unknown, identify what would establish it.

The instruction works in a repository review guide or in a tool that accepts custom rules. The SQL and query establish a code dependency. To say it affects a running worker, a reviewer also needs its deployed version and the order of the rollout. The [PostgreSQL rollback exercise](/learn/postgres-migration-rollback/) demonstrates that distinction with two versions of one query.

## Scope one rule to migration files

Suppose migrations live under `db/migrations/`. In a reviewer that supports path-scoped rules, attach the instruction to SQL files there. Leave the rest of the pull request available to the reviewer so it can follow a reference from the migration into application code.

Here is a complete `.proofline.yaml` example. The leading slash anchors the pattern at the repository root. The double asterisk includes subdirectories.

```
version: 2
rules:
  - key: migration-rollback
    path_globs:
      - "/db/migrations/**/*.sql"
    text: >-
      For a column rename or drop, find readers and writers that can
      still run when the migration takes effect, including the rollback
      version. Cite the SQL and the affected query. If deployment order
      is unknown, identify what would establish it.
```

Try it on two pull requests targeting the same branch.

| Pull request | Expected result |
| --- | --- |
| Drop `orders.status` in `db/migrations/042_orders.sql` and change a worker query | The SQL path activates the rule. Inspect whether the reviewer identifies the old worker query and checks when it can run. |
| Change only `docs/orders.md` to document the new field | The migration rule has no matching path. Other applicable review rules can still run. |

An additive migration also matches the path pattern. A match tells the reviewer to consider the instruction. It still needs a relevant rename or drop and supporting evidence to report this particular problem.

## Decide what “only on experimental branches” means

A pull request from `experiment/new-storage` into `main` has **main** as its base. A second pull request from `fix/worker` into `experiment/new-storage` has **experiment/new-storage** as its base. A filter for experimental _base_ branches selects the second request. A team that organizes experiments by source-branch name is asking for a different filter.

In Proofline, `reviews.base_branches` restricts which pull requests the repository reviews. It affects the whole review. A rule's `path_globs` determines where that one instruction applies. Keep the review-wide branch filter unset if ordinary reviews should continue on `main`. For an experiment kept under a dedicated directory, a rule on that directory can apply alongside the team's normal checks. [Review scope and branch filters](/help/repository-configuration/)

Validate the draft configuration, merge it, and try the two pull requests above. Proofline reads the file at the merge base, so the pull request introducing a rule still uses the earlier configuration. [Manage custom review rules](/help/review-rules/)

## One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. [Eligibility and fair-use terms](/free-code-review/).

[Start free with GitHub](https://proofline.sh/orgs/plan?offer=free_month)

## Related reading

-   ### [Customizable AI code review rules](/blog/customizable-ai-code-review/)
    
    Company The Proofline team October 7, 2026 3 min read
    
-   ### [How to test a PostgreSQL migration before rolling back the app](/learn/postgres-migration-rollback/)
    
    Breaking migrations The Proofline team November 18, 2026 3 min read
