Document small-PR AI review workflow in AGENTS.md

[justin808]

Summary

• add a small-PR review workflow section to AGENTS.md
• document batching, blocking-vs-optional triage, bot deduplication, and end-of-cycle master sync
• clarify how agents should handle review comments to avoid unnecessary review churn

Test Plan

• docs only; no code or test changes

---

Note

Low Risk
Docs-only change with no runtime, build, or test impact.

Overview
Adds a new Review Workflow section to AGENTS.md documenting how to handle small, focused PRs, including limiting inline AI reviewers, batching fixes after a full review pass, and triaging comments as blocking vs optional vs noise.

Also codifies guidance to verify AI claims locally, deduplicate bot comments, and delay syncing with master (with a note on CHANGELOG.md conflict resolution) until late in the review cycle.

^{Written by Cursor Bugbot for commit 1db35f4. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added Review Workflow guidelines covering reviewer usage, review pacing, fix batching, and issue classification standards.

[coderabbitai]

Walkthrough

Documentation updated to include a new "Review Workflow" section in AGENTS.md, detailing guidelines for AI reviewer usage, review pacing, batching strategies, issue classification, and comment handling procedures.

Changes

Cohort / File(s)	Summary
Documentation Updates AGENTS.md	Added new "Review Workflow" section outlining AI reviewer guidelines, including review pacing, batching fixes, blocking vs. non-blocking issue classification, and comment handling best practices.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 New workflows bloom like morning clover,
Guidelines sprouted, review rules in order,
AI reviewers hop with measured pace,
Through batched fixes and blocked issues' space,
Documentation dances—a reviewer's grace! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding documentation about a small-PR AI review workflow to the AGENTS.md file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jg-codex/agents-review-workflow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Review: Docs-only, low-risk

This is a clean, well-structured addition to AGENTS.md. The guidance around batching fixes, triaging blocking vs. optional comments, and deferring the master sync is practical and directly useful for agentic workflows.

One minor consistency issue: line 149 uses master in isolation, while line 175 (the existing Boundaries section) writes main` or `master. Since the repo's canonical default branch is main (confirmed by the PR metadata), the new bullet should either say main or main`/`master to match the convention already established elsewhere in this file.

Everything else looks good — no code, test, or build impact.

[claude]

Minor inconsistency: the rest of this file (line 175) uses `main` or `master`, but here only `master` appears. Since the repo's default branch is main, consider:

Suggested change

	- Rebase or merge `master` once, near the end of the review cycle. For `CHANGELOG.md` conflicts, prefer resolving them as the final step before merge.
	- Rebase or merge `main` once, near the end of the review cycle. For `CHANGELOG.md` conflicts, prefer resolving them as the final step before merge.

[greptile-apps]

Greptile Summary

This documentation-only PR inserts a new Review Workflow section into AGENTS.md, documenting best practices for managing AI-assisted code review on small, focused PRs. The guidance covers limiting inline-comment AI reviewers to one, batching follow-up commits, distinguishing blocking from optional feedback, verifying AI claims locally, deduplicating bot noise, and syncing master once near the end of the review cycle.

Key observations:

• The section is explicitly scoped to "small, focused PRs (roughly 5 files changed or fewer)", leaving no guidance for larger PRs even though most of the rules apply equally to any PR size.
• The blocking / optional / noise classification taxonomy introduced in the last bullet is not defined anywhere in the document, which could lead to inconsistent agent behaviour.
• The placement (after "Git Workflow", before "Boundaries") is logical and consistent with the document's existing structure.
• All other content is accurate and internally consistent with the rest of AGENTS.md.

Confidence Score: 4/5

• Docs-only change; safe to merge with minor wording improvements suggested.
• No code is changed and the new content is accurate and well-structured. The two style suggestions (scope wording and undefined taxonomy) are non-blocking improvements that could be addressed in a follow-up.
• No files require special attention beyond the two inline suggestions on AGENTS.md.

Important Files Changed

Filename	Overview
AGENTS.md	Adds a "Review Workflow" section with 8 bullet points covering AI reviewer limits, batch-commit strategy, blocking/optional triage, and CHANGELOG conflict handling; minor concerns around the small-PR scope caveat leaving a gap for larger PRs and the undefined blocking/optional/noise classification labels.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[PR opened] --> B{Small PR?\n≤5 files, one purpose}
    B -- Yes --> C[Single AI reviewer\nleaves inline comments]
    B -- No --> C2[No specific guidance\nin current doc]
    C --> D[Wait for full\nreview pass]
    D --> E[Classify comments:\nblocking / optional / noise]
    E --> F[Apply blocking fixes\n+ selected optional items]
    F --> G[Batch into one\nfollow-up push]
    G --> H{CHANGELOG.md\nconflict?}
    H -- Yes --> I[Resolve as final\nstep before merge]
    H -- No --> J[Rebase / merge master\nonce near end of cycle]
    I --> K[Merge]
    J --> K

Loading

_{Last reviewed commit: 1db35f4}

[greptile-apps]

Guidance gap for larger PRs

The entire section is scoped to "small, focused PRs (roughly 5 files changed or fewer)". This leaves agents without any guidance for PRs that exceed that threshold. Since most of the bullet points (batch fixes, triage blocking vs. optional, deduplicate bot comments, rebase once near the end) apply equally well to any PR size, consider either dropping the conditional or adding a separate paragraph for larger PRs.

Suggested change

	For small, focused PRs (roughly 5 files changed or fewer and one clear purpose):
	For all PRs — and especially small, focused ones (roughly 5 files changed or fewer with one clear purpose):

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[greptile-apps]

Undefined classification categories

The terms blocking, optional, and noise are introduced here without a definition. Different agents or contributors may interpret these labels inconsistently, leading to divergent triage behavior. Consider adding a brief inline definition or a short legend, for example:

Suggested change

	- When asking an agent to address review comments, instruct it to classify comments into `blocking`, `optional`, and `noise`, then apply only the `blocking` items plus any explicitly selected optional items.
	- When asking an agent to address review comments, instruct it to classify comments into `blocking` (must fix before merge), `optional` (worth doing but not required), and `noise` (irrelevant, duplicate, or out-of-scope), then apply only the `blocking` items plus any explicitly selected optional items.