Skip to content

Agents: tighten the pull request description rules #339

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

Draft
ericholscher wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Agents: tighten the pull request description rules #339

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
530ad69
Agents: tighten the pull request description rules
claude Oct 26, 2026
2a10cb9
Agents: put the AI-generated note at the top of PR descriptions
claude Oct 26, 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
15 changes: 10 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,19 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall

## Pull Requests

- Make the PR description as useful as possible for humans; lead with the most important context.
- 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
- 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:`.
- Write the description for a reviewer with two minutes, as plain paragraphs in this order:
1. The problem: what was wrong or missing.
2. The approach, and anything the diff doesn't make obvious: a judgement call, a side fix made along the way, a behavior change.
3. What the reviewer or merger has to do, if anything: a redirect to add, a setting to change, a follow-up this unblocks.
- Keep it under about 120 words. One paragraph is fine.
- Describe only this PR: no roadmap, no "first of several", no links to other PRs unless the reviewer must read them first. Link issues it fixes or relates to.
- Don't restate _what_ changed — no "Changes" section, changelog, file lists, or per-change bullets — since the diff already shows that.
- Decide, don't ask: state the choice made and why in a clause, not as an open question to the reviewer.
- Don't include a test plan unless the change can't be verified from the diff.
- Open the description with a one-line note that it was generated by an AI agent, with the session link if there is one. Put it at the top, not in a footer, and never add it twice.

## Package Management

Expand Down
Loading