best-practices: add expanded policy for AI interactions with PRs - #63
Open
paddybyers wants to merge 1 commit into
Open
paddybyers wants to merge 1 commit into
paddybyers wants to merge 1 commit into
Conversation
paddybyers
requested review from
AndyTWF,
SimonWoolf,
lmars and
mattheworiordan
September 26, 2026 07:35
AndyTWF
reviewed
Sep 28, 2026
| ## 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. |
There was a problem hiding this comment.
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"?
| 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. |
There was a problem hiding this comment.
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
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This expands the best practices documents to capture the conclusions of ERFC-001 as outlined in https://ably.atlassian.net/wiki/spaces/ENG/pages/5307367443/ERFC-001+Separating+humans+from+bots+in+our+pull+requests?focusedCommentId=5410914337.