| 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 "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
Given('I have {int} items in my cart', (count) => { ... });
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
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