Skip to content

Agents: add PR description guidance on rationale over restatement #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericholscher merged 6 commits into from
Jun 2, 2026
+5 −6
Merged

Agents: add PR description guidance on rationale over restatement #307

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e967825
Agents: add PR description guidance on rationale over restatement
claude Jun 2, 2026
570322c
Agents: fix typo and clarify PR description wording
claude Jun 2, 2026
b6d9520
Agents: avoid duplicate AI-generated footer in PRs
claude Jun 2, 2026
3fbedfb
Agents: fix Python version and dedupe pre-commit guidance
claude Jun 2, 2026
52439b8
Agents: make the why-over-what PR rule concrete and binding
claude Jun 2, 2026
a522ed9
Apply suggestion from @ericholscher
ericholscher Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.14
- Django web framework
- Docker and Docker Compose for development
- PostgreSQL database
Expand All @@ -26,11 +26,11 @@ 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
* 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 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:`.
Expand Down Expand Up @@ -96,7 +96,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
Copy link
Copy Markdown
Member Author

@ericholscher ericholscher Jun 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There were multiple mentions of pre-commit so removed this to make it explicit.


## Front-end

Expand Down