nledford/engineering-review-board / skills/behavior-driven-development
behavior-driven-development
VerifiedApply Behavior-Driven Development to clarify user-visible behavior, acceptance criteria, business workflows, and executable examples before or during implementation. Do not use to author formal .feature syntax; use gherkin.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
SKILL.md
View on GitHub---
name: behavior-driven-development
description: Apply Behavior-Driven Development to clarify user-visible behavior, acceptance criteria, business workflows, and executable examples before or during implementation. Do not use to author formal .feature syntax; use gherkin.
---
# Behavior-Driven Development
Use BDD to turn user intent into concrete, observable behavior before choosing
implementation details. Treat it as a collaboration and specification practice,
not as a requirement to write `.feature` files for every change.
Use [`gherkin`](../gherkin/SKILL.md) when these examples must become formal
`.feature` artifacts. Use Gherkin alone for syntax-only edits when the behavior
is already clear.
For photo/video DAM workflows, compose with
[`digital-asset-management`](../digital-asset-management/SKILL.md) to express
original preservation, metadata conflicts, hierarchy moves, smart-collection
membership, rendition authorization, and asset-version restore as observable
behavior rather than implementation details.
## When to Use
Use BDD when the work involves:
- User-visible behavior, product rules, workflows, permissions, or outcomes.
- Ambiguous acceptance criteria that need examples before implementation.
- Cross-functional expectations from product, domain experts, QA, support, or
existing behavior contracts.
- Acceptance, integration, end-to-end, or contract tests that should describe
behavior in business-readable terms.
- Bug fixes where the failure should be captured as an externally observable
regression.
Do not force BDD for:
- Trivial documentation edits, formatting-only changes, mechanical renames, or
dependency bumps with no behavior change.
- Purely technical refactors whose behavior is already well covered.
- Low-level implementation details that are better specified with unit tests.
- Formal `.feature` grammar, dialect, or step wording when no behavior
clarification is needed; use [`gherkin`](../gherkin/SKILL.md).
## Workflow
1. Identify the behavior.
- Restate the user's request as observable outcomes: who does what, under
which conditions, and what changes from the user's or system's perspective.
- Prefer domain language from the request, product docs, tests, and code.
- Separate behavior from mechanism: describe effects, not classes, tables,
routes, selectors, or algorithms unless they are part of the public contract.
2. Create examples before implementation when useful.
- Write a short Given/When/Then sketch even if no `.feature` file is needed.
- Cover the main success path, important alternatives, and meaningful failure
cases.
- Keep scenarios specific and testable; avoid broad statements such as
"works correctly" or "handles errors".
- If the examples need a `.feature` file, load
[`gherkin`](../gherkin/SKILL.md) for local syntax and runner conventions.
3. Choose the executable layer.
- Use acceptance tests for product-level flows.
- Use integration or contract tests for API, storage, messaging, or boundary
behavior.
- Use end-to-end tests only when browser, device, or full-system behavior is
essential evidence.
- Use unit tests for small domain rules that do not need business-readable
acceptance coverage.
4. Implement to satisfy the examples.
- Let scenarios guide scope; avoid adding behavior that is not described or
needed.
- Keep test names, assertions, docs, and user-facing text aligned with the
behavior vocabulary.
- Update scenarios when implementation reveals a better business rule, but do
not weaken them to fit an accidental design.
5. Verify and report.
- Run the tests that execute the described behavior.
- State which scenarios or examples are covered and which are deferred.
- Call out any ambiguity that remains in product or domain expectations.
## Architecture Boundaries
- BDD should stay mechanism-neutral, but architecture affects where examples are
executed. In Clean, Hexagonal, or Onion designs, drive scenarios through a
public API, inbound adapter, use case, or application service rather than
private classes, database rows, or framework internals.
- Load [`hexagonal-architecture`](../hexagonal-architecture/SKILL.md) when
acceptance behavior must be mapped to ports, adapters, or external actors. Load
[`clean-architecture`](../clean-architecture/SKILL.md) for use-case,
interactor, presenter, or interface-adapter boundaries. Load
[`onion-architecture`](../onion-architecture/SKILL.md) for domain/application
rings around a protected domain model.
- Do not put ports, repositories, controller names, ORM details, or layer names
in Given/When/Then steps unless those mechanisms are part of the public
contract.
## Given/When/Then Thinking
Use this structure to sharpen behavior even outside Gherkin files:
```text
Given <important context or state>
When <the actor performs the meaningful action>
Then <the observable outcome should occur>
And <additional outcome, only when it belongs to the same behavior>
```
Good:
```text
Given a member has an expired invitation
When they try to accept it
Then the system rejects the invitation
And explains that a new invitation is required
```
Poor:
```text
Given the invitation row has expires_at in the past
When the controller calls InvitationService.accept()
Then it returns Error::Expired
```
The poor version may be useful as a unit test note, but it is not a
business-readable behavior specification.
## Scenario Quality Checklist
- The scenario title names the behavior, not the implementation.
- The actor, context, action, and expected outcome are clear.
- Steps are declarative and business-readable.
- Details are specific enough to test but not brittle.
- Every scenario can map to an automated test or a deliberate manual check.
- Scenarios avoid duplicate coverage unless each duplicate protects a distinct
rule, role, or boundary.
## Common Pitfalls
- Writing UI scripts instead of behavior: avoid clicks, selectors, HTTP status
codes, and database fields unless those are the contract being specified.
- Hiding assertions in vague wording: every `Then` should be observable.
- Adding ceremony after the fact: if examples did not influence scope or tests,
BDD was probably unnecessary.
- Over-covering the obvious: one clear scenario is better than many variants
that do not change the business outcome.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |