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 96306c927b222f45ea9f28f16b266aabe9c30321 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:39:20 +0000 Subject: [PATCH 5/6] Agents: trim boilerplate that agents already follow --- AGENTS.md | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c7a61d8..82a5d8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,12 +56,8 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall ## Testing -- Use `pytest` as the testing framework -- Use the `assert foo == bar` style for assertions -- Write succinct, focused tests that test one thing at a time -- Use descriptive test names that explain what is being tested -- Place tests in appropriate test files following the project structure -- Always keep the test db with ``pytest --reuse-db`` to speed up test runs +- Use `pytest` with the `assert foo == bar` assertion style +- Keep the test DB warm with `pytest --reuse-db` to speed up runs ### Running tests locally @@ -91,19 +87,6 @@ Always run `tox -e migrations` after adding or modifying migration files. This r `manage.py makemigrations --check --dry-run` and catches missing or inconsistent migrations before they cause `IntegrityError` failures at deploy time. -## Code Quality - -- Follow PEP 8 style guidelines -- Use Django conventions and best practices -- Use type hints for function signatures -- Write clear, concise docstrings for public functions and classes - ## Front-end - Most templates/css/js are in a separate repository (https://github.com/readthedocs/ext-theme/). - -## Security - -- Follow Django security best practices -- Be aware of OWASP top 10 vulnerabilities -- Use Django's built-in security features (CSRF, XSS protection, etc.) From 29afb19d03b5f1e146125d84e6d5f9370b8f5bd0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 05:52:45 +0000 Subject: [PATCH 6/6] Agents: require keeping the PR description in sync with the branch --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 82a5d8e..46b9aff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,7 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall * 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. +* Keep the description in sync with the branch. When later commits add, drop, or rework what the PR does, update the description before review or merge — a stale description that describes a different change is worse than none. * 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:`.