best-practices: add guidance on AI-generated commits and AI-assisted PR workflows

best-practices/commits.md

@@ -145,6 +145,16 @@ In body:
 Fixes #123, #124
 ```
 
+## AI-generated commits
+
+AI-generated commits — whether created directly by a coding agent or by a developer using AI-assisted tooling — are acceptable, but must follow the same guidance as any other commit in this document. The standards for coherence, atomicity, and commit message quality apply equally regardless of how the code was produced.
+
+Repositories should contain appropriate configuration (for example, in `CLAUDE.md` or agent skills) to help ensure that coding agents comply with these standards. In practice, coding agents generally follow commit policy guidance well when it is provided.
+
+Be aware that coding agents can generate large volumes of changes quickly, which can easily result in oversized or unfocused commits. If a coding agent has produced a large body of work, it is still important to ensure that the work is committed in logical, independently-reviewable chunks rather than as a single monolithic commit. Use interactive rebase or other tools to reshape the history if needed before requesting review.
+
+Commits can have side-effects arising from their commit message, such as by using "fixes" or "closes" assertions. We avoid using these keywords in commit messages and prefer to have those assertions in PR descriptions instead. Be aware that coding agents may include these assertions, and erroneously cause issues to be closed. Therefore, when reviewing AI-generated commits, take care to ensure that the commit message is appropriate, not just the code changes.
+
 ### More information
 
 There is also good information in:

best-practices/pull-requests.md

@@ -106,6 +106,16 @@ For certain repos - especially where there is a very broad scope, and contributi
 
 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).
+
+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.
+
+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.
+
+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.
+
 ## Etiquette
 
 ### Reviewer Count