How to Set a Pull Request Size Budget for AI Agents

Quick answer
Set the budget before the task starts: a maximum number of files, changed lines, and concerns per pull request.
Put the numbers in AGENTS.md so every session sees them, and in CI so exceeding them fails the check.
A practical starting point is one concern, under ten files, and a few hundred changed lines; adjust from measured review latency.
When a change exceeds the budget, split it by concern rather than by file, so each part stands alone.
Exclude generated files and lockfiles from the line count, or the budget punishes dependency updates.

How do you set a budget that people actually follow?

Start from what a reviewer can read properly in one sitting, then subtract for the mechanical noise. Write the limit where the agent reads it, and make CI enforce the same number. A rule that exists only in a style guide is a suggestion.

Include an escape hatch for legitimate large changes, such as a lockfile regeneration or a framework upgrade, and require a label so reviewers know why the limit was waived.

# .github/workflows/pr-size.yml
name: pr-size
on: [pull_request]
jobs:
  budget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check changed lines
        run: |
          changed=$(git diff --numstat origin/${{ github.base_ref }}...HEAD \
            | grep -vE 'package-lock.json|pnpm-lock.yaml|*.min.js' \
            | awk '{a+=$1; d+=$2} END {print a+d}')
          echo "changed lines: $changed"
          test "$changed" -le 600

What should the budget actually constrain?

Three things: concerns, files, and lines. Concerns matter most, because a single-concern change with many files is reviewable while a three-concern change with ten files is not. Files matter because each one requires context. Lines matter least, but they are the easiest to measure.

The budget should also name the files that never count as small: migrations, infrastructure, authentication, and anything in a production path. Those get their own review regardless of size.

How do you split a change that exceeded the budget?

Split by behaviour, not by directory. The first pull request should be one that a reviewer can approve on its own terms: a refactor with no behaviour change, then the new path, then the cleanup. Each part should leave the tests green.

If the parts cannot stand alone, the change was one conceptual unit all along and the budget is telling you something else: that the unit is too large to review safely, and needs a design conversation before more code.

How do you know the budget is right?

Track review latency and the number of review rounds per change. If changes under the limit still need several rounds, the problem is specification, not size. If review latency stays high while changes are small, the queue is capacity, not diff size.

Adjust the numbers from that evidence rather than from a principle. A team of one can tolerate a larger budget than a team of six, because the reviewer’s context is the same person who wrote the spec.

Where this bites vibecoders
An agent asked for “a small change” will happily produce 900 lines because it interprets the task broadly and cleans up along the way. Give it a number and a file list, and tell it to stop and report rather than exceed them.

Where AI coding assistants get this wrong

Setting a line limit that ignores lockfiles and generated files.
Splitting by directory, which produces parts that do not stand alone.
Waiving the limit without a label or a reason.
Enforcing the budget only in review, after the work is done.
Assuming a small diff is a safe diff; migrations are small and risky.
Changing the budget without measuring review latency.

Checklist

Write the budget in AGENTS.md.
Enforce the same number in CI.
Exclude generated files and lockfiles.
Name the file types that always need review.
Require a label for waivers.
Revisit the numbers from review-latency data.

FAQ

What is a reasonable starting budget?

One concern, under ten files, and a few hundred changed lines excluding generated content. It is a starting point, not a standard: a solo developer can go larger, and a regulated codebase should go smaller. Measure review latency and adjust.

Does a size limit stop the agent from finishing a task?

It should stop it from finishing the task in one change. Tell the agent to implement part one, stop, and report. The alternative is a branch that nobody can review, which delays the task more than splitting it.

How do I handle a legitimate large refactor?

Land it separately with no behaviour change, and prove that with tests before and after. Mechanical refactors are the one case where a large diff is acceptable, because the review question is narrow: does behaviour stay the same?

Should the limit apply to human changes too?

Usually yes, because the review constraint is about the reader, not the author. Exempting humans creates two standards and teaches the team that the limit is optional. Apply it to everyone and waive with a label.