Cursor Masterclass
for QA Engineers

Rules are persistent instructions that get inserted into the model context before the agent reads your prompt. For a QA team they are the place you encode the things you would otherwise repeat in every message: locator conventions, what a real assertion looks like, and the rule that a failing test is a finding, not a file to edit.

The four rule types and where each one lives

How a rule reaches the model, and why short beats long

• Rules are prepended, not remembered. LLMs do not retain memory between completions, so when a rule applies its contents are inserted at the start of the model context. There is no clever retrieval step for an always-applied rule: it is text, pasted in front of your conversation, every single turn.
• That is why length is a real cost. Cursor's guidance is to keep rules under 500 lines (guidance, not an enforced limit) and to split large rules into multiple composable rules. A 400-line "QA handbook" rule set to always apply is a tax on every request you ever send.
• Reference files instead of pasting them. A rule can reference a file with @filename.ts, for example @service-template.ts or @component-template.tsx. Referencing keeps the rule short and prevents the rule from going stale when the template changes.
• Rules compete with everything else in the window. The context breakdown tray (click the context ring next to the prompt input) shows Rules as its own category alongside the system prompt, tool definitions, skills, MCP instructions and the conversation itself. If the ring is running hot, rules are one of the things you are paying for.
• Add a rule only after you see the mistake twice. Cursor's stated practice: start simple, add a rule after Agent repeats the same mistake, check rules into git. Do not copy an entire style guide into a rule (use a linter), do not document every command (Agent knows npm, git and pytest), and do not restate what is already obvious from the codebase.

Project rules: .mdc files and the frontmatter that decides everything

• The extension is the contract. Project rules live in .cursor/rules as .mdc files. The filename itself can be anything, and rules can be organized into subfolders.
• All three frontmatter fields are set by the type dropdown. description, globs and alwaysApply. You can hand-edit them; the UI is writing the same three keys.

.cursor/rules/
  react-patterns.mdc       # Recognized as a project rule
  api-guidelines.md        # Ignored (wrong extension)
  frontend/                # Organize rules in folders
    components.mdc

The frontmatter interaction table. This is the single thing to get right on this tab.

The same four behaviors, named as the UI names them:

Glob patterns for file-scoped rules

Separate multiple patterns with commas.

AGENTS.md: rules with no frontmatter, nested by directory

• Plain markdown, project root. No metadata, no configuration, offered as an alternative to .cursor/rules. If your repo already has one for another tool, Cursor reads it.
• Subdirectories are supported and this is the useful part. A nested AGENTS.md is automatically applied when working with files in that directory or its children.
• Nested files combine, they do not replace. Nested instructions are combined with parent directories, and more specific instructions take precedence. So a root file can carry the repo-wide testing policy while tests/e2e/AGENTS.md carries the Playwright specifics.

project/
  AGENTS.md              # Global instructions
  frontend/
    AGENTS.md            # Frontend-specific instructions
    components/
      AGENTS.md          # Component-specific instructions
  backend/
    AGENTS.md            # Backend-specific instructions

Team Rules, enforcement, and precedence

• Team Rules are created and enforced org-wide from the dashboard. Admins decide per rule whether it is required.
• Two checkboxes decide whether a rule exists at all. Enable this rule immediately: leaving it unchecked saves the rule as a draft that does not apply until enabled. Enforce this rule: when on, the rule is required for all members and cannot be disabled in Customize. Non-enforced team rules can be toggled off by users under Team Rules in Customize.
• Content is free-form text. Team Rules do not use the folder structure of Project Rules, so there is no .mdc frontmatter to write.
• They support globs for file scoping. For example **/*.py. Without a glob, a Team Rule applies to every conversation. Scope your "all API tests must assert on the response schema" rule to the test globs, not to everything.
• Enabled Team Rules cross repositories. They are included in the model context for Agent (Chat) across all repositories and projects for that team.
• Precedence: Team Rules -> Project Rules -> User Rules. All applicable rules are merged, and earlier sources take precedence when guidance conflicts. Your personal User Rule cannot quietly override the org's enforced rule.

Creating, referencing and importing rules

1. Let the agent write the file. Type /create-rule in Agent and describe what you want. Agent writes the rule into .cursor/rules with the correct frontmatter, which removes the most common source of a rule that never fires.
2. Or use the UI. Customize -> Rules -> Add Rule. The type dropdown sets description, globs and alwaysApply for you.
3. Point at files rather than pasting them. Use @filename.ts inside the rule body, for example @migration-template.sql. Referencing beats copying: shorter rule, and it cannot go stale.
4. Import a rule set from GitHub. Customize -> Rules -> Add Rule -> Remote Rule (Github), then paste a repo URL (public, or private that you can access). Cursor scans the repo for all .mdc files, then pulls and syncs them.
5. Know where imports land. Imported rules go to .cursor/rules/imported/<repoName>, preserving relative paths. Review them like any other dependency before you rely on them.
6. Keep them in review. Check rules into git so they go through PR review, and tag @cursor on a GitHub issue or PR to have Agent update a rule.

Stated limits, and the things rules do not touch

• Rules do not affect Cursor Tab. The FAQ is explicit: rules do not impact Cursor Tab or other AI features. Your inline completions will happily ignore the conventions rule you just committed.
• User Rules do not apply to Inline Edit. They are not applied to Inline Edit (Cmd/Ctrl+K); they are used by Agent (Chat) only. If your personal rule seems to vanish, check which surface you are typing into.
• Under 500 lines is guidance, not enforcement. Nothing stops you writing a longer rule. The cost lands in the context window instead of in an error message.
• Composability is the intended answer to size. Split large rules into multiple rules, give concrete examples or referenced files, avoid vague guidance, and reuse rules rather than repeating the same prompt.

A starter QA rule set you would actually commit

Three files, one per trigger style. Together they cover roughly 80 percent of what a test-automation team keeps repeating in chat.

1. Playwright conventions, scoped to the test tree (.cursor/rules/playwright-conventions.mdc). Globs with no description, so it auto-attaches whenever a spec or page object is in context.

---
globs: tests/**/*.spec.ts, tests/**/*.page.ts
alwaysApply: false
---

- Prefer role and label based locators. Use a test id only when nothing semantic is stable
- Never use nth-child, XPath, or locators that depend on CSS class names
- Every spec opens with a test.describe named after the feature under test
- Page objects live in tests/pages and use named exports. Follow @login.page.ts
- Wait on the condition the test cares about. Never add a fixed timeout to stabilise a test

2. Test integrity, always on (.cursor/rules/test-integrity.mdc). Short on purpose: it rides along with every single request, so every line is paying rent.

---
alwaysApply: true
---

- Never delete, skip, or weaken an assertion to make a test pass
- A failing test is a finding. Report the failure and the suspected cause before changing any test file
- Do not change production code and its test in the same step without saying so explicitly
- Never commit credentials or real customer data into fixtures

3. API contract test conventions, description-driven (.cursor/rules/api-test-conventions.mdc). No globs, so Agent pulls it in when the description matches what you asked for.

---
description: Conventions for API contract tests, fixtures and response assertions
alwaysApply: false
---

- Assert status code and response schema as separate assertions so schema drift is not reported as a status failure
- Request fixtures live in tests/fixtures and are named after the endpoint they exercise
- Every negative-path test asserts on the error body, not only the status code
- Follow the fixture shape in @checkout.fixture.ts

Rules are text in front of the prompt, which makes them cheap and blunt. When you need instructions that carry scripts, templates and reference files, and that load only when relevant, you want Skills: that is the next tab.

A rule tells Agent how to behave. A skill gives it a capability: a folder of instructions, scripts and reference material that loads only when it is relevant. For a QA team this is where repeatable work (triage a flake, write a test plan, run a review pass) stops living in someone's head and starts living in the repo.

What a skill actually is

• A folder, never a loose file. Every skill is a directory containing a SKILL.md. A bare markdown file dropped in a skills root is not a skill.
• An open standard, not a Cursor-only format. Agent Skills is the standard published at agentskills.io, so the same folder works across any agent that supports it.
• Version controlled. Skills are tracked in your repo or installed from GitHub links, so a skill goes through review like any other change.
• Actionable. A skill can carry scripts, templates and references that the agent runs with its own tools, not just prose.
• Progressive. Resources load on demand, so a large skill does not cost you context until the moment it is needed.
• Discovered at startup. When Cursor starts it scans the skill directories, makes them available to Agent, and Agent decides from context when one is relevant. You can also force it: type / in Agent chat and search for the skill name.

Where Cursor looks for skills

• Compatibility directories load too. Cursor also reads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/, so a skill written for another agent is picked up without moving it.
• Project scope is the one to commit. Anything a reviewer needs to reproduce your workflow belongs at project level. User scope is for preferences.
• Check what loaded. Discovered skills are listed under Customize -> Skills, and they show up alongside rules in the Agent Decides section.
• Installing from GitHub. The documented flow is Customize -> Rules -> Add Rule -> Remote Rule (Github), then paste the repo URL.

.agents/
└── skills/
    └── my-skill/
        └── SKILL.md

The SKILL.md frontmatter

• Leave paths unset for an always-available skill. Patterns follow standard glob syntax. No paths means the skill can surface regardless of which files are open.
• globs is the legacy fallback. It is still accepted for older skills, but write paths in anything new.
• Keep SKILL.md short. Move detail into references/. Agents load resources progressively, so a thin entry file plus fat references is cheaper than one long file.

---
name: my-skill
description: Short description of what this skill does and when to use it.
---

# My Skill

Detailed instructions for the agent.

## When to Use

- Use this skill when...

## Instructions

- Step-by-step guidance for the agent
- Use the ask questions tool if you need to clarify requirements with the user

paths takes either a list or a comma-separated string:

---
name: react-component-patterns
description: Conventions for writing React components in this codebase.
paths:
  - "**/*.tsx"
  - "packages/ui/**/*.ts"
---

---
name: python-style
description: Style rules for Python files.
paths: "**/*.py, scripts/**/*.py"
---

Nested folders and monorepo scoping

• Category folders are free. Cursor walks the skills root recursively and picks up any SKILL.md. A folder like testing/ above your skills is purely organizational, it does not become part of the identity.
• Identity comes from the immediate parent. Only the folder directly containing SKILL.md names the skill.
• A nested skills root is auto-scoped. A .cursor/skills/ or .agents/skills/ folder anywhere in the repo is picked up, and skills in a nested project directory are automatically scoped to files inside that directory. You do not need paths for that case.

my-monorepo/
├── .cursor/skills/          # repo-wide skills
│   └── land-it/SKILL.md
└── apps/
    └── web/
        └── .cursor/skills/  # scoped to apps/web automatically
            └── deploy-web/SKILL.md

Scripts, references and assets

• Reference scripts by relative path from the skill root. Write scripts/deploy.sh <environment> or python scripts/validate.py in SKILL.md. Agent reads the instruction and executes the script when the skill is invoked.
• Any executable format works. Bash, Python, JavaScript, or anything else the agent implementation can run.
• Write scripts like production tooling. Self-contained, helpful error messages, graceful handling of edge cases. The agent cannot debug a script that fails silently.

Built-in Cursor skills

These ship with Cursor, are managed by Cursor, and appear alongside your own. Run any of them by typing / in Agent chat. Agent may also use some automatically when a request clearly matches. The pills mark the ones a tester reaches for.

/cursor-blame deserves a second look even though it is not on the QA list: when a regression lands in agent-authored code, it investigates the change and the prompt that produced it.

Migrating existing rules with /migrate-to-skills

• Dynamic rules convert. Rules using Apply Intelligently, meaning alwaysApply is false or undefined and there are no globs, become standard skills.
• Slash commands convert. Both user-level and workspace-level commands become skills with disable-model-invocation: true, which preserves their explicit-invocation behavior.
• Three things do not convert. Rules with alwaysApply: true, rules with specific globs, and User Rules (they are not stored on the file system).
• Review the output before committing. Generated skills land in .cursor/skills/.

# --- in Agent chat, not a terminal ---
/migrate-to-skills
/create-skill a skill that triages a flaky Playwright spec

Plugins: shipping a whole QA setup as one install

• The manifest is tiny. A plugin is a directory with a .cursor-plugin/plugin.json manifest plus its components. Only name is required. Components are discovered automatically from their default directories, or you can point at custom paths in the manifest.
• Plugins can also ship canvases. Prebuilt shared setup templates a team opens from an installed plugin in Customize.
• Distribution is Git plus review. Plugins are distributed as Git repositories, every plugin is manually reviewed before listing, all plugins must be open source, and each update is reviewed before publishing.
• Team marketplaces. Teams plan gets up to one, Enterprise gets unlimited, managed at Dashboard -> Plugins. On Enterprise, only admins can add them.
• Scope. Plugins can be scoped to a project or installed at the user level.

my-plugin/
├── .cursor-plugin/
│   └── plugin.json
├── rules/
│   └── coding-standards.mdc
├── skills/
│   └── code-reviewer/
│       └── SKILL.md
└── mcp.json

{
  "name": "my-plugin",
  "description": "Custom development tools",
  "author": { "name": "Your Name" }
}

1. Create the local plugin folder. ~/.cursor/plugins/local/my-plugin, with .cursor-plugin/plugin.json at the plugin root.
2. Symlink instead of copying. That way every edit is live and you are not testing a stale copy.
3. Reload. Restart Cursor or run Developer: Reload Window, then verify the components actually loaded in Customize.
4. Publish when it is stable. Submit for review at cursor.com/marketplace/publish. For a repo holding several plugins, add a marketplace manifest at .cursor-plugin/marketplace.json.

# --- shell, macOS and Linux ---
ln -s /path/to/my-plugin ~/.cursor/plugins/local/my-plugin

# --- PowerShell equivalent ---
# needs Developer Mode on, or an elevated shell. Otherwise copy the folder instead.
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.cursor\plugins\local\my-plugin" -Target "C:\path\to\my-plugin"

A QA skill worth committing

Flaky-test triage is the ideal first skill: it is a procedure everyone already does badly, it needs a script, it needs a reference table, and it should only surface when someone is looking at specs.

.cursor/skills/
└── flaky-test-triage/
    ├── SKILL.md
    ├── scripts/
    │   └── rerun.sh
    └── references/
        └── flake-taxonomy.md

---
name: flaky-test-triage
description: Triage an intermittent test failure. Use when a spec fails on CI but passes locally, when a spec fails only in a parallel run, or when someone asks whether a failure is a real bug or a flake.
paths:
  - "tests/**/*.spec.ts"
  - "e2e/**/*.spec.ts"
---

# Flaky Test Triage

## When to Use

- A spec failed on CI and passes on a local rerun
- The same spec fails only when the suite runs in parallel
- Someone asks whether a failure is a product bug or a flake

## Instructions

1. Re-run the single spec in isolation ten times: scripts/rerun.sh <spec-path> 10
2. If it passes every time, treat it as environment or ordering related. Check shared fixtures and seeded test data first.
3. If it fails intermittently, classify it against references/flake-taxonomy.md (wait, race, data, selector, network).
4. Never delete or skip the test. Either propose the fix, or quarantine it and open a ticket with the run log attached.
5. Report back: spec path, failure class, the evidence, the proposed fix, and whether it should block the release.

• The description is doing the real work. It names the situations, not the capability. That is what makes Agent pull the skill in without being told.
• The paths entry keeps it quiet. The skill stays out of context entirely while someone works on application code.
• Rule five is the QA part. The skill forbids the tempting fix (skip the test) and forces a decision about release impact.
• Same shape works for a test-plan generator. paths pointed at your spec directory, assets/test-plan-template.md, and instructions that require risk, scope and exit criteria in every plan.

Skills give Agent new capabilities inside the same context window. When the work is large enough that it would flood that window, or when you want an independent second opinion, you hand it to a subagent instead, and you enforce the rules of engagement with hooks.

Subagents give a task its own clean context window and hand back only the result. Hooks are the opposite direction of control: spawned processes that sit in the agent loop and decide what the agent is allowed to do. Together they are how a QA team turns policy into something the tool enforces rather than something the tool is asked politely to respect.

Where subagents live, and who wins

• Project beats user. When names conflict, the project subagent is the one that runs.
• Cursor beats the compatibility folders. Across locations, .cursor/ takes precedence over .claude/ or .codex/.
• Check them in. .cursor/agents/ belongs in version control, same as your rules and skills.
• Available in three places. Subagents work in the editor, in the CLI, and in Cloud Agents.
• Three are built in and need no configuration. explore (searches and analyzes codebases), bash (runs series of shell commands), browser (drives the browser through MCP tools). Each exists because its output is verbose and isolating it keeps the parent focused on decisions.

The frontmatter fields

• readonly: true is the QA field. A reviewer that cannot edit files and cannot run state-changing commands can be pointed at anything without a second thought. Set it on every subagent whose job is to look and report.
• Model parameters use bracket syntax. Append id=value pairs in square brackets to a model ID, comma-separated, for options like reasoning effort or context size. Empty brackets pin the base model and select the standard variant rather than the fast one.
• The configured model is not always honored. Cursor falls back to a compatible model when a team admin has blocked the model, when a legacy request-based plan requires Max Mode and it is not enabled, or when the model is not on your plan.

A review subagent a QA team can commit as .cursor/agents/test-reviewer.md:

---
name: test-reviewer
description: Reviews test code for assertions that cannot fail, sleeps used as synchronization, and selectors bound to markup. Use proactively after any change under tests/ or e2e/.
model: inherit
readonly: true
---

You review test code. You never edit files and you never run the suite.

When invoked:
1. Read every changed spec file named in the prompt.
2. Flag assertions that cannot fail, fixed sleeps used instead of waits, selectors bound to markup rather than roles or test ids, and shared mutable fixtures.
3. For each finding give file, line, why it is unsafe, and the smallest fix.
4. End with a single verdict: safe to merge, or needs changes.

How delegation actually happens

• Automatic. Agent decides based on task complexity and scope, your subagent descriptions, and the current context and available tools. Phrases like "use proactively" or "always use for" in the description encourage automatic delegation.
• Explicit with /name. The reliable path when you want a specific reviewer on a specific thing.
• Natural language. "Use the verifier subagent to confirm the auth flow is complete" also works.
• The description is the whole game. It is what Agent reads to decide whether to delegate at all. Invest in it, then test it: prompt the way your team actually prompts and check which subagent triggers.

# --- in Agent chat, not a terminal ---
/verifier confirm the auth flow is complete
/security-auditor review the payment module
/test-reviewer review the specs I changed on this branch

Parallelism, resuming and the nesting limit

• Parallel execution is real. Agent sends multiple Task tool calls in a single message, so the subagents run simultaneously.
• Every run returns an agent ID. Pass it back ("Resume agent abc123 and analyze the remaining test failures") to continue with full context. Background subagents write state as they run and can be resumed after completing.
• Background output is on disk. Background subagents write to ~/.cursor/subagents/, and the parent can read those files to check progress.
• Failures come back as a status. On failure the subagent returns an error status to the parent, which can retry, resume with more context, or handle it differently.
• Nesting stops at one level down. The main agent and its direct subagents can launch subagents, but a subagent launched by another subagent cannot launch further ones. Nested launches also require Task tool access in the current mode, and hooks or tool policies can block spawning.
• Tools are inherited, including MCP. Subagents inherit all tools from the parent. The exception: cloud subagents use the MCP servers configured for your team at cursor.com/agents, not your local ones.
• Cloud delegation. /in-cloud makes the next task run as a cloud subagent on its own VM and branch. /babysit has a cloud subagent iterate on a pull request remotely.

The honest cost trade-off

• N subagents cost roughly N times the tokens. Running five in parallel uses about five times the tokens of a single agent.
• Say it plainly: subagents are about context isolation, not speed. If you are delegating to go faster you will be disappointed and the bill will not be.
• The case that pays for itself. A long exploration that would otherwise fill the main window with search output, or an independent verification pass whose whole value is that it did not see how the code was written.

Subagents versus skills, as a decision

The docs are explicit about the failure mode: if you are creating a subagent for a simple single-purpose task like generating a changelog or formatting imports, make it a skill instead.

Anti-patterns

• Dozens of generic subagents. Fifty vague "helps with coding" agents are ineffective, because Agent has no basis to choose between them.
• Vague descriptions. The description drives delegation. If it does not name the situation, delegation does not happen.
• Two-thousand-word prompts. A giant prompt makes a subagent slower and harder to maintain, not smarter. Keep prompts concise.
• Duplicating slash commands. If a command already does it, a subagent adds cost and nothing else.
• Start with two or three. One clear responsibility each. Generate the first configs with /create-subagent, then trim them. Use hooks if you need subagents to produce structured output files.

Hooks: processes that talk JSON to the agent loop

• Mechanically simple. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block or modify behavior.
• Defined in hooks.json. At project or user level, or installed through plugins from Customize.
• The documented use cases map straight to QA work. Run formatters after edits, add analytics, scan for PII or secrets, gate risky operations such as SQL writes, control subagent (Task tool) execution, and inject context at session start.
• Third-party hooks load too. Cursor supports loading hooks from tools like Claude Code.
• Scripts can be anything executable. Bash, TypeScript run through a runtime, or Python. If a script needs a dependency installed, it must be installed wherever the hooks run.

Config locations and priority

• Priority runs Enterprise -> Team -> Project -> User. All matching hooks from every source run. When responses conflict, the higher-priority source wins during the merge.
• Project hooks need a trusted workspace. They run in any trusted workspace and are checked into version control, which makes committing .cursor/hooks.json the simplest way to distribute a policy to the whole team.
• Team hooks sync on a schedule. Cloud distribution syncs to all members automatically every thirty minutes, with operating-system targeting for platform-specific hooks.
• Reloading is automatic. Cursor watches hooks config files and reloads on save. If they still do not load, restart Cursor.
• Debug in two places. The Hooks tab in Customize and the Hooks output channel show what is configured, what executed, and what errored.

1. Write the script under .cursor/hooks/. Keep it beside the config it belongs to.
2. Make it executable. chmod +x .cursor/hooks/format.sh on macOS and Linux. A non-executable script is a hook failure, and by default a hook failure lets the action through. On Windows there is no chmod: write the hook as a script your shell can run and point command at it.
3. Register it in .cursor/hooks.json with the project-root relative path. Save, and Cursor reloads.
4. Watch the Hooks output channel while you trigger it. Confirm it fired before you trust it as a control.
5. Commit both files. Everyone on a trusted workspace gets the policy, and so do Cloud Agents.

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]
  }
}

Command hooks and prompt hooks

• Command-based is the default. It executes a shell script that receives JSON on stdin and returns JSON on stdout.
• Prompt-based uses an LLM. Set "type": "prompt" and give a prompt expressing a natural language condition. It returns a structured { ok: boolean, reason?: string } response and uses a fast model for quick evaluation.
• $ARGUMENTS carries the input. In a prompt hook the placeholder is auto-replaced with the hook input JSON, and if $ARGUMENTS is absent the input is auto-appended.
• Use command hooks for anything deterministic. A regex on a shell command is a control. An LLM judging whether a command looks safe is a heuristic, and it is not available in the cloud.

The events a QA team actually wires up

The full catalog splits into agent hooks (Cmd+K and Agent Chat): sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought; tab hooks (inline completions): beforeTabFileRead, afterTabFileEdit; and app lifecycle hooks: workspaceOpen. These are the ones worth your time first.

• Scripts get environment variables for free. CURSOR_PROJECT_DIR and CURSOR_VERSION are always present, CURSOR_USER_EMAIL when logged in, CURSOR_TRANSCRIPT_PATH when transcripts are enabled, CURSOR_CODE_REMOTE is the string "true" in a remote workspace, and CLAUDE_PROJECT_DIR is an alias for the project dir.
• Every hook also receives a common payload. Including conversation_id (stable across turns), generation_id (changes with every user message), hook_event_name, workspace_roots, user_email and transcript_path.

Matchers, and what each hook matches against

Every documented example passes a string pattern, so write it that way:

{
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "./scripts/approve-network.sh",
        "timeout": 30,
        "matcher": "curl|wget|nc"
      }
    ]
  }
}

What hook output cannot do

Hooks in cloud agents

• Command hooks only. Prompt-based hooks require authentication wiring between the hook and the agent loop that the cloud execution environment does not have.
• Three of the four sources load. Project hooks (from .cursor/hooks.json in the repo), team hooks and enterprise hooks all apply.
• User-level hooks are unavailable. ~/.cursor/hooks.json does not load, because cloud VMs have no access to your local home directory. If your safety net lives only in your home directory, it does not exist in the cloud.
• Early turns can be unhooked. Cloud agents sometimes begin in a read-only environment for exploratory turns, and hooks do not run during those turns. They start once the agent has a writable environment.
• Supported in cloud. beforeShellExecution, afterShellExecution, beforeReadFile, afterFileEdit, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeSubmitPrompt, preCompact, afterAgentResponse, afterAgentThought, stop.
• Not available in cloud. sessionStart and sessionEnd, beforeMCPExecution and afterMCPExecution, beforeTabFileRead and afterTabFileEdit (Tab is an IDE feature), and workspaceOpen (an IDE lifecycle hook).

Two hooks worth committing

One. Block a destructive command. The matcher narrows it to the commands you care about, and failClosed means a broken guard blocks instead of waving things through.

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-destructive.sh",
        "matcher": "rm -rf|drop table|truncate|db:reset",
        "timeout": 10,
        "failClosed": true
      }
    ]
  }
}

#!/bin/bash
json_input=$(cat)
echo "$json_input" >> /tmp/agent-audit.log
echo '{"continue": true, "permission": "deny", "user_message": "Destructive command blocked by the QA hook.", "agent_message": "That command was blocked. Use the seeded test database and the fixture reset task instead."}'
exit 0

• Everything on stdout is the response. Audit lines must go to a file, never to stdout, or the JSON is corrupted and the hook fails.
• The three valid shapes for this hook. { "continue": true, "permission": "allow" }, the deny above, or { "continue": true, "permission": "ask", "user_message": "GitHub CLI command requires permission" }.
• agent_message earns its place. It is fed to the agent when the action is denied, so use it to point at the approved path rather than leaving the agent to guess and retry.
• exit 2 is the shortcut. Exiting with code 2 blocks the action and is equivalent to returning permission: "deny", which is handy for a one-line guard.
• Make it executable. chmod +x .cursor/hooks/block-destructive.sh.

Two. Keep the agent away from secrets. beforeReadFile receives the absolute file_path and the full content, and its output decides whether the model ever sees the file.

{
  "version": 1,
  "hooks": {
    "beforeReadFile": [
      { "command": ".cursor/hooks/guard-secrets.sh", "failClosed": true }
    ]
  }
}

{ "permission": "deny", "user_message": "Blocked: this path is on the secrets list and is never sent to the model." }

The same idea as a release gate, using stop. When the loop ends without the suite having run, hand the agent its next instruction:

{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": ".cursor/hooks/test-gate.sh", "loop_limit": 2 }
    ]
  }
}

{ "followup_message": "The test suite was not run for this change. Run it now and report pass or fail before you finish." }

Subagents isolate context and hooks enforce policy. What decides how much rope the agent has in the first place is the mode it is running in, and what it can reach outside your repo is the MCP servers you connect. Both are next.

Plan Mode decides what gets built, Agent Review checks what got built, and checkpoints undo it when the agent gets it wrong. This tab covers those three, plus the context ring you should read before blaming the model, the browser tool that turns the agent into a manual tester, worktrees for running several agents on one repo, and MCP for wiring in the tools your team already runs.

Plan Mode: decide before you build

• What it is. Plan Mode creates a detailed implementation plan before writing any code. Agent researches the codebase, asks clarifying questions, and generates a reviewable plan you can edit before building.
• How you enter it. Press Shift+Tab from the chat input to rotate into Plan Mode, or pick it from the mode dropdown. Cursor also suggests Plan Mode automatically when you type keywords that indicate a complex task.
• What it produces. A plan file you can edit in chat or as markdown. Plans are saved by default in your home directory. Click Save to workspace to move a plan into the workspace for future reference, team sharing and documentation, which is what you want when the plan is the test strategy for a release.
• Nothing is written until you say so. No code is written until you click to build the plan.
• MCP works inside Plan Mode. Cursor uses MCP tools listed under Available Tools when relevant, including in Plan Mode, so a plan can be informed by your tracker or log search before a single file changes.

1. Agent asks clarifying questions. It pins down requirements instead of guessing them.
2. It researches your codebase. Gathering the relevant context itself, so you do not have to hand-feed files.
3. It creates a comprehensive implementation plan. The plan, not the diff, is the artifact at this stage.
4. You review and edit the plan. Through chat or through the markdown file.
5. You click to build. Only now does Agent start changing files.

Agent Review: a second pass on local changes

• What it is. A dedicated code review on your local changes, run from inside Cursor before anything reaches a pull request.
• Where the setting lives. Cursor Settings > Agents > Agent Review. If it is missing there, check Git & PRs > Pull Requests.
• It reads your repository rules. Agent Review reads repository rules from BUGBOT.md files, which means the same rules your PR reviewer enforces are enforced on your machine first. Set those up once and both surfaces agree (see tab 7).
• It can be automatic or manual. Enable it in settings to have reviews run without asking, or leave it manual and call it yourself.

Checkpoints: the undo button that is not Git

• Created automatically. Checkpoints save snapshots of your codebase during an Agent session. Agent creates them before making significant changes, capturing the state of all modified files.
• Three ways to restore. Click any checkpoint in the chat timeline to preview files at that point and then restore, use the Restore Checkpoint button on a previous request, or use the + button that appears when you hover over a message.
• Why a tester cares. When an agent rewrites twelve spec files and only three were meant to change, restoring a checkpoint is faster and more precise than trying to talk it back.

Context: read the ring before blaming the model

• The window is fixed and shared. Every chat shares a fixed context window. When it nears full, Cursor compresses older parts of the conversation into a summary, which is why an agent can forget a constraint you gave twenty turns ago.
• The context ring shows fullness. It sits next to the prompt input. Click it to open the breakdown tray, then hover a bar segment or a list row to highlight that category.
• Read the split, not just the total. If tools, rules, skills, MCP and subagents already take a large share of the ring, your code and your test output are competing for what is left. That is a configuration problem, not a model problem.

The Browser tool: your agent as a manual tester

• No setup required. You can use Browser without installing or configuring any external tools. Agent can control a web browser to test applications, audit accessibility and verify visual changes, with full access to console logs and network traffic.
• Logs are files, not summaries. Browser logs are written to files the agent can grep and selectively read. Instead of summarizing verbose output after every action, Agent reads only the relevant lines, which preserves context and saves tokens.
• Screenshots are images, not descriptions. Screenshots are integrated with the file reading tool, so Agent sees browser state as images. That is what makes layout and UI feedback usable.
• It gets extra hints. Agent receives total line counts and preview snippets for browser logs so it can decide what to inspect, and it is prompted to detect running dev servers and use the correct ports instead of starting duplicates.
• Sessions persist per workspace. Cookies (auth and session data), Local Storage (localStorage and sessionStorage) and IndexedDB content are retained between Agent sessions. The browser context is isolated per workspace, so projects keep separate storage and cookie state. Log in once, then keep testing the authenticated flows.

Allow list and block list live at Cursor Settings > Agents > Auto-Run. The browser itself runs as a secure web view controlled by an MCP server running as an extension, with a random authentication token generated before each session and a unique random ID per tab.

# in-chat prompts, typed into the Agent input (not shell)

@browser Check color contrast ratios, verify semantic HTML and ARIA labels, test keyboard navigation, and identify missing alt text

@browser Fill out forms with test data, click through workflows, test responsive designs, validate error messages, and monitor console for JavaScript errors

Worktrees: several agents, one repo, no collisions

• The problem they solve. Worktrees let Agent work in isolated Git checkouts. Each task gets its own files, dependencies and changes while your main checkout stays untouched, so you can start several agents on the same repo without conflicts.
• Availability gotcha. The UI-native worktrees feature is only available in the Agents Window. In the IDE you use the Worktree Skills commands instead.
• Setup is a repo file. Cursor checks .cursor/worktrees.json when creating a worktree from the Agents Window, the IDE or the CLI. Lookup order: the worktree path first, then the root path of your project.
• Each key takes commands or a script path. Either an array of shell commands executed sequentially in the worktree, or a string filepath to a script file relative to .cursor/worktrees.json. Put scripts in .cursor/ next to the config.
• Copy what Git will not. $ROOT_WORKTREE_PATH points at the root checkout, which is how you carry an untracked .env or fixture file across. Windows cmd uses %ROOT_WORKTREE_PATH%, PowerShell uses $env:ROOT_WORKTREE_PATH. That is also why a cp line under the generic setup-worktree key breaks on Windows: put the Windows commands in setup-worktree-windows and leave the fallback for the commands that genuinely run everywhere.
• Debugging setup. Open the Output panel in the editor and select the Worktrees Setup channel.

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": [
    "echo 'Using generic fallback. For better support, define OS-specific scripts.'"
  ]
}

# in-chat slash commands, typed into the Agent input (not shell)

/worktree fix the failing auth tests and update the login copy
/apply-worktree
/delete-worktree
/best-of-n sonnet,gpt,composer fix the flaky logout test

# shell
git worktree list

• /worktree <task> runs the rest of that chat in a separate checkout. Good for experimental edits, for installs, builds and test runs that would disturb your current branch, and for risky refactors with a simple cleanup path. In many cases you can commit and push directly from the worktree.
• /apply-worktree brings the changes into your main checkout so you can test them there. /delete-worktree cleans up when you are done.
• /best-of-n <models> <task> runs the same task across multiple models at once, each in its own worktree so candidates stay isolated. Limit: it compares runs only and does not merge changes back into your main checkout. After picking a winner, commit and push from that worktree or run /apply-worktree.
• Do not symlink dependencies into a worktree. The docs call this out directly: it can break the main worktree. Use a fast package manager such as bun, pnpm or uv instead.

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 25
}

MCP: connecting the tools your team already runs

• What it buys a tester. MCP lets Cursor connect to external tools and data sources, so the agent can pull a failing run, a ticket or a log query into the same session where it is writing the fix. You can write a server in any language that can print to stdout or serve an HTTP endpoint.
• Where servers come from. Install and manage them from the Customize page or configure them in mcp.json. Official plugins live in the Cursor Marketplace, community servers at cursor.directory.
• Disabled means invisible. Enable and disable servers from Customize in the sidebar. Disabled servers will not load or appear in chat, which is the fastest way to cut tool clutter out of the context ring.

A QA-shaped local server: run it over stdio so the credential never leaves your machine, and pull the token from the environment rather than hardcoding it.

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "${env:QA_TRACKER_TOKEN}"
      }
    }
  }
}

A remote server, HTTP or SSE, uses url and headers instead of command and args:

{
  "mcpServers": {
    "server-name": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

MCP approval and the security you should keep on

• Connections are approved once, tool calls are not. All MCP connections need your approval, and after you approve a connection each tool call still needs individual approval before running. You can pre-approve specific tools with an MCP allowlist. This is the single most misread part of MCP setup.
• MCP follows the same Run Modes as terminal commands. In Auto-review, allowlisted MCP tools run immediately and everything else is routed through the classifier (Run Modes are covered in tab 1).
• Cursor uses listed tools on its own. Tools under Available Tools are used when relevant, including in Plan Mode. You can also ask for a tool by name or just describe what you need.
• Team allowlists approve, they do not install. An MCP allowlist approves an MCP configuration. It does not distribute or install the server. Leaving a tool allowlist empty allows all tools from that server.
• Failures are isolated. If a server crashes or times out, Cursor shows an error in chat and marks the tool call failed, and other MCP servers keep working. Debug from the Output panel (Cmd+Shift+U) by selecting MCP Logs.

• Verify the source. Only install from trusted developers and repositories.
• Review permissions. Check what data and APIs the server will access before you connect it.
• Limit API keys. Use restricted keys with the minimum permissions the job needs, and never hardcode secrets.
• Audit code. Review the server's source for critical integrations, and consider an isolated environment.
• Keep sensitive servers local. The docs recommend running sensitive servers locally with stdio transport. "MCP servers can access external services and execute code on your behalf. Always understand what a server does before installation."

That covers everything the desktop app gives you. The same rules, skills, MCP servers and worktrees also run from a terminal, which is where QA automation actually lives, so tab 6 takes the agent into CI.

The Cursor CLI is the same agent without the editor, and it is the piece a tester can put in a pipeline. This tab is the reference: install, modes, every flag you will use, subcommands, slash commands, headless output for CI, the permission tokens that stop it doing something stupid, and where the config actually lives.

Install: the binary is agent

• The command is agent, not cursor. The product is the Cursor CLI, the binary you type is agent.
• It has two personalities. Interactive in your terminal, or print mode for scripts and CI pipelines.
• Authenticate once, or per script. agent login for interactive use. For scripts, export CURSOR_API_KEY or pass --api-key <key>.

# shell - macOS, Linux, WSL
curl https://cursor.com/install -fsS | bash

# shell - Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

# shell - first run
agent
agent "refactor the auth module to use JWT tokens"
agent -p "find and fix performance issues"

• It reads the same rules as the editor. Rules live in .cursor/rules and are loaded and applied automatically based on their configuration. The CLI also reads AGENTS.md and CLAUDE.md at the project root, if present, and applies them as rules alongside .cursor/rules.
• It reads the same MCP config. The CLI automatically detects and respects your mcp.json, from .cursor/mcp.json or ~/.cursor/mcp.json, so the servers you set up in tab 5 are already there.

The three modes

• Shift+Tab rotates between Agent, Plan and Ask, the same gesture as the IDE.
• A Debug mode also exists, reachable through the /debug slash command. It is not a --mode value.
• Say what you do not want. The docs recommend stating intent clearly, for example including "do not write any code" in the prompt to keep the agent from editing files. In a triage job that instruction matters more than the mode.
• Review before you accept. In an interactive session, Ctrl+R reviews changes, i adds follow-up instructions, arrow keys scroll and switch files. @ selects files and folders into context, /summarize frees context window space.

Flag reference

Global options work with any command.

Subcommands

• No command means interactive. When no command is specified, Cursor Agent starts in interactive agent mode by default.
• agent mcp has its own subcommands, all useful before you trust a server in CI: login <identifier>, list, list-tools <identifier>, enable <identifier>, disable <identifier>. Run list-tools first so your permission tokens name real tools.
• agent create-chat returns an ID, which is what makes a scripted multi-step job resumable with --resume.
• Shell integration is reversible. uninstall-shell-integration removes it from ~/.zshrc again.

Slash commands, grouped for scanning

These are typed inside an interactive session, never in your shell.

Headless mode: putting the agent in a pipeline

• Enter with -p or --print. This prints the response to the console and is the documented path for scripts and CI pipelines.
• Pick an output format. text for a human reading the job log, json when you want to pull the answer out with jq, stream-json when you want to watch tool calls as they happen.
• Authenticate with an environment variable. export CURSOR_API_KEY=your_api_key_here on macOS, Linux and WSL, or $env:CURSOR_API_KEY = "your_api_key_here" in PowerShell. You can also pass --api-key. Store it as a CI secret, never in the repo.
• Do not treat a missing --force as read only. The docs are inconsistent here: the headless page says that without --force changes are only proposed and not applied, while the parameter reference says -p, --print has access to all tools including write and shell. What is unambiguous is that combining --print with --force (or its alias --yolo) is the documented way to modify files in scripts. Until the docs reconcile the rest, get your read-only guarantee from a committed deny list, not from a flag you left off.
• --force still respects deny. The flag forces allow "unless explicitly denied", so the deny list in your permissions file is the real guardrail, not the flag.
• Files come in through the prompt. Include file paths in the prompt text and the agent reads them through tool calls. Paths can be relative to the working directory or absolute, and images are handled transparently.

# commit this FIRST, at .cursor/cli.json. Without it, --force means write and shell.
{
  "permissions": {
    "allow": ["Read(reports/**)", "Read(tests/**)", "Write(reports/**)"],
    "deny": ["Write(src/**)", "Write(tests/**)", "Shell(rm)", "Shell(git)", "WebFetch(*)"]
  }
}

#!/bin/bash
# shell - triage-failures.sh, run this after the test job fails
# Safe only because the deny list above is committed. The prompt is not the guard.

echo "Triaging failing tests..."

agent -p --force --output-format text "Read every JUnit XML file under reports/ and the spec files each failure names. For each failing test, classify it as product bug, test bug or environment issue, quote the assertion that failed, and write the table to reports/triage.md. Do not modify any test or source file."

if [ $? -eq 0 ]; then
  echo "Triage written to reports/triage.md"
else
  echo "Triage failed"
  exit 1
fi

# shell - other documented invocations
agent -p "What does this codebase do?"
agent -p --force "Refactor this code to use modern ES6+ syntax"
agent -p --output-format json "Analyze this image and provide a detailed description: $IMAGE_PATH" | jq -r '.result'
agent -p --force --output-format stream-json --stream-partial-output "Summarize the failing specs in reports/"

Reading stream-json

• Top-level .type values are system, assistant, tool_call and result.
• system with .subtype == "init" carries .model, which is what you log so a flaky run can be traced back to a model choice.
• assistant events split two ways: streaming deltas have timestamp_ms and no model_call_id, while buffered flushes before tool calls and at end of turn carry model_call_id. Text sits at .message.content[0].text.
• tool_call has a .subtype of started or completed. Payloads include .tool_call.writeToolCall.args.path, .tool_call.writeToolCall.result.success.linesCreated, .tool_call.writeToolCall.result.success.fileSize, .tool_call.readToolCall.args.path and .tool_call.readToolCall.result.success.totalLines. Watching writeToolCall.args.path is a cheap audit of exactly which files a CI agent touched.
• result carries .duration_ms. With --output-format json instead, the final answer is at .result.

Permissions: the part you commit

Permissions are set as permission tokens in ~/.cursor/cli-config.json (global) or <project>/.cursor/cli.json (project-specific).

• Glob wildcards are **, * and ?. Relative paths are scoped to the current workspace, absolute paths can target files outside the project.
• Deny rules take precedence over allow rules. This is the sentence that makes the file worth committing.
• Domain matching is specific. * matches all domains, *.example.com matches subdomains such as docs.example.com and api.example.com, and example.com matches that exact domain only.
• No WebFetch entry means a prompt. Without a WebFetch allowlist entry, each fetch prompts for approval, which will hang a headless job.
• Entries are exact strings. Typos do not fail loudly, they just never match.

A permissions block a tester can commit: the agent may run the suite and read the code, but it can only write into reports/, and it can never touch secrets or delete anything.

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(git)",
      "Shell(npm)",
      "Read(src/**/*.ts)",
      "Read(tests/**)",
      "Read(reports/**)",
      "Write(reports/**)",
      "WebFetch(docs.github.com)",
      "Mcp(*:search)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)",
      "Write(**/.env*)",
      "Write(src/**)"
    ]
  }
}

Configuration, and the one limitation to remember

• Required fields. version (number), editor.vimMode (boolean), permissions.allow (string array), permissions.deny (string array).
• Useful optional fields for a QA machine. approvalMode, sandbox.mode, sandbox.networkAccess, notifications, rewind, display.showThinkingBlocks, and the two attribution flags attribution.attributeCommitsToAgent and attribution.attributePRsToAgent, which add a "Made with Cursor" trailer to Agent commits and a footer to Agent PRs and default to true.
• Pure JSON, no comments. The CLI self-repairs missing fields, backs up corrupted files as .bad and recreates them. If the CLI misbehaves on startup, move the file aside and restart: mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad on macOS and Linux, or rename the file at $env:USERPROFILE\.cursor\cli-config.json on Windows.
• Environment overrides. CURSOR_CONFIG_DIR points at a custom directory. On Linux and BSD, XDG_CONFIG_HOME puts the config at $XDG_CONFIG_HOME/cursor/cli-config.json.
• Behind a corporate proxy. Set HTTP_PROXY, HTTPS_PROXY and NODE_USE_ENV_PROXY=1 before running, plus NODE_EXTRA_CA_CERTS if the proxy does SSL inspection. Some enterprise proxies do not support HTTP/2 bidirectional streaming, and network.useHttp1ForAgent: true switches agent connections to HTTP/1.1 with Server-Sent Events.

Worktrees from the CLI, and the cloud handoff

• -w or --worktree [name] keeps the agent off your checkout. It runs in a new Git worktree created under ~/.cursor/worktrees/<reponame>/<name>, alongside worktrees created from the editor. Omit the name and Cursor generates one.
• Setup and base are configurable. Setup scripts come from .cursor/worktrees.json and can be skipped with --skip-worktree-setup. --worktree-base <branch> bases the worktree on a branch or ref instead of current HEAD.
• Be explicit about the repo root. Combine --workspace <path> when you need an explicit repository root, otherwise the CLI uses the current working directory. --worktree only changes where the agent makes file edits inside that project.
• Same retention rules. CLI worktrees are cleaned up exactly like editor worktrees, so the machine-wide cap from tab 5 applies here too.

# shell
agent --worktree "upgrade the test runner and fix any broken snapshots"
agent --workspace ~/src/my-app --worktree auth-fix "fix the flaky auth test and open a PR"

# in-session message - prefix with & to hand off to a Cloud Agent
& refactor the auth module and add comprehensive tests

• The & prefix moves the conversation to the cloud. Prepend it to any message to push the conversation to a Cloud Agent mid-session, then pick it up on web or mobile at cursor.com/agents. Useful when a triage turns into a long refactor you do not want holding your terminal.
• Approve as you go, interactively. Before running terminal commands the CLI asks you to approve with y or reject with n. That prompt is exactly what --force removes, which is why the deny list matters more in CI than on your laptop.
• One gap to plan around. /review and /review-bugbot are not available in the CLI. Run pre-push reviews from the desktop app or from cursor.com/agents.

Which is the natural handoff: once the agent runs unattended, review has to become someone else's job. Tab 7 puts Bugbot, cloud agents and automations on review duty.

Everything up to here ran on your machine, at your pace, with you watching. This tab is the other half of the job: review that happens without you, agents that run in someone else's VM, and QA chores that fire on a schedule. Bugbot guards the pull request, cloud agents do the long jobs, automations put the recurring work on a timer.

Bugbot: what it reviews and how you turn it on

• It reviews pull requests, not your working tree. Bugbot analyzes the PR diff and looks for bugs, security issues, and code quality problems, then leaves comments with explanations and fix suggestions.
• It reads the conversation already on the PR. Existing top-level and inline comments from the connected provider are pulled in as context, so it avoids repeating suggestions and builds on prior feedback.
• Every finding has two escape hatches. A Fix in Cursor link opens the issue directly in the editor, and a Fix in Web link opens it at cursor.com/agents.
• Setup is two steps. Connect the repository provider from the Cursor dashboard, then enable Bugbot per repository at cursor.com/dashboard/bugbot. Supported providers: GitHub (including GitHub Enterprise Server), GitLab (including GitLab Self-Hosted), and Bitbucket (including Bitbucket Data Center).
• It runs on every PR update by default. Incremental Review is off by default, which means the full PR diff is reviewed on every push. Turn it on from the Bugbot dashboard to review only the changes since the previous Bugbot review.
• Scope differs between individual and team setups. For individuals, Bugbot runs only on PRs you author. On a team, it runs for all contributors to an enabled repository regardless of team membership.
• Effort levels are a paid dial. Default optimizes for speed and cost, High reasons longer and may find more bugs, and Custom lets you describe when deeper reviews are worth it. Effort levels are available only on usage-based Bugbot plans.

Every way to trigger a review

BUGBOT.md: the rules file both reviewers read

• The path is .cursor/BUGBOT.md. Bugbot always includes the root file, plus any additional BUGBOT.md files it finds while traversing upward from the changed files. A backend/.cursor/BUGBOT.md applies only when backend files are in the diff.
• Agent Review reads the same files. The local review you run in the editor before anyone sees your branch and the remote review on the PR share one rules source, so a rule you write once is enforced in both places.
• Rule content is free text. You are writing instructions, not filling in a schema. Documented example patterns include flagging eval() and exec(), blocking disallowed OSS licenses when dependency files change, flagging deprecated lifecycle methods, requiring tests for backend changes, and disallowing TODO and FIXME comments.
• A rule can do more than complain. Rules can raise blocking or non-blocking Bugs, set the title and body of a finding, assign it to the PR author, apply labels, suggest an autofix snippet, and auto-resolve a finding once it no longer applies.
• Rules stack from four sources. The merge order is Team Rules, then repository rules (learned and manual), then the project BUGBOT.md files including nested ones, then User Rules.
• Learned rules are generated for you. Enable learning per organization and repository at cursor.com/dashboard/bugbot/repository-rules. Cursor generates rules from your team's activity on that repository, or backfills from repository history, and enables or disables them as it learns. Manual rules live in the same dashboard with a Name, Rule content, and optional Scoped paths such as src/components/**.
• You can see whether a rule earns its place. Rule analytics report Issues found, PRs reviewed, Accepted issues, and Acceptance rate. Delete the rules nobody accepts.

A QA-shaped rules file. Every clause below maps to a documented capability: blocking versus non-blocking, title and body, assignment, labels, autofix suggestions, auto-resolve.

# .cursor/BUGBOT.md

## Weakened assertions are blocking

If a diff replaces an exact assertion with a weaker one (a truthiness check in place of a
value check, a removed expect, an assertion moved inside a try block), raise a blocking Bug.
Title it "Assertion weakened" and quote the old and the new assertion in the body.
Assign it to the pull request author and apply the label "test-quality".

## Backend changes need tests

If any file under src/api/ or src/services/ changes and no file under tests/ changes in the
same pull request, raise a non-blocking Bug titled "Backend change with no test".
Suggest an autofix snippet containing a skeleton test for the changed function.

## No skipped or focused tests reach the base branch

Flag any added test.skip, test.only, it.only or xit as a blocking Bug.
Auto-resolve the finding once the line no longer appears in the diff.

## Hard waits are a smell, not a fix

Flag any added fixed-duration sleep or timeout inside tests/ as a non-blocking Bug.
Explain in the body which condition should be waited on instead. Apply the label "flaky-risk".

## No TODO or FIXME in shared test helpers

Raise a non-blocking Bug on any added TODO or FIXME comment under tests/helpers/.
Apply the label "cleanup" and assign it to the pull request author.

Running Bugbot before anyone sees the branch

• /review-bugbot reviews branch changes, not just the last edit. By default it covers every change relative to the base branch, committed and uncommitted. Ask it to review only uncommitted changes when you want narrower feedback.
• It compares against your default base branch. When your base is something other than the default, tell the agent which branch to compare against or let it infer from context.
• The patch-id sync stops you paying twice. /review-bugbot stores the git patch ID of the diff it reviewed. When Bugbot on your source control provider later sees a diff with the same patch ID, it skips the review and leaves a comment saying it already reviewed that diff. Run it locally, open the PR with the same diff, and the remote review does not repeat.
• Where it works. /review and /review-bugbot are available in Cursor desktop builds and at cursor.com/agents. CLI support is documented as not yet available. Plan your CI review step around the PR trigger or the review API, not around the slash command.

Autofix and its ceiling

• What it is. Autofix spawns a Cloud Agent to fix bugs found during a PR review, pushes the fix, and posts a comment on the original PR with the results.
• Individual options. Use Installation Default, Off (fall back to the manual Fix in Cursor and Fix in Web links), Create New Branch (recommended), and Commit to Existing Branch.
• Team options. Off, Create New Branch (recommended), Commit to Existing Branch. Individual members can override the team default for their own PRs.
• The loop guard. Commit to Existing Branch is capped at 3 attempts per PR to prevent Autofix from fighting itself. If a finding survives three attempts, it is yours to fix.
• Model selection. Autofix uses your Default agent model from Settings -> Models, falling back to the team default model, then the system default.
• Requirements. On-demand usage pricing enabled, and storage enabled (so not Legacy Privacy Mode). Billing runs on Cloud Agent credits at your plan rates.

The check conclusion every QA lead gets wrong

Bugbot publishes a GitHub check named Cursor Bugbot and a Bitbucket build status with key cursor-bugbot. What that check reports is not what most people assume.

Cloud agents: the long jobs you should not babysit

• What they are. Agents running in isolated cloud VMs with a full development environment: cloned repos, installed dependencies, secrets, startup commands, and network access. You can run as many in parallel as you want, and your laptop does not need to stay online.
• What they can actually do. Build, test, and interact with the changed software; control a desktop and a browser through computer use; call MCP servers; work across a multi-repo environment spanning frontend, backend, infrastructure, and shared libraries, inspecting the whole workspace and opening pull requests in every repo they change.
• They produce evidence, not just diffs. Artifacts include screenshots, videos, and logs showing what changed and how the agent verified it, plus merge-ready PRs. For a tester this is the interesting part: the recording is the reproduction.
• You can take the wheel. Remote desktop control lets you drive the agent's desktop and test the software yourself without checking the branch out locally, then hand control back.
• The environment is a committed file. Environments are configured with agent-led setup, a saved snapshot, or a Dockerfile in .cursor/environment.json. The dashboard shows which environment each agent used, with details and version history.
• Prerequisite. An account admin must connect source control before anyone can start a cloud agent from a repository. Supported: GitHub (Cloud and Enterprise Server), GitLab (Cloud and Self-Hosted), Bitbucket Cloud, and Azure DevOps.

# in an interactive CLI session, hand the rest of the job to the cloud
& run the full regression suite against staging and attach screenshots for every failure

Automations: scheduled and event-driven QA work

• What they are. Automations run cloud agents in the background, either on a schedule or in response to events from GitHub, GitLab, Slack, webhooks, Linear, and more. The docs name reviewing recent PR commits for bugs, deep security review, triaging bugs in Slack, and summarizing codebase changes on a schedule.
• Four ways to create one. From the Agents Window, at cursor.com/automations, from a Cursor Marketplace template, or with the /automate skill in a local agent session, where you describe the workflow in plain language and Cursor configures the triggers, instructions, and tools for you.
• One automation can have several triggers. It runs when any of them fires.

1. Choose a trigger. Every hour, or when a pull request is opened, or when an incident is raised.
2. Write the prompt. Be specific about what to check, change, or produce. Reference the tools you enabled by name. Include decision rules for the different cases.
3. Choose the tools. Send to Slack, Comment on Pull Request, MCP tools, and the rest of the list below.
4. Decide the repository shape. One repository, a multi-repo environment, or no repository at all.
5. Set the quality bar and save. State when the agent should open a PR, when it should only comment, and when it should do nothing. Then save and activate.

Automation tools and settings

• Pull request creation. Repo-backed automations can open PRs after making code changes. Enabled by default for every automation.
• Comment on pull request. Top-level and inline comments. Enable approvals and the agent can also approve, request changes, and dismiss reviews. Without approvals it can only comment.
• Request reviewers. Uses git, memory, and other tools to identify domain experts.
• Send to Slack and Read Slack channels. Target one channel or let the agent choose. Allowing any channel also grants the read access needed to discover public channels.
• MCP server. Connecting a server gives the agent access to every tool that server exposes. Connect only servers you trust with the permissions the automation needs.
• Memories. Persistent notes across runs of the same automation, stored as a named entry (MEMORIES.md by default) outside the working filesystem. Enabled by default, editable and deletable from the UI. Treat them as untrusted input: memories persist, so a poisoned note can steer future runs.
• Computer use. Included by default. Lets the agent drive a browser, produce screenshots or recordings, and reach internal services. It needs a configured development environment to be useful, and you should ask for a demo in the instructions when you want the agent to show its work.
• Model, repositories, permissions, identity. You pick the model. Repositories are No repository, Single repository (one repo and one branch), or a Multi-repo environment. Permissions are Private, Team Visible, or Team Owned. On GitHub, comments, review approvals, and reviewer requests run as cursor; team-scoped automations open PRs as cursor while private ones open PRs as your account; Slack messages come from the Cursor bot.

Three automations worth building

1. Nightly flaky-test triage. Scheduled trigger, single repository, tools: Read Slack channels off, Send to Slack on, Memories on. Prompt it to re-run the specs that failed in the last CI window, separate genuine failures from non-deterministic ones, and post one Slack summary grouping tests by suspected cause. Memories give it a running record of which tests keep reappearing, which is the fact your team actually wants.
2. Test coverage check on every PR opened. Trigger: Pull request opened, plus Pull request pushed if you want it on every commit. Tools: Comment on pull request, no PR creation. Prompt it to list every behavior changed in the diff and say which of them has a test, then comment only when something is untested. Set the quality bar explicitly, otherwise it will comment on every PR and your team will mute it. This is the complement to your BUGBOT.md rules: Bugbot judges the code, this one judges the coverage.
3. Incident to reproduction case. Trigger: PagerDuty Incident triggered or Sentry Issue created, single repository, tools: computer use and pull request creation. Prompt it to read the incident payload, reproduce the failure against the environment in .cursor/environment.json, capture a screenshot or recording, and open a PR containing a failing regression test plus the artifact. You arrive in the morning to a red test that proves the bug instead of a paragraph describing it.

Bugbot guards the PR, cloud agents do the heavy runs, and automations handle the recurring work. None of that matters until it is one continuous habit.

Next: chain all of it into one workflow →

A login test in your Playwright suite has failed twice and passed on retry both times, so nobody filed it. Here is that test going from noticed to merged fix, using one artifact from every tab on this page, in the order you would actually touch them.

The pass, step by step

1. Ground the repo before you ask for anything. An AGENTS.md at the root stating the framework, the runner command, the fixture conventions, and the assertion style, plus one scoped .cursor/rules/flaky-triage.mdc with globs: tests/**/*.spec.ts saying how this team handles waits and retries. Without this the agent invents your conventions from the first file it opens. See rules for the frontmatter that decides when each file loads.
2. Set the guardrails before the first prompt, not after the first accident. Pick Auto-review as your Run Mode, add autoRun.block_instructions to .cursor/permissions.json in plain English ("Every command that drops or truncates a database table should go through approval first", "Every command that pushes or force-pushes should go through approval first"), and add a beforeShellExecution hook in .cursor/hooks.json for the destructive shapes you never want to argue about. Set failClosed: true on that hook, because hooks fail open by default and a crashed guard that lets the command through is not a guard. The run modes and hooks tabs have the exact shapes.
3. Scope it in Plan Mode instead of burning edit turns. Shift+Tab to Plan Mode and describe the symptom, not the fix: "the login spec passes on retry, find out why". The agent asks clarifying questions, researches the codebase, and produces a plan you can edit before a single line changes. Click Save to workspace so the plan is a reviewable artifact rather than a file in your home directory. If the build later goes sideways, revert and sharpen the plan; do not patch a wrong build with follow-up prompts.
4. Isolate it in a worktree. /worktree reproduce the flaky login test gives the agent its own checkout with its own dependencies, so a half-finished experiment never blocks your main branch. Commit .cursor/worktrees.json with the setup commands (install, copy the env file from $ROOT_WORKTREE_PATH, run migrations) so every new worktree is usable on arrival. Do not symlink dependencies in; use a fast package manager instead.
5. Reproduce it with the Browser tool. @browser plus the login URL, with instructions to run the flow ten times, watch the console and the network panel, and screenshot the state at the moment of failure. This is where flaky login tests usually confess: a race between a token refresh call and the first assertion, visible in network traffic and invisible in the test log.
6. Package the repeatable part as a skill. The reasoning you just did (how to distinguish a genuine failure from a timing failure in this codebase) belongs in .cursor/skills/flaky-test-triage/SKILL.md with paths scoped to your spec files, so the next person does not redo it. Remember the folder name must match the name in the frontmatter. See skills.
7. Delegate the verification to a subagent that cannot edit anything. A .cursor/agents/verifier.md with readonly: true runs in its own context window, cannot make file edits or run state-changing shell commands, and confirms the fix holds without any chance of quietly "helping" by adjusting the test. Give it everything it needs in the prompt: subagents start with a clean context and see none of your conversation.
8. Review locally before anyone else sees it. /agent-review in the agent window, or the Source Control tab to compare all local changes against your main branch rather than only the latest edit. Pick Deep depth for logic changes, Quick for a formatting pass. Agent Review reads your BUGBOT.md files, so it enforces the same rules the PR gate will.
9. Gate the PR with Bugbot. Run /review-bugbot before you push; the patch-id sync means the identical diff will not be reviewed twice on the PR. Your .cursor/BUGBOT.md is what catches the fix that "fixes" the flake by weakening the assertion. Configure fail-on-unresolved-issues if you want findings to actually stop a merge, because findings default to a neutral check.
10. Run it headless in CI. The same agent, non-interactive, with a permissions block committed in .cursor/cli.json so the pipeline's allowances live in the repo and not in one engineer's head. Only permissions can be configured at the project level; every other CLI setting is global. See the CLI in CI.
11. Schedule the recurring part. The one-off triage is done. The habit is an automation: a scheduled cloud agent that re-runs last night's failures, tells genuine failures from timing failures using the skill you wrote in step 6, and posts one grouped summary to Slack. That is the difference between fixing a flaky test and having fewer flaky tests.

# shell (macOS, Linux, WSL): the headless verification step in your pipeline
# PowerShell: $env:CURSOR_API_KEY = "your_api_key_here"
# --force allows anything the committed .cursor/cli.json deny list does not block.
# Commit that deny list before this line, not after the first incident.
export CURSOR_API_KEY=your_api_key_here
agent -p --force --output-format text "Run the login spec ten times, and write every failure with its console and network context to flaky-report.txt"

# in-session slash commands, in the order this workflow uses them
/worktree reproduce the flaky login test and capture a trace
/verifier confirm the login spec passes ten consecutive runs without a retry
/agent-review
/review-bugbot

What to commit

This is the whole page as a directory listing. If you copy one thing from here, copy this table.

The first week, in order

• Day one: two things only. An AGENTS.md and a Run Mode. That is the whole day-one setup. Auto-review is the recommended mode and needs no configuration file to work well.
• Once it is working: react, do not anticipate. The docs' own guidance on rules is to start simple and add a rule only after you see the agent repeat the same mistake. Apply that rule to everything on this page, not just to rules. Add the .mdc file for the convention that actually got broken. Add an autoRun.block_instructions line for the command that actually scared you. Add two or three BUGBOT.md clauses for the review comments you actually keep leaving.
• Then the force multipliers. Once you have a procedure you have run three times, package it as a skill. Once you want an opinion that cannot edit your branch, add one readonly: true subagent. Start with two or three focused subagents, not a directory of them: fifty vague "helps with coding" agents are documented as ineffective, and running five subagents in parallel costs roughly five times the tokens.
• Last: the automated surface. Hooks, cli.json for CI, environment.json, and automations come after the manual loop is boring. Automating a workflow you have not yet stabilised just gives you a scheduled version of your confusion.
• Prune on the same schedule you add. Keep rules well under the 500-line guidance and split large ones. Do not copy a style guide into a rule when a linter already enforces it, and do not document commands the agent already knows. Bugbot rule analytics report an acceptance rate for a reason: a rule nobody accepts is noise your team learns to scroll past.

The honest limits, and what stays yours

Read the safety story on this page as risk reduction, not as a control. Run Modes are described in the docs as best-effort guardrails rather than a hard security boundary, and Auto-review is called out by name as not a security boundary: its classifier can allow a call you would have blocked, and it can block a call you would have allowed. Both directions are real failure modes, and the second one is the one that tempts people into Run Everything. Hooks fail open unless you set failClosed: true. The browser origin allowlist does not stop link clicks, redirects, or JavaScript navigation. Team Rules can be marked as enforced and used in compliance workflows, and the docs still say plainly that AI guidance should not be your only security control. A model asked to behave is not an access control, and a check that reports neutral is not a merge gate.

What all of this buys you is leverage: the agent grounds itself in your conventions, isolates its experiments, reproduces the failure, gates its own diff, and repeats the boring part on a schedule. What it does not buy you is the last decision. Bugbot finds a weakened assertion; whether the fix is acceptable is a judgement about your product, your users, and your risk. The tester still owns the acceptance decision, and nothing on this page should be built in a way that quietly takes it away.