Cursor Code Review: Use Bugbot in a Current-Head Gate

How should you use Cursor code review?

Use Cursor code review in two loops: run /review locally for fast pre-push feedback, then run Bugbot on the committed pull-request diff. Verify every consequential finding and require a repository-owned verdict for the exact head commit. Cursor supplies review evidence; tests, branch policy, and maintainers retain merge authority.

Verified against Cursor documentation on August 5, 2026. Cursor's currentBugbot documentationdescribes a pull-request reviewer that analyzes diffs, posts explanations and fix suggestions, runs on updates, and supports manual triggers such ascursor review and bugbot run. Cursor'sJune 2026 Bugbot updatealso introduced local /review, /review-bugbot, and/review-security commands. Those surfaces answer different questions. Local review asks, “What should the author inspect before push?” Bugbot asks, “What did the PR reviewer find on this diff?” A merge gate asks, “May this exact revision merge under repository policy?”

The local and hosted loops may share work. Cursor says that if local/review sees a diff and a pull request later opens with the same diff, Bugbot can recognize it, skip a duplicate review, and leave a comment recording the reuse. Treat that comment as a provenance record: verify that the reused diff still matches the pull-request head before admitting it to the gate.

Choose the right Cursor code review surface

Start with the decision you need to make. The local command is an authoring preflight: it keeps feedback close to the working tree and lets you fix obvious defects before reviewers see them. Bugbot is a pull-request reviewer: it creates a shared GitHub record, can rerun on updates, and can attach findings to the diff. A repository gate is policy: it combines review evidence with required tests, approvals, and current-head checks.

Do not collapse the three into one green icon. Local review can pass while the committed diff changes during cleanup. Bugbot can find no issue while a required integration test fails. Tests can pass while a reviewer catches a compatibility break the suite does not encode. Themerge-safe AI review workflow for GitHubexplains how to combine those signals without giving model prose policy authority.

This separation is useful even when one vendor supplies more than one surface. Independence comes from the subject, permissions, and artifact contract, not from choosing a different model name. An author-side tool should not be able to rewrite the policy that judges its own change.

Set up Cursor Bugbot for pull request review

Bugbot setup happens through Cursor's dashboard and GitHub app. Cursor's official instructions require Cursor administrator access and GitHub organization administrator access for the connection. Connect GitHub, select the repositories Bugbot may review, and enable the reviewer on a representative repository before rolling it out broadly.

1. Open the Bugbot area in the Cursor dashboard.
2. Connect or manage the Cursor GitHub app installation.
3. Grant access only to the repositories that need review.
4. Enable Bugbot on one repository with representative pull requests.
5. Choose automatic review on updates or an explicit manual-trigger policy.
6. Add a root .cursor/BUGBOT.md with two or three tested invariants.
7. Open a small pull request and inspect the Cursor Bugbot check, its conclusion, comments, and runtime.

Record the observable contract before rollout: the exact GitHub check name, the head SHA it reviewed, whether it concluded success, neutral, orfailure, and whether a new push invalidates the old result and schedules another run. Setup is complete only when a maintainer can connect that check to the current pull-request revision without inferring state from comment timestamps.

Treat the GitHub App boundary as part of setup. Before approving the installation, review the repositories and permissions GitHub displays; after installation, use GitHub'sinstalled-app controlsto inspect or narrow repository access. Do not infer Cursor's data boundary from a product label—confirm the live installation request and your organization's policy.

Start narrow. Automatic review on every update is useful when the signal is quiet and the cost is understood. Manual review is safer while rules are noisy or while a team is learning which changes need the extra pass. Cursor'scurrent pricing pagedescribes Bugbot as usage-based, so review frequency and effort are operational choices as well as quality choices. Check the live page instead of copying a fixed per-run number into repository policy.

A successful installation proves only that the reviewer can run. Test whether it can recognize your repository's actual failure modes. Prepare a small evaluation set: one known violation, one safe counterexample, and one unrelated change. The first checks recall, the second checks noise, and the third checks whether the rule is scoped tightly enough.

Write Bugbot rules that encode repository risk

Cursor uses .cursor/BUGBOT.md for project-specific review context. The root file is always included. Additional files are selected by walking upward from a changed file, which lets a service own its local constraints without forcing every pull request to carry every rule.

A useful rule names an invariant, its consequence, the safe path, and its scope. “Check security” is too broad. “Every webhook signature must be verified over the untouched request body before JSON parsing; otherwise a valid signature can be rejected or a modified body can be trusted” gives the reviewer a claim and a causal failure path to inspect.

# Bugbot review rules

## Public artifact compatibility

- Preserve existing fields in `reviewgate-agent-result/v1`.
  Renaming or removing a field breaks external repair agents.
  Add a versioned field or schema before changing the contract.

## Current-head publication

- Never publish a usable review result unless `reviewed_sha`
  equals the pull request head being evaluated.

Keep deterministic checks out of prose. A formatter should enforce formatting. A type checker should enforce types. Bugbot rules should capture history and product judgment that those tools cannot infer: compatibility promises, authorization boundaries, idempotency rules, destructive migration constraints, or required failure behavior.

Review the rules as code. Add a rule with a representative violation, observe the finding, and then run the safe counterexample. Narrow any instruction that reports the counterexample. Remove obsolete rules when the architecture changes. A large rule file that nobody tests is another source of confident noise.

Track reviewed diff, finding disposition, and merge verdict

Most Cursor code review guides stop after setup and fixes. The missing contract is state. A review system needs to distinguish three records that change at different times: the diff a reviewer saw, the disposition of each consequential finding, and the repository verdict for the current head.

This contract turns “run an AI reviewer and fix the comments” into something a maintainer or repair agent can audit. Each state has an owner and invalidation rule. The reviewed diff belongs to the reviewer invocation. Finding disposition belongs to an evidence policy. The merge verdict belongs to the repository.

ReviewGate supplies evidence for the first two states in public source. Its stable result records repository and pull-request scope, reviewed_sha, structured findings, dispositions, typed review errors, and a score derived from admitted blockers. Repository CI, approvals, and branch policy compose that evidence into the third state: the merge verdict. See thefeature and scoring contract for the exact ReviewGate policy, or inspect theagent-result schema directly.

Conceptual combined record (not a ReviewGate artifact):

review_evidence:
  reviewed_sha: a1b2c3d
  result_status: passed
  finding:
    id: public-schema-field-rename
    disposition: fixed
    evidence:
      source: compatibility-test
      result: passed
repository_policy:
  required_ci: passed
  required_approvals: 1/1
  outcome: merge_allowed

The first block is review evidence. The second is repository policy. Keeping them separate makes it clear which system may change a finding and which system may authorize a merge.

Run a current-head Cursor code review workflow

The workflow below keeps the fast Cursor loop while adding an auditable merge decision. Each step has a completion condition. If you cannot name what “done” looks like, the step is advice rather than a gate.

1. Define the pull request contract

   Record the intended change, affected interfaces, expected tests, and explicit non-goals before asking Cursor or Bugbot to review the diff.

   Done when the pull request states the change, interfaces, tests, and non-goals in reviewable terms.

2. Run a local preflight

   Use Cursor's local /review command before push to catch obvious defects while the author still has the implementation context.

   Done when the author has resolved or recorded every consequential local finding before push.

3. Run Bugbot on the pull request

   Enable automatic review for each update or trigger Bugbot manually, then inspect the Cursor Bugbot check conclusion and confirm which pull request revision its review evidence covers.

   Done when the Cursor Bugbot result or explicit reused-diff record can be tied to the current head and its findings are available.

4. Verify consequential findings

   Require each potential blocker to identify an exact changed location, a checked claim, a causal failure path, and the relevant test state.

   Done when every potential blocker has repository evidence or is excluded with a recorded reason.

5. Record finding disposition

   Mark every blocker as still open, fixed, rejected with evidence, intentional, or needing human judgment instead of treating an outdated comment as resolution.

   Done when every known blocker has one explicit, evidence-backed current disposition.

6. Bind policy to the current head

   After every relevant push, require a fresh repository-owned result for the exact commit GitHub is evaluating and retain unresolved obligations across reruns.

   Done when review evidence names the pull request head and every required check applies to the commit shown in GitHub's checks box.

7. Keep merge authority explicit

   Combine the current review result with deterministic CI, branch protection, required approvals, and maintainer judgment before merging.

   Done when repository policy records a pass or block outcome and the responsible maintainer makes the merge decision.

Require the check in GitHub without confusing its role

1. Let Bugbot complete once so GitHub records the exact Cursor Bugbot check identity.
2. Open the repository ruleset or protected-branch settings for the merge branch.
3. Add that exact Bugbot status under required status checks if its completion is mandatory.
4. Require deterministic CI and approvals separately; a Bugbot pass does not satisfy them.
5. Push a harmless commit and confirm the earlier check becomes insufficient until a new run completes.

Requiring Bugbot makes GitHub wait for the check, but it is not finding-sensitive by default. Cursor documents success for no issues and no unresolved prior comments; neutral for findings, cancellation by a newer commit, or an internal error; and failure when findings exist and fail-on-unresolved behavior is enabled. GitHub accepts neutral as satisfying a required check. Where Cursor offers fail-on-unresolved issues, enable it if Bugbot findings themselves must block. Otherwise, add ReviewGate or another repository-controlled policy check that converts verified finding state into a failing verdict. GitHub'srequired-check guidanceexplains how required checks attach to the revision GitHub evaluates.

ReviewGate can supply the repository-owned part without replacing Cursor. Install the ReviewGate GitHub Action as a separate review job, keep Bugbot for its native Cursor workflow, and require only the checks your branch policy explicitly trusts. External repair agents can consume theexact-head repair-loop contract instead of scraping review comments.

Do not make a model-generated score configurable by pull-request text. The reviewed code is untrusted input. Thresholds, finding admission, required checks, and workflow permissions should live in trusted repository or organization configuration. That prevents a change under review from quietly weakening its own judge.

Trace one Bugbot finding through the three states

Consider a pull request that changes a public JSON field fromreviewed_sha to commit_sha. The local Cursor pass notices the rename. Bugbot applies the repository rule, attaches a finding to the changed schema line, and explains that existing external agents still require the old field.

The review comment is presentation. To admit the finding as a blocker, verify the checked claim: the public v1 schema requires reviewed_sha, the serializer removed it, and a fixture or consumer test fails. Record that evidence with the reviewed head. At this point the finding is still_open and the merge verdict cannot pass.

The author restores the field and adds a compatibility test. That push creates a new head, so the old review is stale even though the evidence suggests the issue is fixed. Run deterministic CI and request a current-head review. The finding moves tofixed only when the replacement code and test settle the same causal claim. A fresh repository verdict can then pass if no other admitted blocker remains.

Now change the example: the public contract was intentionally versioned to v2 and every consumer migrated. The correct disposition is not “fixed.” It isrejected_with_evidence or an intentional-contract state, backed by the new schema and migration record. Explicit disposition preserves why the comment did not lead to a code change.

Bind every Cursor code review result to the current head

GitHub evaluates required checks for the commit shown in the pull request checks box. Itsrequired-status-check guidanceexplains that this can be the test merge commit when it has a status, otherwise the head commit. Bind Bugbot review evidence separately to the pull-request head: a clean review on commit A cannot prove commit B is clean. Even a one-line test fix can alter production code, generated files, dependencies, or review instructions.

Store the head SHA in the machine-readable result and compare it with the live pull request immediately before the pass decision. Treat a mismatch as stale, not as a low score and not as success. A provider timeout or malformed artifact is also not a code-quality verdict; represent it as an unavailable review state and retain the latest valid evidence separately.

Incremental review is useful for latency and cost, but it does not remove the state problem. The reviewer must know the trusted prior revision and the delta it is adding to the result. An unresolved finding from the prior revision must survive unless the new delta contains evidence that settles the same claim. Reviewer silence on a later run is not resolution evidence by itself.

Interpret a Bugbot run with no findings

Start with the check conclusion, not comment count. Cursor definessuccess as no issues and no unresolved Bugbot comments from earlier runs. A neutral conclusion can mean findings, cancellation by a newer commit, or an internal error, so it is not a clean signal even though GitHub allows neutral required checks to pass. Confirm which current-head diff or explicit reused local review the result covers, then examine evidence sources Bugbot does not own.

• Did required unit, integration, migration, and security checks pass?
• Did the pull request change an interface that lacks a contract test?
• Did a human reviewer raise an unresolved product or architecture concern?
• Were the applicable BUGBOT.md rules present on the reviewed head?
• Did the reviewer complete, or did the service fail without publishing findings?

Keep “no finding” distinct from “finding resolved.” The former describes one invocation. The latter describes an evidence-backed transition for a known obligation. Conflating them creates the familiar rereview bug where a model omits a prior comment and automation silently marks the defect fixed.

Avoid common Cursor code review failure modes

Using the authoring pass as independent review

The local command is valuable, but it shares the author's working context and may never produce a durable artifact. Use it to improve the change before push. Use a separate pull-request invocation for evidence that other reviewers can inspect.

Writing broad rules without counterexamples

“Flag every possible breaking change” invites noise. Name the protected contract, the actual break, and the compatible path. Test the rule against a safe change so the reviewer learns where the boundary stops.

Parsing comment tone as merge policy

Reactions, prose summaries, and comment counts are presentation. They are difficult to version and easy to misread. Require a check or structured artifact with an explicit state for the current head.

Assuming a moved comment is fixed

GitHub may mark an inline comment outdated when its line changes. That says the anchor moved; it does not prove the causal defect disappeared. Preserve stable finding identity and require resolution evidence.

Letting a service failure become a clean review

A missing review, timeout, or provider error is inconclusive. Fail closed for merge policy, report the operational error separately, and retry within a bounded policy. Never convert unavailable review into “no bugs found.”

Cursor code review pre-merge checklist

• The pull request contract names affected interfaces, tests, and non-goals.
• Local Cursor review ran before push where it added useful feedback.
• The Cursor Bugbot conclusion and covered diff are known for the current pull-request head.
• Applicable root and nested .cursor/BUGBOT.md rules were present.
• Every consequential finding has exact repository evidence and a causal path.
• Every known blocker has an explicit current disposition.
• Required deterministic CI passed for the commit shown in GitHub's checks box.
• The repository-owned verdict names the reviewed SHA and usable review state.
• Required human approvals and unresolved human comments are satisfied.
• A maintainer still owns the final risk and merge decision.

If you want this contract as a check instead of a manual convention,install ReviewGate and configure the review angles that encode your repository's real risks. ReviewGate remains review-only: it publishes evidence and a score, while your tests, branch protection, and maintainers decide what may merge.

If your team uses Windsurf instead, theWindsurf code review guide applies the same freshness boundary to Quick Review, Devin Review, and agent-generated Autofix commits through an explicit review-epoch contract.

Cursor code review questions