From c978160f8d8efa252dbfd81696bd11aec8e56852 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sun, 25 Oct 2026 17:01:34 -0700 Subject: [PATCH] agents: add PR comment etiquette and AI oversight disclosure rules Autonomous AI agents have posted noisy CI play-by-play comments, redundant commit narrations, and internal checklists on pull requests while omitting clear disclosure of human oversight. Update `AGENTS.md`, `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`, and `.agents/rules/pr.md` to require clean commit-ready PR descriptions, disclose human oversight level in a separate post-creation PR comment, and forbid CI status or diff-narration comment spam. Also add `CLAUDE.md` referencing `AGENTS.md`. --- .agents/rules/agent-config.md | 2 +- .agents/rules/pr.md | 10 ++++++++-- .github/PULL_REQUEST_TEMPLATE.md | 25 ++++++++++++++++++------- AGENTS.md | 20 +++++++++++++++++++- CLAUDE.md | 1 + CONTRIBUTING.md | 25 ++++++++++++++++++------- 6 files changed, 65 insertions(+), 18 deletions(-) create mode 100644 CLAUDE.md diff --git a/.agents/rules/agent-config.md b/.agents/rules/agent-config.md index f16932940e..3f15edfb44 100644 --- a/.agents/rules/agent-config.md +++ b/.agents/rules/agent-config.md @@ -1,7 +1,7 @@ --- trigger: glob description: Prose style rules for agent configs, rules, and skills -globs: ".agents/**/*.md,AGENTS.md,GEMINI.md" +globs: ".agents/**/*.md,AGENTS.md,CLAUDE.md,GEMINI.md" --- # Agent Configuration Style diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index fa578823c8..149e1c5bf3 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -37,8 +37,14 @@ Before drafting any pull request description, strictly adhere to the rules in * **PR Metadata Discrepancies**: If a PR title or description diverges from the branch's actual scope, notify the user of the discrepancy and ask for confirmation before updating GitHub. -* **NEVER** include a list of per-file edits or changelog bullet points of - individual file modifications in PR descriptions or commit messages. +* **NEVER** include a list of per-file edits, changelog bullet points of + individual file modifications, test execution logs/checklists, or AI + disclosure metadata in PR descriptions or commit messages. +* **AI Disclosure & Comment Etiquette**: Keep the PR description clean for use + as the merge commit message. Disclose human oversight level in a separate PR + comment after creation. Never post comments for every CI run or narrate build + IDs, commit SHAs, line counts, or trivial diff details (e.g., + "comment-only"); comment `PTAL` only when ready for re-review. * High-level overview only: state *why* the change is made and *how* at a conceptual level. Link related issues (e.g. `Work towards #`). * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear, diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c347266583..c478ff1e8b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,24 @@ PR Instructions/requirements * Title uses `type: description` format. See CONTRIBUTING.md for types. * Common types are: build, docs, feat, fix, refactor, revert, test - * Update `CHANGELOG.md` as applicable -* Breaking changes include "!" after the type and a "BREAKING CHANGES:" + * Add a news entry file in `news/` as applicable (do not edit `CHANGELOG.md` + directly) +* Breaking changes include "!" after the type and a "BREAKING CHANGE:" section at the bottom. See CONTRIBUTING.md for our breaking changes process. -* Body text describes: - * Why this change is being made, briefly. - * Before and after behavior, as applicable - * References issue number, as applicable -* Update docs and tests, as applicable +* Body text becomes the commit message upon merge and should be clean and + concise: + * Briefly describe *why* this change is being made. + * Briefly give a high-level overview of *how* the code is changed. + * Reference issue number, as applicable. + * Do not include per-file changelogs, test run logs/checklists, or AI + disclosure metadata in the PR description. +* Update docs and tests, and run `bazel test` and `buildifier` locally prior + to pushing. +* AI-assisted PRs: + * After creating the PR, post a separate comment disclosing the level of + human oversight (e.g., human-reviewed, semi-autonomous, or autonomous). + * Do not post comments for every CI run or narrate build IDs, commit SHAs, + or trivial diff details. Reply `PTAL` once CI is passing and ready for + review. * Delete these instructions prior to sending the PR diff --git a/AGENTS.md b/AGENTS.md index 58031f822f..a3e4fd2619 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,7 +47,25 @@ because it interferes with code review comments. ### PR descriptions Follow the advice in `CONTRIBUTING.md` for PR descriptions. PR descriptions -become the commit message upon merge. +become the commit message upon merge. Keep the PR description clean and +suitable for use as the commit message; do not put AI disclosures, test +execution logs, or check checklists in the PR description. + +### GitHub PR interaction and AI disclosure + +* **Run local checks before pushing:** Run `bazel test --config=fast-tests` + and `buildifier` locally before opening or updating a PR. +* **Post AI disclosure as a PR comment (not in the PR description):** When an + AI agent creates or interacts on a PR, post a single comment after the PR is + created disclosing the level of human oversight (e.g., `human-reviewed`, + `semi-autonomous`, or `autonomous`). +* **No CI status spam or commit narration:** Do not post comments for every CI + run, and do not narrate build IDs, commit SHAs, patch line/file counts, or + trivial diff details (e.g., stating a push is "comment-only"). GitHub + already displays commits and check statuses. +* **Comment only when actionable:** Only post a PR comment to answer a + reviewer's question, ask a clarifying question, or briefly indicate the PR + is ready for re-review (e.g., `PTAL`) once CI is passing. ### Python pytest conventions diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..285e0f5b36 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@./AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 505d994d15..feee2bad5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -375,16 +375,27 @@ had written it entirely themselves. This means: * **Understanding the code:** You must be able to explain what the code does and why it's implemented that way. This includes discussing its - implications, and any trade-offs made during its development, just as if you - had written it entirely yourself. + implications, and any trade-offs made during its development, just as if + you had written it entirely yourself. * **Vetting the correctness and functionality:** You are responsible for thoroughly testing and verifying that the code is correct, functional, and meets all project requirements and standards. - -If the human PR author cannot fulfill these responsibilities, the `rules_python` -maintainers will not spend time reviewing or merging the PR. The goal is to -ensure that all contributions, regardless of their origin, maintain the quality -and integrity of the project and do not place an undue burden on maintainers. +* **Disclosing human oversight in a PR comment:** Keep the PR description + clean for use as the merge commit message. After creating the PR, post a + comment disclosing the level of human oversight (e.g., closely + human-directed/reviewed, semi-autonomous, or fully autonomous). +* **Avoiding bot comment spam:** Do not post comments for every CI run or + commit push, and do not narrate build IDs, commit SHAs, line counts, or + trivial diff details (such as noting a push is "comment-only"). Only post + a comment to ask or answer a substantive question, or reply `PTAL` + ("Please take another look") once CI is passing and the code is ready for + review again. + +If the human PR author cannot fulfill these responsibilities, the +`rules_python` maintainers will not spend time reviewing or merging the PR. The +goal is to ensure that all contributions, regardless of their origin, maintain +the quality and integrity of the project and do not place an undue burden on +maintainers. ## FAQ