Cursor rule

1---
2description: "Guidelines for Cursor background agents running long tasks autonomously in isolated VMs."
3alwaysApply: false
4---
5 
6# Background Agent Guidelines
7 
8Cursor Background Agents run long tasks autonomously in isolated Ubuntu VMs with internet access. They clone the repo from GitHub, work on a separate branch, and open PRs when complete.
9 
10## How Background Agents Work
11 
12- Each background agent runs in an isolated Ubuntu VM provisioned by Cursor
13- The agent clones the repository from GitHub (it does NOT use your local checkout)
14- It works on a dedicated branch and can commit, push, and open pull requests
15- You are notified when the task completes or if the agent needs input
16- Multiple background agents can run in parallel on different tasks
17 
18## SAFe Gate Chain Compliance
19 
20Background agents MUST follow the same SAFe workflow as interactive sessions:
21 
221. **Stop-the-Line Gate**: Verify AC/DoD exists before starting work
232. **Pattern Discovery**: Search `patterns_library/` before implementing
243. **Commit Format**: Use SAFe format `type(scope): description [{{TICKET_PREFIX}}-XXX]`
254. **Branch Naming**: Use `{{TICKET_PREFIX}}-{number}-{description}`
265. **Exit States**: Declare the correct exit state when complete
27 
28## PR Creation from Background Agents
29 
30When a background agent opens a PR:
31 
32- Reference the Linear ticket in the PR title: `feat(scope): description [{{TICKET_PREFIX}}-XXX]`
33- Follow the PR template from `CONTRIBUTING.md`
34- Include a test plan in the PR body
35- Tag appropriate reviewers per the 3-stage review process
36- The PR still requires QAS validation and HITL merge authority
37 
38## Best Practices
39 
40- Assign one ticket per background agent for clear scope
41- Provide the full spec path: `specs/{{TICKET_PREFIX}}-XXX-feature-spec.md`
42- Reference the agent role: "Act as the BE Developer" or "Act as the FE Developer"
43- Include validation commands the agent should run before opening the PR
44- Monitor agent progress via Cursor's background agent dashboard
45 
46## Limitations
47 
48- Background agents cannot access your local filesystem or environment variables
49- They start fresh from the GitHub remote each time
50- They cannot interact with local Docker containers or databases
51- Session state does not persist between background agent runs
52- They inherit repository-level Cursor rules but not user-level settings
53 
54## When to Use Background Agents
55 
56| Scenario | Use Background Agent? |
57|----------|-----------------------|
58| Implementing a well-specified story with clear AC | Yes |
59| Exploratory debugging or investigation | No -- use interactive |
60| Multi-file refactoring with clear scope | Yes |
61| Tasks requiring local environment (Docker, DB) | No -- use interactive |
62| Running test suites and fixing failures | Yes |
63| Architectural decisions requiring discussion | No -- use interactive |
64 
65## Example Invocation
66 
67```
68Run as a background agent:
69- Act as the BE Developer (see .claude/agents/be-developer.md)
70- Implement {{TICKET_PREFIX}}-42 per specs/{{TICKET_PREFIX}}-42-user-api-spec.md
71- Follow patterns from patterns_library/api/user-context-api.md
72- Run: pytest tests/integration/ && ruff check . && mypy .
73- Open a PR when all checks pass
74```
75