From e967825a69e32aeb56184b8bccd5c6e7faf8aeb7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:31:40 +0000 Subject: [PATCH 1/6] Agents: add PR description guidance on rationale over restatement --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 99012e0..be8e559 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,7 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall * Put a footer note that this was generated by the AI agent in use * Use feature branches for all changes * Don't include a "Changes" section, since the PR content is self-explanatory +* Write PR descriptions about the decisions and rationale (the "why"), not a restatement of what changed. Omit anything already obvious from the diff, such as field names, file lists, or an enumerated list of tests. * Don't include Test Plan unless absolutely necessary. * Link related issues in the PR description, if there are any in the chat context * Prefix pull request titles, example `Api:`, `Builds:`, or `Docs:`. From 570322cb3688b4107c34ba40fdaa7b175c53fb47 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:32:20 +0000 Subject: [PATCH 2/6] Agents: fix typo and clarify PR description wording --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index be8e559..1f698c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # AI Instructions for Read the Docs This file lives in the `common` repo, -and is copied to each produciton repo. +and is copied to each production repo. Agents don't work with symlinks or submodules, so this is best for now. @@ -26,7 +26,7 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall ## Pull Requests -* Make the PR description maximum useful for humans, context first and most important. +* Make the PR description as useful as possible for humans; lead with the most important context. * Always open pull requests as drafts * Put a footer note that this was generated by the AI agent in use * Use feature branches for all changes From b6d9520e06e09d2e7d3b6c4f566427686f1c6747 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:33:41 +0000 Subject: [PATCH 3/6] Agents: avoid duplicate AI-generated footer in PRs --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1f698c6..7bb9629 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall * Make the PR description as useful as possible for humans; lead with the most important context. * Always open pull requests as drafts -* Put a footer note that this was generated by the AI agent in use +* Note in a footer that the PR was generated by an AI agent, but only if no such footer is already appended automatically — never add a second one * Use feature branches for all changes * Don't include a "Changes" section, since the PR content is self-explanatory * Write PR descriptions about the decisions and rationale (the "why"), not a restatement of what changed. Omit anything already obvious from the diff, such as field names, file lists, or an enumerated list of tests. From 3fbedfbe67bc22817b8849824c1239c5b96ef097 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:38:57 +0000 Subject: [PATCH 4/6] Agents: fix Python version and dedupe pre-commit guidance --- AGENTS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7bb9629..c7a61d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Read the Docs is a documentation hosting platform that builds and hosts document It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automatically builds documentation from Git repositories. **Technology Stack:** -- Python 3.x +- Python 3.12 - Django web framework - Docker and Docker Compose for development - PostgreSQL database @@ -97,7 +97,6 @@ before they cause `IntegrityError` failures at deploy time. - Use Django conventions and best practices - Use type hints for function signatures - Write clear, concise docstrings for public functions and classes -- Run linters and formatters using `tox -e pre-commit` before committing code ## Front-end From 52439b86dcb25dac819b46dc822c3234177bd926 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:49:19 +0000 Subject: [PATCH 5/6] Agents: make the why-over-what PR rule concrete and binding --- AGENTS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c7a61d8..3517295 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,8 +30,7 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall * Always open pull requests as drafts * Note in a footer that the PR was generated by an AI agent, but only if no such footer is already appended automatically — never add a second one * Use feature branches for all changes -* Don't include a "Changes" section, since the PR content is self-explanatory -* Write PR descriptions about the decisions and rationale (the "why"), not a restatement of what changed. Omit anything already obvious from the diff, such as field names, file lists, or an enumerated list of tests. +* Write the description about *why*: the problem it solves, the approach taken, and anything a reviewer should double-check. Don't restate *what* changed — no "Changes" section, changelog, file lists, or per-change bullets — since the diff already shows that. Prefer "Sharpens the PR rules, which kept producing diff-restating descriptions" over "Reworded one bullet, fixed a typo, removed two sections." * Don't include Test Plan unless absolutely necessary. * Link related issues in the PR description, if there are any in the chat context * Prefix pull request titles, example `Api:`, `Builds:`, or `Docs:`. From a522ed932387d2e7a961135de4ba8a1e1b414b1c Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Tue, 2 Jun 2026 08:08:13 -0700 Subject: [PATCH 6/6] Apply suggestion from @ericholscher --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3517295..d5393f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Read the Docs is a documentation hosting platform that builds and hosts document It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automatically builds documentation from Git repositories. **Technology Stack:** -- Python 3.12 +- Python 3.14 - Django web framework - Docker and Docker Compose for development - PostgreSQL database