The AI Pull Request Manifest: The One Page That Makes Agent Code Reviewable

The question that kills an AI pull request is not "does this line compile?"

It is "why did it touch this file?"

You open a PR for a small bug fix. The description says the agent fixed a null check. The diff has the null check, a new dependency, two unrelated refactors, a rewritten test helper, an adjusted lint rule, and a config file nobody remembers approving. Everything may be technically defensible. Nobody has enough context left to tell whether it belongs.

That is what AI changed about code review. It did not make review impossible. It made scope cheap to lose.

Humans used to pay a little pain for every unrelated change. We had to type it, context-switch to it, and decide it was worth doing while we were already in the area. An agent has no such friction. Give it a loose task and it sees every nearby improvement as an invitation. The result is a diff that has a reason for every line and no coherent reason for the pull request.

The fix I keep coming back to is a small AI pull request manifest. It is a written contract created before implementation. The agent works against it. The reviewer checks the diff against it. If a file is outside the expected scope, it needs an explicit explanation or it comes out.

It is not glamorous. It works.

Why an AI Summary Is Not Enough

Most agent tools already generate a summary. That is useful, but it is backwards-looking. A model can explain any completed diff in fluent prose. A summary tells you the story after the agent has already made decisions. It does not tell you whether those decisions were allowed.

The manifest is forward-looking. It says what the task is, what success looks like, what the agent expects to touch, which checks will prove it, and where it must stop and ask.

That changes the review conversation from this:

I think this extra refactor was needed because the agent said it simplified the code.

To this:

This file was not in the expected scope. What broke without it, and should that be a separate change?

You are no longer reviewing a persuasive essay. You are checking whether the implementation kept a promise.

The Manifest Template

Keep it short enough that people use it. Mine has six fields.

## Agent change manifest

### Task
One sentence describing the user-visible outcome.

### Expected scope
- Files or directories expected to change
- Explicit non-goals

### Approach
The smallest intended change and any important constraint.

### Evidence
- Checks to run
- Manual behavior to verify

### Risks and rollback
What could break, and how to undo the change.

### Not verified
What the agent could not test or confirm.

That is the whole thing. No prompt transcript. No chain of thought. No 800-line work log. The useful artifact is the agreement, not a diary.

Here is a real-ish example for a bug where a user cannot save a profile with an empty optional bio:

### Task
Allow users to save a profile when bio is empty.

### Expected scope
- `app/profile/ProfileForm.tsx`
- `app/profile/profile.test.tsx`
- No schema, dependency, or API changes.

### Approach
Treat an empty bio as undefined before the existing validation call.

### Evidence
- Run the profile test file.
- Manually save a profile with a blank bio in localhost.

### Risks and rollback
Risk: whitespace-only input behavior changes. Roll back the normalization line.

### Not verified
Did not test the mobile layout.

Look at what this prevents. A package addition is immediately suspicious. A backend migration is immediately out of scope. A reviewer knows to check whitespace behavior and knows the browser case that matters. The PR could still be wrong, but it is no longer mysterious.

Write It Before the Agent Writes Code

This is the part teams skip when they are trying to move fast. They ask the agent to implement the whole thing, then demand the manifest afterward. That turns the document into a justification exercise.

Use a two-stage loop instead:

1. Ask the agent to inspect and propose the manifest only.
2. Read the scope and correct it if needed.
3. Ask it to implement exactly that plan.
4. Require an explicit note for every scope expansion.

For a tiny change, this takes a minute. For a larger change, it catches the moment where you thought you were requesting a button and the agent interpreted it as a feature redesign.

This is not waterfall with an AI sticker. The manifest should change when you discover new evidence. The difference is that a scope change becomes visible. Add a line saying why the new file is necessary, update the evidence, and continue. You have created a paper trail for a decision instead of a surprise in a diff.

The Three Review Passes

The manifest lets you make review faster because it gives each pass a different job.

1. Scope review

Start with the file list, not the code. Every changed file should appear in the expected scope or have an explanation. Every untouched expected file may mean the agent did not complete the stated approach.

This is the fastest high-signal check you can make. Large studies of failed agent-authored pull requests point to the same pattern: rejected changes tend to touch more files, fail more checks, and bundle unrelated modifications. Scope is a quality signal, not just an aesthetic preference.

If the diff contains a drive-by formatting pass, ask for it to be split. Agents can make a clean follow-up pull request in less time than it takes to find the one meaningful line hidden in a global rewrite.

2. Behavior review

Now review the path the user actually takes. The manifest tells you the expected outcome and the manual check. Read the diff through that lens.

For a payment change, this means the state transition, not whether the new function is elegant. For a UI change, use the local browser. For an API change, exercise the request and error response. For a background job, test the retry and idempotency path, not just the happy path.

AI code review is useful here as a second pair of eyes. Give the review agent the manifest, the diff, the relevant surrounding files, and the checks that ran. Do not let it post every speculative comment directly on the PR. A person should validate its findings before someone burns an hour fixing a hallucinated issue.

3. Evidence review

Finally, look at what proves the claim. Did the stated tests run? Did the agent report a build failure honestly? Is there an untested branch, a browser state, or an external dependency it could not reach?

The Not verified field is one of the most valuable parts of the template. Agents are good at completing the happy path and sounding finished. A named blind spot tells the reviewer where not to assume certainty.

The Policy I Would Put in a Repository Today

Here are the rules I would use for agent-authored work on a small team.

• One manifest per pull request.
• The task must describe an outcome, not a pile of implementation instructions.
• Every changed file must be in scope or explained in the manifest update.
• No dependency, CI, migration, or permission change without explicit reviewer approval.
• The author must state which checks ran and what did not run.
• An AI reviewer may flag issues, but a human validates them before requesting changes.
• A pull request that contains an unrelated refactor gets split, even if the refactor is good.

The fourth rule does most of the heavy lifting. A dependency change, a workflow change, a migration, and an access change all have an execution path outside the code you are currently reading. They deserve a reviewer who knows that category, not a brief appearance in a feature PR.

This policy pairs naturally with the least-privilege permissions model for coding agents. An agent that cannot install packages or modify CI without an approval is less likely to smuggle a whole second task into a bug fix. Permission boundaries and review boundaries reinforce each other.

What the Manifest Does Not Solve

It does not make generated code correct. It does not replace tests, staging, domain expertise, or a reviewer who understands the system. It does not prevent a rushed team from rubber-stamping a bad PR.

It gives the team a better chance to notice what it is approving.

That sounds modest. It is. The point is not to invent a grand new process for AI. The point is to preserve the most useful property of code review: a person can understand the change well enough to take responsibility for it.

AI code review became a bottleneck because code generation accelerated and the human side did not. The wrong response is to remove the human side. The right response is to put structure around the parts an agent makes cheap: scope expansion, fluent summaries, and apparently reasonable changes that nobody asked for.

One page is enough to start. Put it in the pull request template. Require it for agent-authored changes for two weeks. Then look at the PRs that were easier to review and the ones that still got through messy. The template will tell you where it needs to get sharper.

Frequently Asked

Should every AI-assisted pull request use a manifest?

Use it for any change where an agent modified code autonomously or touched more than a trivial file. A one-line spelling fix does not need ceremony. A feature, bug fix, or refactor does.

Can an AI write the manifest?

Yes, but create and approve it before implementation. The reviewer or task owner should correct the scope before the agent starts changing code.

Why not just ask the agent to keep pull requests small?

That instruction helps but is too vague. A manifest defines what small means for this task, identifies allowed files, and creates a visible place to record a necessary scope expansion.