Skip to main content
skill CX Codex

bdd-principles — Claude Code skill: BDD and setup

The bdd-principles skill covers BDD foundations, Three Amigos sessions, and examples as living documentation. Use it when requirements need a shared reading before coding.

Apache-2.0 133 installs ★ 201 updated 2026-09-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TheBushidoCollective/han --skill bdd-principles -a claude-code
Open on GitHub

What bdd-principles does

The skill frames Behavior-Driven Development as a conversation between business and technical roles. It covers the Discovery, Development, and Delivery cycle, the Three Amigos practice, shared vocabulary, and Example Mapping.

It shows how concrete examples can guide acceptance tests, executable specifications, regression checks, and outside-in work. The included material uses Gherkin scenarios for password resets, promotions, and product search. The practical point is clear: teams need to settle rules and edge cases before turning examples into automation.

There is no separate slash command for this skill. After installation, the agent can use its guidance in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, or OpenCode.

What it helps with

  • clarify requirements with concrete examples
  • run a Three Amigos session
  • turn product behavior into Gherkin scenarios
  • create a shared domain vocabulary
  • map rules, examples, and open questions

Example prompts for the agent

  • Analyze this feature with the Three Amigos practice and surface the unanswered business rules.
  • Turn the password-reset requirements into Gherkin scenarios.
  • Use Example Mapping to separate the feature, rules, examples, and questions.

How to install bdd-principles

1Skills CLI (Vercel)

npx skills add TheBushidoCollective/han --skill bdd-principles -a claude-code

2Manually: put the files in place

~/.claude/skills/bdd-principles/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bdd-principles/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bdd-principles

How do I install bdd-principles in Claude Code?

Run npx skills add TheBushidoCollective/han --skill bdd-principles -a claude-code, then check ~/.claude/skills/bdd-principles/SKILL.md.

What does bdd-principles do?

It teaches core BDD ideas, Three Amigos, Example Mapping, ubiquitous language, and example-driven development. The guidance helps turn expected behavior into scenarios and living documentation.

What happens in a Three Amigos session?

Business, development, and testing perspectives examine the feature together. They discuss value, rules, technical constraints, edge cases, and how the result will be verified.

Source text

SKILL.md · Apache-2.0
---
name: bdd-principles
user-invocable: false
description: Core BDD concepts, philosophy, and the Three Amigos practice
---

# BDD Principles

Master the foundational principles and philosophy of Behavior-Driven Development.

## What is BDD?

Behavior-Driven Development (BDD) is a collaborative software development approach that:

- Bridges the gap between business and technical teams
- Uses concrete examples to describe system behavior
- Creates living documentation that serves as tests
- Focuses on delivering business value
- Promotes shared understanding through conversation

## Core Philosophy

### Discovery > Development > Delivery

**Discovery**: Collaborate to understand requirements

- Hold Three Amigos sessions
- Explore with examples
- Challenge assumptions
- Build shared understanding

**Development**: Implement guided by examples

- Use examples as specifications
- Automate examples as tests
- Follow outside-in TDD

**Delivery**: Validate against real behavior

- Executable specifications provide confidence
- Living documentation stays current
- Regressions are caught early

## The Three Amigos

A practice where three perspectives collaborate to explore and define features:

### 1. Business Perspective (Product Owner/BA)

- What problem are we solving?
- What value does it provide?
- What are the business rules?

### 2. Development Perspective (Developer)

- How might we build this?
- What are the technical constraints?
- What are the edge cases?

### 3. Testing Perspective (Tester/QA)

- What could go wrong?
- What are we missing?
- How will we verify this works?

### Example Three Amigos Session

**Feature**: Password Reset

**Business**: "Users who forget their password need a way to reset it via email."

**Developer**: "We'll need to generate secure tokens with expiration. How long should tokens be valid?"

**Tester**: "What happens if they request multiple reset emails? Can old tokens still be used?"

**Business**: "Tokens should be valid for 1 hour. Multiple requests should invalidate old tokens."

**Developer**: "Should we rate-limit reset requests to prevent abuse?"

**Tester**: "What if the email address doesn't exist in our system?"

**Business**: "For security, show the same success message whether or not the email exists."

**Outcome**: Concrete examples that become scenarios:

```gherkin
Scenario: Request password reset with valid email
  Given a user account exists for "[email protected]"
  When I request a password reset for "[email protected]"
  Then I should receive a reset email
  And the reset link should be valid for 1 hour

Scenario: Request password reset with non-existent email
  When I request a password reset for "[email protected]"
  Then I should see a success message
  But no email should be sent

Scenario: Multiple password reset requests
  Given I have requested a password reset
  When I request another password reset
  Then the previous reset link should be invalidated
  And I should receive a new reset email
```

## Living Documentation

BDD scenarios serve as:

1. **Executable Specifications**: Automated tests that verify behavior
2. **Documentation**: Up-to-date description of how the system works
3. **Common Language**: Shared vocabulary between business and technical teams
4. **Regression Suite**: Safety net when making changes

### Example: Living Documentation

```gherkin
Feature: Promotional Discount Application
  To attract customers and increase sales
  As a marketing manager
  I want to offer promotional discounts

  Rule: Percentage discounts apply to order subtotal
    Example: 20% off for orders over $100
      Given I have a $150 order
      When I apply a "20% off" promotion
      Then my discount should be $30
      And my order total should be $120

  Rule: Minimum purchase amount must be met
    Example: Promotion requires $50 minimum
      Given I have a $40 order
      When I try to apply a "$50 minimum" promotion
      Then the promotion should not apply
      And I should see "Minimum purchase not met"

  Rule: Only one promotion per order
    Example: Cannot stack multiple promotions
      Given I have a $100 order
      And I have applied "10% off"
      When I try to apply "Free shipping"
      Then I should see "One promotion per order"
      And only "10% off" should be applied
```

## Ubiquitous Language

Develop and use a shared vocabulary:

❌ **Technical Jargon**:

```
"When the user submits the form, we validate the input,
hash the password with bcrypt, insert a record into the
users table, and return a 201 response."
```

✅ **Ubiquitous Language**:

```
"When a customer registers, we verify their information,
create their account, and send a welcome email."
```

### Building Ubiquitous Language

**Discover terms through conversation:**

- What do you call this?
- What's the difference between X and Y?
- When does this state change?

**Document terms in scenarios:**

```gherkin
# Use "Member" not "User" (business term)
Given I am a Gold Member

# Use "Place order" not "Submit order" (domain term)
When I place an order

# Use "Pending" not "In progress" (system state)
Then the order should be Pending
```

**Keep a glossary:**

```
Member: A customer with a subscription
Guest: A customer without a subscription
Order: A collection of items ready for purchase
Cart: A temporary collection of items being considered
```

## Example Mapping

A workshop technique to explore features with examples:

### The Four Colors

**Yellow Cards**: User Stories/Features
**Blue Cards**: Rules (acceptance criteria)
**Green Cards**: Examples (scenarios)
**Red Cards**: Questions (uncertainties)

### Example Mapping Session

**Story**: User registration

**Rules** (Blue):

- Email must be unique
- Password must be strong
- Age must be 18+

**Examples** (Green):

- Register with valid details → Success
- Register with existing email → Error
- Register with weak password → Error
- Register under 18 → Error

**Questions** (Red):

- Do we verify email addresses?
- What defines a "strong" password?
- Do we need parent consent for minors?

## Specification by Example

Use concrete examples to drive development:

### Vague Requirement

"Users should be able to search for products."

### Specification by Example

```gherkin
Scenario: Search by product name
  Given products "Laptop", "Mouse", "Keyboard" exist
  When I search for "lap"
  Then I should see "Laptop" in results
  But I should not see "Mouse" or "Keyboard"

Scenario: Search with no results
  Given products "Laptop", "Mouse" exist
  When I search for "phone"
  Then I should see "No results found"

Scenario: Search is case-insensitive
  Given a product "Laptop" exists
  When I search for "LAPTOP"
  Then I should see "Laptop" in results
```

## Outside-In Development

Start from the outside (user-facing behavior) and work inward:

1. **Write a failing scenario** (acceptance test)
2. **Write a failing unit test** (for the layer you're working on)
3. **Write minimum code** to make unit test pass
4. **Refactor**
5. **Repeat** until scenario passes

```
Scenario (Acceptance) ─┐
                       ├─> Controller Test ─┐
                       │                    ├─> Service Test ─┐
                       │                    │                 ├─> Code
                       │                    │                 │
                       │                    ├─ Service        │
                       │                    │                 │
                       ├─ Controller        │                 │
                       │                    │                 │
Scenario Passes ───────┴────────────────────┴─────────────────┘
```

## BDD vs TDD

**TDD** (Test-Driven Development):

- Developer-focused
- Tests implementation
- Red-Green-Refactor cycle
- Unit tests guide design

**BDD** (Behavior-Driven Development):

- Business-focused
- Tests behavior
- Conversation-Specification-Automation
- Scenarios guide development

**They complement each other:**

- BDD: What should we build? (outside-in)
- TDD: How should we build it? (inside-out)

## Key Principles

1. **Collaboration is essential** - BDD requires active participation from business, development, and testing
2. **Examples clarify requirements** - Concrete examples reveal ambiguities and edge cases
3. **Automate what matters** - Not everything needs to be automated, focus on high-value scenarios
4. **Think behaviors, not tests** - Describe what the system does, not how it's tested
5. **Iterate and refine** - Scenarios evolve as understanding deepens
6. **Keep scenarios maintainable** - Write clear, focused scenarios that are easy to update

## Common Misconceptions

❌ "BDD is just testing with Cucumber"
✅ BDD is a collaborative practice; tools are just enablers

❌ "BDD means writing tests before code"
✅ BDD means discovering requirements through examples before implementation

❌ "BDD scenarios should test everything"
✅ BDD scenarios should document key behaviors; use unit tests for details

❌ "Only testers write scenarios"
✅ Business, developers, and testers collaborate on scenarios

❌ "BDD slows down development"
✅ BDD reduces rework by building the right thing the first time

## Benefits of BDD

- **Reduced rework**: Build the right thing from the start
- **Better collaboration**: Shared understanding across roles
- **Living documentation**: Always up-to-date specifications
- **Faster onboarding**: New team members learn from scenarios
- **Regression safety**: Automated scenarios catch breaking changes
- **Business confidence**: Stakeholders see value being delivered

Remember: BDD is fundamentally about communication and collaboration. The goal is to build software that delivers real value by ensuring everyone has a shared understanding of what needs to be built.

© TheBushidoCollective · Apache-2.0 · TheBushidoCollective/han

Similar skills

All skills for Testing and QA →
058-design-bdd Juan Antonio Breña Moral 058-design-bdd — a skill that takes Java teams through Behavior-Driven Development as collaborative discovery practice. Works with trusted behavior facts, concrete examples, and scenarios in shared domain language. CX Codex +1 135installs behavior-driven-development FradSer behavior-driven-development — a BDD skill for feature work, bug fixes, and executable tests. It turns behavior examples into failing tests before implementation. CX Codex +1 151installs gherkin-style-testing-cursorrules-prompt-file PatrickJS gherkin-style-testing-cursorrules-prompt-file — a Cursor rule that turns technical test scripts and manual cases into Gherkin scenarios written in plain business language. CX Codex +1 ★ 41,178repo stars serenity-bdd-skill TestMu AI serenity-bdd-skill is a Claude Code skill that creates Java BDD tests with Serenity and the Screenplay pattern. It activates for requests about Serenity, @Steps, or Serenity reports. CX Codex +1 223installs acceptance-pipeline-catalog pproenca acceptance-pipeline-catalog guides code agents through building, reviewing, and debugging Gherkin acceptance test pipelines with mutation testing based on Robert C. Martin's specification. CX Codex +1 142installs add-cucumber-tests Decathlon add-cucumber-tests turns a functional specification into Cucumber .feature files, using Tzatziki step definitions as the source of legal steps. Built for Java/Spring projects that already depend on Tzatziki or Cucumber. CX Codex +1 1,100installs

From the same set36

The whole set →
android-architecture This skill guides Android architecture with MVVM, clean layers, Hilt, and Room. Use it when shaping app structure or separating UI from business logic. CX Codex +1 141installs reactflow-fundamentals reactflow-fundamentals guides your agent in building node graphs, flowcharts, and workflow editors with React Flow. Covers node types, connection edges, and canvas controls. CX Codex +1 138installs django-orm-patterns The django-orm-patterns skill guides Django ORM work with models, queries, relationships, and database-side calculations. Use it when building data-driven Django applications. CX Codex +1 136installs c-systems-programming c-systems-programming equips the coding agent with low-level C patterns for process control, system I/O, asynchronous signals, and IPC pipelines. CX Codex +1 134installs elixir-ecto-patterns elixir-ecto-patterns — a skill that steers the agent through Ecto work: schemas, changesets, queries, associations, transactions. Useful when an Elixir app talks to a database. CX Codex +1 121installs storybook-play-functions Guides AI assistants in writing Storybook play functions for interaction testing using @storybook/test utilities. CX Codex +1 119installs tensorflow-neural-networks tensorflow-neural-networks — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that builds and trains neural networks using TensorFlow's Keras API and low-level custom implementations. CX Codex +1 116installs atomic-design-integration atomic-design-integration integrates Atomic Design methodology into React, Vue and Angular: folder structure, barrel exports, typed components and hooks. CX Codex +1 114installs

Project sponsors

Companies that keep this analytics open