bdd-assistant

name	bdd-assistant
scope	partial
description	Guide developers through Behavior-Driven Development workflow. Use when: writing BDD scenarios, using Gherkin syntax, Given-When-Then format, feature files, Three Amigos collaboration. Keywords: BDD, behavior-driven, Given When Then, Gherkin, Cucumber, scenario, feature file, step definition, 行為驅動開發.

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 "[e-mail]"
  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:

1. 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?
   

2. 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:

1. 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]
   

2. 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:

1. 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', () => { ... });
   

2. 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

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

First-Time Setup

If no configuration found and context is unclear:

1. Ask: "This project hasn't configured BDD preferences. Which BDD tool do you use?"

   • Cucumber (JavaScript/TypeScript)
   • Behave (Python)
   • SpecFlow (C#)
   • Other

2. 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:

• BDD Core Standard
• BDD Workflow Guide
• Gherkin Quick Reference

For related standards:

• TDD Standards
• ATDD Standards
• Testing 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