Comprehensive Rules for writing clear, testable, and outcome-focused acceptance criteria using BDD (Given-When-Then) in Agile environments.
You're tired of building the wrong thing. Requirements that shift mid-sprint. Acceptance criteria that create more confusion than clarity. Tests that fail because nobody understood what "correctly" actually meant.
These Cursor Rules transform how you define, communicate, and validate software requirements using battle-tested BDD practices.
Every development team faces these productivity killers:
Result: 47% of project failures stem from poor requirements management (PMI Study). Your team spends more time in clarification meetings than coding.
Transform vague requirements into crystal-clear, testable specifications using Gherkin's Given-When-Then format. These rules enforce BDD best practices that create living documentation your entire team can understand and validate.
Before (Typical User Story):
As a user, I want to reset my password so I can access my account
Acceptance Criteria:
- User can reset password
- System sends email
- Password gets updated
After (BDD Excellence Rules):
Scenario: Registered user resets forgotten password
Given a user with email "[email protected]" has an active account
When the user requests a password reset
Then the system sends a reset link to "[email protected]"
And the link expires after 24 hours
Scenario: Password reset with expired token
Given a user received a reset link 25 hours ago
When the user opens the expired link
Then the system displays "Link expired, request a new one"
And the system offers to resend a new link
Old Process: Product manager explains requirements verbally, developers take notes, QA guesses at test cases.
New Process: Collaborative BDD session produces executable specifications:
@JIRA-456
Scenario: Customer views order history with filters
Given a customer has placed 15 orders in the last year
And 3 orders were cancelled
When the customer filters by "cancelled" status
Then the system displays exactly 3 orders
And each order shows "Cancelled" status
And the orders are sorted by date descending
Before: Reviewers guess if implementation matches requirements After: Every PR links to specific Gherkin scenarios that validate the behavior
Before: "It doesn't work correctly" bug reports After: Failed Gherkin scenarios pinpoint exact conditions:
Scenario: System handles concurrent password resets
Given user "[email protected]" requests password reset
When the same user requests another reset within 30 seconds
Then the system invalidates the first token
And only the second reset link remains valid
Add these Cursor Rules to your .cursorrules file. The configuration includes Gherkin syntax enforcement, BDD pattern recognition, and integration guidelines for Jira/TestRail.
Take your current story and run it through the BDD Excellence framework:
## Jira Integration
- Tag scenarios with ticket IDs: `@JIRA-123`
- Sync nightly with TestRail
- Link failed scenarios back to tickets
## CI Pipeline
- Feature files execute on every merge
- Pipeline blocks on scenario failures
- Screenshots attached for debugging
AI-assisted development makes code generation faster, but garbage requirements still produce garbage software. While tools generate implementation, you still need crystal-clear specifications of what to build.
These BDD Excellence Rules ensure your AI pair programmer, your human teammates, and your stakeholders all understand exactly what success looks like - before anyone writes a line of code.
Your next sprint starts with better requirements. Your team delivers exactly what users need. Your stakeholders see their vision implemented correctly the first time.
Transform how your team thinks about requirements. Start writing acceptance criteria that actually work.
You are an expert in Agile Product Development, Behavior Driven Development (BDD), Gherkin syntax, Jira, and TestRail.
Key Principles
- Collaboratively define acceptance criteria with Product, QA, Dev, and Stakeholders before implementation begins.
- Focus on the user outcome (WHAT) and observable behaviour; never prescribe the technical implementation (HOW).
- Each criterion must be specific, measurable, and independently testable with a clear pass/fail.
- Use concise, plain language free of jargon or ambiguity; prefer active voice.
- Describe happy path first, then edge cases and exceptions.
- Keep criteria atomic—changing one should not change the interpretation of another.
- Maintain a living link between criteria and automated tests (Jira ↔ TestRail ↔ CI).
Gherkin
- Always employ the Scenario (or Scenario Outline) keyword followed by a meaningful title.
Example:
```gherkin
Scenario: Registered user resets forgotten password
```
- Structure every scenario with Given-When-Then blocks in that exact order.
• Given: system state & pre-conditions.
• When: single user action.
• Then: single expected result.
- Use And/But for additional steps but avoid more than 3 consecutive Ands; split into a new Scenario or Background.
- Avoid UI-specific terms; describe behaviour (e.g., “user submits credentials” not “user clicks the green button”).
- Use data tables for multiple permutations and Scenario Outlines for parameterised examples.
- Indent exactly two spaces; never use tabs.
- Begin files with `# language: en` when localisation is required.
- File naming: kebab-case matching epic or feature (e.g., `password-reset.feature`).
Error Handling and Validation
- Create a dedicated scenario for every identified edge case, error state, or business rule violation.
Example:
```gherkin
Scenario: Password reset token is expired
Given a user has received a reset link 25 hours ago
When the user opens the link
Then the system displays the message "Link expired" and offers to resend a new link
```
- Specify quantitative limits ("within 2 seconds", "no more than 3 retries") so automation can assert performance.
- Use explicit negative assertions (Then the user is NOT logged in) rather than implying absence.
- Do not chain multiple validations in one Then; enumerate them with separate Thens.
BDD Framework (Cucumber / Behave / SpecFlow)
- Background blocks may declare common context but keep them <5 Given lines; otherwise refactor into hooks.
- Tag scenarios with Jira ticket IDs (e.g., `@JIRA-123`) to enable traceability.
- Use `@wip` tag for scenarios under refinement; exclude them from CI until tags removed.
- Always map each step definition to one domain action; avoid regex wildcards that match dissimilar behaviour.
- Fail fast: step definitions must raise explicit exceptions on unmet pre-conditions.
Additional Sections
Testing & Automation
- Integrate feature files into CI so they execute on every merge; block the pipeline on failure.
- Store screenshots or logs for any failed Then assertion and link them back to the scenario via attachments in Jira.
Performance Criteria
- Write separate scenarios for load/performance when needed. Prefix title with `Performance:`.
- Capture metrics using hooks and assert against thresholds in Then steps.
Security Criteria
- Document security-related behaviour (e.g., rate limiting, XSS sanitisation) as rule-oriented scenarios.
- Ensure sensitive data examples are masked (`<masked>`) in feature files to prevent leakage.
Tooling Conventions
- In Jira, place acceptance criteria in the issue’s “Acceptance Criteria” field using markdown lists where each item references the corresponding Gherkin scenario title.
- Sync TestRail cases nightly; use identical titles for easy mapping.
Common Pitfalls & Anti-Patterns
- DON’T embed UI colours, CSS classes, or DOM IDs in criteria.
- DON’T combine multiple user actions under one When; split them.
- DON’T describe implementation details such as database tables or API routes.
- DON’T leave criteria vague (e.g., “works correctly”). Replace with explicit outcomes.
Checklist Before Marking Story "Ready for Dev"
1. All acceptance criteria written in Gherkin & peer-reviewed.
2. Each criterion has at least one edge-case scenario.
3. Performance and security benchmarks included where applicable.
4. Criteria linked to Jira ticket and synced to TestRail.
5. Stakeholders have approved via comments or formal sign-off.