Skip to content

best-practices: add expanded policy for AI interactions with PRs #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paddybyers wants to merge 1 commit into
base: main
Choose a base branch
from
Open

best-practices: add expanded policy for AI interactions with PRs #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions best-practices/pull-requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ The policy here is the set of rules we use with that aim. Although there is a lo

- the approval of a maintainer via a PR approval is a necessary condition for new code to be merged;
- PR reviews should be conducted in a timely way so as not to impede the authors' work;
- PR feedback must be courteous, objective and clear, and should include guidance, suggestions and other constructive feeback where this helps to move everyone's work forward.
- PR feedback must be courteous, objective and clear, and should include guidance, suggestions and other constructive feeback where this helps to move everyone's work forward;
- AI authorship of, and interaction with, PRs does not dilute the human author's responsibility for a PR and adherence to these principles. AI interactions with a PR must not impede a human's ability to do this.

## Applicability

Expand Down Expand Up @@ -108,14 +109,38 @@ After a PR is merged, the branch should be deleted.

## Use of coding agents and AI review bots

Code generated by coding agents is now the default way that much of our code is produced. Coding agents can raise PRs, so long as they follow the guidance in this document and in [commits.md](commits.md).
Code generated by coding agents is now the default way that much of our code is produced. Coding agents can raise PRs, so long as they follow the guidance in this document and in [commits.md](commits.md). The core principles that must be maintained when introducing AI-based workflows are as follows.

@AndyTWF AndyTWF Sep 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we could consider including a statement in this section akin to "humans still have to review PRs more often than not, and therefore need to understand the intent behind it; repos should contain templates for what to put in a PR description and agents should be encouraged to write in terse, straight-to-the-point language to avoid a wall of text"?


Raising a PR in non-draft state is an indication by the author that it is ready for independent review; this is just as true for AI-generated PRs as for any other. Therefore, if the author wishes to trigger an AI-assisted PR review as part of their own pre-submission process, this should be done with the PR in draft state. Once the author is satisfied that the PR is ready for independent review - which requires any prior review feedback to be resolved - it should be updated to a full (non-draft) PR.
- PRs continue to be owned by humans, and a human owns what their agents say on it. Human authors are responsible for appropriateness and validity of PRs, and compliance of their agents with this policy.

- Codeowners own the workflow. Whether and how a repo uses auto-approval, bot-assisted review, draft-first workflows, or other automation is a decision for that repo's maintainers, provided the automation meets the principles here. Different repos have different needs and are not required to converge on identical tooling.

PRs are a vehicle for humans to understand, discuss and approve changes. This means that:

By default, AI review comments and the resulting discussion and resolution should remain in the PR for future reference, unless the author believes that they constitute extraneous noise. In that case, consider re-raising a clean PR without the noise. It is the author's responsibility to ensure that the PR is in a fit state to review, and that extends to the PR discussion as well as to the code and history.
- PR conversations are for humans. A comment on a PR should mean a person said something to you. The conversation thread should consist of human contributions, plus only those bot contributions that specifically require human attention and action.

@AndyTWF AndyTWF Sep 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps my comment above may better live here... but definitely something about how PR descriptions are the key vehicle behind a quick understanding of intent, so need to be to the point, not full of waffle/claudisms etc


- You can always tell a human from an agent. Automated accounts post as themselves, not as a human. Where an agent posts on a PR at a human's explicit direction (eg "reply to this comment"), the post must carry a clear indication that it was agent-authored (eg a footer), since the wording may not be exactly what the human would have written themselves.

Raising a PR in non-draft state is an indication by the author that it is ready for independent review; this is just as true for AI-generated PRs as for any other. Therefore, if the author wishes to trigger an AI-assisted PR review as part of their own pre-submission process, this should be done with the PR in draft state. Once the author is satisfied that the PR is ready for independent review - which requires any prior review feedback to be resolved - it should be updated to a full (non-draft) PR.

For the avoidance of doubt: as PR author you are expected to present a PR that is fit for peer, human review. A repo may have AI triage and/or review configured to take place post-submission that preempt independent human review, but the principle remains that it must be ready for human review. If an author presents a PR that looks like it was written by a coding agent and they have not reviewed it themselves, then the reviewer is expected to reject the PR. It is not acceptable to expect other humans to review code you are presenting that you have not reviewed yourself.

## Use of PR features

AI interactions should be directed to the appropriate surface or feature in Github. This avoids polluting the comment thread, so it doesn't compete for attention with human discussion, but also means that the AI input is more structured and more explicitly linked to its purpose and the context that was used to generate it.

| AI output | Appropriate surface |
|---|---|
| Preview / deploy URLs | A deployment with `environment_url` (shows as a "View deployment" button and on the deployments page) |
| Reports (coverage, size, scans) | Check run output / job summary |
| Per-line findings | Check annotations (inline in Files changed) |
| Pass/fail gates | Status checks (merge box) |
| PR status or metadata (stale, size, etc.) | Labels |

Within the conversation thread itself a bot should only post a conversation comment to ask a human to do something, and should say so plainly (eg an indication that a human review is required after triage). It should not post comments that just narrate or confirm what already happened (verdicts, "review complete" comments, walkthroughs duplicating a check or deployment). Any bot comments should always be kept to the point.

By default, AI outputs, review feedback and the resulting discussion and resolution should remain in the PR for future reference, unless the author believes that they constitute extraneous noise. In that case, consider re-raising a clean PR without the noise. It is the author's responsibility to ensure that the PR is in a fit state for humans to review, and that extends to the PR discussion as well as to the code and history.

## Etiquette

### Reviewer Count
Expand Down
Loading