Behavior-driven development (BDD) specifies and validates software behavior through user-focused examples. Gherkin gives testers and developers a shared vocabulary: Given describes the initial state, When the action, and Then the expected outcome. Developers can turn these scenarios into executable tests. section 6.2
Listing 6.1 The BDD approach — sending a message described as a Gherkin scenario
Feature: Real-time message delivery
Scenario: A message reaches another member live
Given Ada and Grace are both viewing the "general" channel
When Ada sends a message "deployment is green"
Then Grace sees "deployment is green" without reloading
This scenario specifies live message delivery from the users’ perspective, without prescribing its implementation. section 6.2
Write and review scenarios before implementation. Check that they express the intended behavior, cover edge cases, and are complete enough to support acceptance. Revising a scenario is cheaper than rebuilding a feature that solves the wrong problem. section 6.2 section 6.11
Use a repeatable process for each small delivery slice:
- Plan the slice and its dependencies, then write its Gherkin feature files. section 6.5 section 6.6
- Stop before building. Review and iterate on the scenarios; proceed only after explicit approval. section 6.6
- Run the scenarios and confirm they fail for the right reason, not because the test harness is broken. Build until they pass; fix the implementation rather than changing a scenario to fit it. section 6.6
- Deploy the slice, run its unit tests and BDD suite, and explore the app using the reviewed scenarios as a guide. section 6.11
Add an approval gate
When using Claude Code to plan a delivery, make the stop condition explicit: “Stop after generating the Gherkin scenarios so the user can review them. Iterate over the scenarios and wait for approval before continuing.” The gate keeps human review focused on the behavior contract before code is built. section 6.6 section 6.12







