如何為 AI 智能體所寫的程式碼撰寫 PR 描述

Start with the problem and the decision, then describe the change, the risks and the test evidence. Give the reviewer a way to understand why the change should go in before they read the diff. The agent can draft it; the change owner checks that it describes what actually happened.

Write an explanation, not a file list

A list like "updated three files and added tests" helps orientation, but leaves the decision out of the picture. What was the broken behavior? Why does this solution fit? What changed for whoever uses the system?

A good PR description separates two things: the decision that can be discussed and the code that implements it. If the decision is still open, say so. A confident-sounding description does not turn an assumption into agreement.

A template to start from

The following is a suggested template, not a description of a real PR:

Problem: what can the user or the system not do today?

Decision: which solution was chosen, and why? What alternative was considered, and what was the trade-off?

Change: what is the new behavior, and which components are affected?

Boundaries: what stayed the same, and what is explicitly out of scope?

Evidence: which tests or scenarios were actually run, on which version, and what was the result?

Risks: what might break, how would we notice, and how can we roll back?

Open questions: which decisions or checks are still missing?

The template should fit the change. A small fix does not need a long document. A change to permissions, data or an external interface justifies more explanation even if the diff is short.

Ask the agent for evidence you can check

The agent can read the diff and the run output and propose a draft. Ask it to distinguish between "I ran this" and "recommend running this". Every line about a test should be backed by output or a result you can locate, not a list of checks it intended to perform.

An illustration: a change in invoice handling should say what happens to an invoice that was paid while the job was queued. Unit-test output helps, but on its own does not prove the payment-provider integration was checked. This is a suggested example, not a client case.

If the agent used test data or a service stub, say so. If an integration test was not run, leave the limitation visible instead of writing "everything works".

Keep responsibility with the change owner

Before opening the PR, read the description without the diff. Can you explain the decision in your own words? Is there a claim you did not verify? Is there a remaining risk that someone else needs to decide on?

The agent is a draft writer. Whoever brings the change to the team needs to own the explanation. If you cannot answer why a particular solution was chosen, go back to the decision conversation instead of adding more words to the description.

Make the template part of the repository

According to GitHub's documentation, a PR template in the repository is shown automatically in the PR body when you open one. You can keep it in .github/pull_request_template.md. To be available, the template needs to be merged into the default branch. Multiple templates are also supported, when different change types call for different questions.

The template reminds you what to explain. It does not prove the explanation is correct and does not replace testing or review. Every so often, check which fields repeat themselves without adding information and which important questions stay outside it.

Start with one decision you can critique

Success here means the reviewer can identify the problem, understand the choice and find test evidence, without guessing from file names. If the important question only comes up after reading hundreds of lines, move it up front - into the description, or into a discussion before implementation.

Sources: GitHub: creating a pull request template for your repository. Originally published in Hebrew on ofershap.github.io.