docs: add PR sizing and description guidelines to AGENTS.md by ajpallares · Pull Request #6915 · RevenueCat/purchases-ios

ajpallares · 2026-06-05T07:59:46Z

Checklist

If applicable, unit tests
If applicable, create follow-up issues for purchases-android and hybrids

Motivation

Give AI coding agents concrete, less subjective guidance so PRs stay small and easy to review.

Description

Adds a dedicated Pull Requests section to AGENTS.md (with Labels as a subsection) covering:

Smaller, self-contained, stacked PRs, with a soft ~500-line target on hand-written source and up-front planning of the PR breakdown for larger tasks.
Concise descriptions: short motivation, no diff restatement, no commits section, and testing notes only for what the diff doesn't show.

The PR template now points AI agents to that section, keeping the existing detailed hints for human contributors.

Note

Low Risk
Documentation-only changes with no runtime or SDK behavior impact.

Overview
Documents how to open PRs for AI agents and contributors by expanding AGENTS.md with a Pull Requests section (size/stacking, concise descriptions, label rules) and retitling the former labels block as a subsection.

The PR template now tells AI agents to follow that section in addition to filling out the template.

^{Reviewed by Cursor Bugbot for commit 8098b3f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Add Guardrails guidance for AI agents to prefer smaller, self-contained stacked PRs (soft ~500-line target on hand-written source) and to keep PR descriptions concise. Co-authored-by: Cursor <cursoragent@cursor.com>

AlvaroBrey

🙌 Looks great, just one minor suggestion:

Should we tell the agent to respect the MR template, as well? Not sure if it's doing that already or if we enforce it somehow

tonidero

Looking nice!

tonidero · 2026-06-05T08:28:33Z

+  - **Don't restate the diff** — no file-by-file or change-by-change enumeration. If a bullet just describes a code change visible in the diff, cut it.
+  - **No "Commits" section** — the commit list is already on the PR.


I wonder if this is already part of "be concise". Just slightly concerned about increasing the size of this file too much since that's basically tokens that need to go on every loop.

Very good point. I also wondered about this. The problem with "be concise" is subjectivity IMO. And these instructions do add some concrete restrictions to the AI. But it's true that adds more and more info the context. Will simplify :)

tonidero · 2026-06-05T08:30:06Z

 - **Check Android SDK** when unsure about cross-platform implementation details — new features should follow existing patterns across SDKs
 - **Never commit Claude-related files** — do not stage or commit `.claude/` directory, `settings.local.json`, or any AI tool configuration files
 - **Never commit API keys or secrets** — do not stage or commit API keys, tokens, credentials, or any sensitive data
+- **Prefer smaller, self-contained stacked PRs** when possible. "Self-contained" means the PR compiles, passes tests, and is reviewable on its own. As a rule of thumb, aim to keep the diff under ~500 lines of hand-written source — excluding generated, serialized, or non-reviewed files (e.g. JSON, snapshots, lockfiles, `api/*.swiftinterface`). When changes depend on each other, stack them instead of bundling everything into one large PR.


Could be good to ask it to start bigger tasks by planning how the could could be split into different PRs... I think that might help it organize itself? Just an idea but FFTI!

tonidero · 2026-06-05T08:32:51Z

Should we tell the agent to respect the MR template, as well? Not sure if it's doing that already or if we enforce it somehow

I don't think it is... And might be something we could do indeed.

facumenzella · 2026-06-05T09:17:08Z

PULL_REQUEST_TEMPLATE.md says:

<!-- Describe your changes in detail -->
<!-- Please describe in detail how you tested your changes -->

And we've added:

Don't restate the diff — no file-by-file or change-by-change enumeration.
Testing: only mention what the diff doesn't show ... Don't enumerate added test cases — the test files are in the diff.

What if we just point Agents.md to the template? Or the opposite

facumenzella

Awesome! Just a nit for a contradiction, but we can refine this later

ajpallares · 2026-06-05T12:06:38Z

Great catch @facumenzella! I see the contradiction, but I think the hints in PULL_REQUEST_TEMPLATE.md are meant for humans (who often tend to under-explain) while what this PR adds to AGENTS.md is meant for AI (which tend to over-explain). Honestly, the message in PULL_REQUEST_TEMPLATE.md could explain why we get such big PR descriptions by AI agents... 🤔

Maybe we can point AI agents to AGENTS.md in PULL_REQUEST_TEMPLATE.md while keeping the existing messages for humans?

facumenzella · 2026-06-05T12:08:58Z

sounds good @ajpallares !

Move PR sizing/description guidance into a dedicated "Pull Requests" section (with Labels as a subsection), point the PR template at it for AI agents, and trim the description sub-bullets. Co-authored-by: Cursor <cursoragent@cursor.com>

…/RevenueCat/purchases-ios into pallares/agents-md-pr-guidelines

Co-authored-by: Cursor <cursoragent@cursor.com>

…/RevenueCat/purchases-ios into pallares/agents-md-pr-guidelines

Co-authored-by: Cursor <cursoragent@cursor.com>

ajpallares · 2026-06-05T15:22:47Z

@tonidero @AlvaroBrey @facumenzella Sorry to ask for your reviews again, but I've changed it a bit trying to address all the feedback 🙏

AlvaroBrey

Looks nice! Hope it helps

facumenzella · 2026-06-05T15:25:42Z

@@ -1,4 +1,5 @@
 <!-- Thank you for contributing to Purchases! Before pressing the "Create Pull Request" button, please provide the following: -->
+<!-- AI agents: fill in this template, and also follow the "Pull Requests" section in AGENTS.md. -->


🍬 awesome

docs: add PR sizing and description guidelines to AGENTS.md

83a5f9e

Add Guardrails guidance for AI agents to prefer smaller, self-contained stacked PRs (soft ~500-line target on hand-written source) and to keep PR descriptions concise. Co-authored-by: Cursor <cursoragent@cursor.com>

ajpallares added the pr:other label Jun 5, 2026

ajpallares marked this pull request as ready for review June 5, 2026 08:11

ajpallares requested a review from a team as a code owner June 5, 2026 08:11

AlvaroBrey approved these changes Jun 5, 2026

View reviewed changes

tonidero approved these changes Jun 5, 2026

View reviewed changes

facumenzella approved these changes Jun 5, 2026

View reviewed changes

Merge branch 'main' into pallares/agents-md-pr-guidelines

2f0ee50

ajpallares and others added 3 commits June 5, 2026 17:12

Merge branch 'pallares/agents-md-pr-guidelines' of https://github.com…

9712230

…/RevenueCat/purchases-ios into pallares/agents-md-pr-guidelines

docs: tell AI agents to fill the PR template and follow AGENTS.md

2585df2

Co-authored-by: Cursor <cursoragent@cursor.com>

ajpallares requested review from AlvaroBrey, facumenzella and tonidero June 5, 2026 15:18

ajpallares and others added 4 commits June 5, 2026 17:18

Merge branch 'main' into pallares/agents-md-pr-guidelines

bb6b93a

docs: tell agents to use the PR template in AGENTS.md

0d42ed2

Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'pallares/agents-md-pr-guidelines' of https://github.com…

50ca5e6

…/RevenueCat/purchases-ios into pallares/agents-md-pr-guidelines

docs: shorten PR template bullet in AGENTS.md

8098b3f

Co-authored-by: Cursor <cursoragent@cursor.com>

AlvaroBrey approved these changes Jun 5, 2026

View reviewed changes

facumenzella reviewed Jun 5, 2026

View reviewed changes

facumenzella approved these changes Jun 5, 2026

View reviewed changes

ajpallares merged commit 9a34dec into main Jun 5, 2026
18 of 20 checks passed

ajpallares deleted the pallares/agents-md-pr-guidelines branch June 5, 2026 16:28

RCGitBot mentioned this pull request Jun 8, 2026

[AUTOMATIC] Release/5.78.0 #6954

Merged

ajpallares mentioned this pull request Jun 18, 2026

Add Danger check to discourage large PRs #7041

Merged

		- Don't restate the diff — no file-by-file or change-by-change enumeration. If a bullet just describes a code change visible in the diff, cut it.
		- No "Commits" section — the commit list is already on the PR.

		@@ -1,4 +1,5 @@
		<!-- Thank you for contributing to Purchases! Before pressing the "Create Pull Request" button, please provide the following: -->
		<!-- AI agents: fill in this template, and also follow the "Pull Requests" section in AGENTS.md. -->

Uh oh!

Conversation

ajpallares commented Jun 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Motivation

Description

Uh oh!

AlvaroBrey left a comment

Choose a reason for hiding this comment

Uh oh!

tonidero left a comment

Choose a reason for hiding this comment

Uh oh!

tonidero Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

ajpallares Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero commented Jun 5, 2026

Uh oh!

facumenzella commented Jun 5, 2026

Uh oh!

facumenzella left a comment

Choose a reason for hiding this comment

Uh oh!

ajpallares commented Jun 5, 2026

Uh oh!

facumenzella commented Jun 5, 2026

Uh oh!

ajpallares commented Jun 5, 2026

Uh oh!

AlvaroBrey left a comment

Choose a reason for hiding this comment

Uh oh!

facumenzella Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ajpallares commented Jun 5, 2026 •

edited by cursor Bot

Loading