BDD Assistant

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2026-01-19 Applicability: Claude Code Skills

Purpose

This skill guides developers through the Behavior-Driven Development workflow, helping them:

Conduct Discovery sessions to explore requirements
Write effective Gherkin scenarios in Given-When-Then format
Create reusable step definitions
Integrate BDD with TDD for implementation
Maintain living documentation

Quick Reference

BDD Workflow Checklist

┌─────────────────────────────────────────────────────────────────┐
│  🔍 DISCOVERY Phase                                              │
│  □ Stakeholders identified (Business, Dev, QA)                  │
│  □ User story discussed and understood                          │
│  □ Concrete examples collected (Example Mapping)                │
│  □ Edge cases identified                                        │
│  □ Questions answered or noted for follow-up                    │
├─────────────────────────────────────────────────────────────────┤
│  📝 FORMULATION Phase                                            │
│  □ Scenarios use correct Gherkin syntax                         │
│  □ Scenarios are declarative (WHAT, not HOW)                    │
│  □ Business language used (no technical jargon)                 │
│  □ Each scenario is independent and self-contained              │
│  □ Scenarios have 5-10 steps maximum                            │
│  □ Scenarios reviewed by stakeholders                           │
├─────────────────────────────────────────────────────────────────┤
│  ⚙️ AUTOMATION Phase                                             │
│  □ Step definitions created for all steps                       │
│  □ Step definitions are reusable                                │
│  □ Scenarios fail initially (RED)                               │
│  □ TDD used for unit-level implementations                      │
│  □ All scenarios pass (GREEN)                                   │
│  □ Code refactored and clean                                    │
└─────────────────────────────────────────────────────────────────┘

Gherkin Quick Reference

| Keyword | Purpose | Example | |---------|---------|---------| | Feature | Container for scenarios | Feature: User Login | | Scenario | Single test case | Scenario: Successful login | | Given | Set up initial context | Given I am on the login page | | When | Trigger action | When I enter valid credentials | | Then | Assert outcome | Then I should see my dashboard | | And/But | Continue previous | And I should see a welcome message | | Background | Common setup | Runs before each scenario | | Scenario Outline | Data-driven | Template with Examples table |

Declarative vs Imperative

# ❌ BAD - Imperative (too detailed, UI-focused)
Scenario: Login
  Given I navigate to "http://example.com/login"
  And I click on the username field
  And I type "john@example.com"
  And I click on the password field
  And I type "secret123"
  And I click the submit button
  Then I should see "Dashboard" in the page title

# ✅ GOOD - Declarative (behavior-focused)
Scenario: Successful login with valid credentials
  Given I am a registered user
  When I login with valid credentials
  Then I should see my dashboard

Three Amigos Quick Reference

| Role | Focus | Questions to Ask | |------|-------|------------------| | Business (PO/BA) | What & Why | "What's the value?", "Who are the users?" | | Development | How | "What's the technical impact?", "Dependencies?" | | Testing (QA) | What if | "What could go wrong?", "Edge cases?" |

Workflow Assistance

Discovery Phase Guidance

When exploring requirements:

Example Mapping

🟡 User Story: "User can login"
     │
     ├─ 🔵 Rule: "Users must be authenticated"
     │      ├─ 🟢 Example: Valid credentials → login success
     │      └─ 🟢 Example: Invalid credentials → error message
     │
     ├─ 🔵 Rule: "Account lockout after failures"
     │      ├─ 🟢 Example: 3 failures → account locked
     │      └─ 🟢 Example: Locked account → cannot login
     │
     └─ 🔴 Question: Password expiration policy?

Questions to Ask
- What's the happy path?
- What could go wrong?
- What are the boundary conditions?
- What's explicitly out of scope?

Formulation Phase Guidance

When writing scenarios:

Feature File Structure

Feature: Feature name
  As a [role]
  I want [feature]
  So that [benefit]

  Background:
    Given common preconditions

  Scenario: Descriptive scenario name
    Given [initial context]
    When [action]
    Then [expected outcome]

Scenario Style Guidelines
- One behavior per scenario
- Use business language
- Keep steps declarative
- Aim for 5-10 steps maximum
- Make scenarios independent

Automation Phase Guidance

When implementing:

Step Definition Best Practices

// ✅ Good: Reusable, parameterized
Given('I have {int} items in my cart', (count) => { ... });

// ❌ Bad: Specific to one scenario
Given('I have 3 widgets in my cart', () => { ... });

BDD + TDD Integration

BDD Scenario (feature level)
     │
     └──▶ Step Definitions
             │
             └──▶ TDD Cycle (unit level)
                   🔴 Write failing unit test
                   🟢 Implement minimal code
                   🔵 Refactor

Integration with Other Workflows

BDD + SDD

When working with Spec-Driven Development:

# Reference spec in feature file
# @spec SPEC-001
@SPEC-001
Feature: User Authentication
  Implements SPEC-001 user authentication requirements.

  @AC-1
  Scenario: Successful login
    # Acceptance Criterion 1 from SPEC-001
    ...

BDD + TDD

Scenario Level (BDD)           Unit Level (TDD)
─────────────────────          ─────────────────
Scenario: Checkout    ──────▶  test_calculate_total()
  Given cart items             test_apply_discount()
  When checkout                test_create_order()
  Then order created           test_send_email()

BDD + ATDD

ATDD: Acceptance Criteria (business sign-off)
  │
  └──▶ BDD: Feature Files (Gherkin scenarios)
         │
         └──▶ TDD: Unit Tests (implementation)

Configuration Detection

This skill supports project-specific configuration.

Detection Order

Check CONTRIBUTING.md for "Disabled Skills" section
- If this skill is listed, it is disabled for this project
Check CONTRIBUTING.md for "BDD Standards" section
Check for existing .feature files in the codebase
If not found, default to standard BDD practices

First-Time Setup

If no configuration found and context is unclear:

Ask: "This project hasn't configured BDD preferences. Which BDD tool do you use?"
- Cucumber (JavaScript/TypeScript)
- Behave (Python)
- SpecFlow (C#)
- Other
After selection, suggest documenting in CONTRIBUTING.md:

## BDD Standards

### BDD Tool
- Cucumber.js

### Feature File Location
- `features/` directory

### Scenario Style
- Declarative (behavior-focused)
- Business language required
- Max 10 steps per scenario

Detailed Guidelines

For complete standards, see:

For related standards:

Anti-Patterns Quick Detection

| Symptom | Likely Problem | Quick Fix | |---------|----------------|-----------| | Scenarios break on UI changes | Imperative style | Use declarative language | | Business can't read scenarios | Technical jargon | Use business language | | Scenarios pass but features don't work | Missing scenarios | Better Discovery sessions | | Too many scenarios | Scenario explosion | Use Scenario Outlines | | Step definitions duplicated | Not reusable | Extract to helpers |

Related Standards

Behavior-Driven Development - Core BDD standard
Acceptance Test-Driven Development - ATDD standard
Test-Driven Development - TDD standard
Spec-Driven Development - SDD workflow
Testing Standards - Testing framework
TDD Assistant - TDD skill

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-01-19 | Initial release |

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards