Gherkin BDD Conventions

Standards for generating BDD scenarios, step definitions, and maintaining the bdd/ scaffold.

Scaffold Structure

The canonical bdd/ directory tree:

bdd/ ├── features/ │ ├── INDEX.md │ ├── cross-domain/ │ └── {domain}/ │ └── {feature-name}.feature ├── steps/ │ ├── INDEX.md │ ├── world.[ext] │ ├── common_steps.[ext] │ ├── api_steps.[ext] │ ├── db_steps.[ext] │ └── {domain}_steps.[ext]

Note: bdd/.claude/rules/ is user-created when needed for custom domain mappings — it is not part of the auto-generated scaffold.

Language Detection Rules

Scan existing step files to determine the language:

• Glob bdd/steps/. and count file extensions: .py , .go , .ts .

• If no step files exist → default to Python (behave).

• If one language detected → use that language.

• If multiple languages detected → use the majority language and warn: "Mixed languages detected in bdd/steps/ : {list}. Using majority language: {language}."

• Never create step files in a different language than detected.

Language-to-Framework Mapping

Extension Language Framework Step syntax

.py

Python behave @given , @when , @then decorators

.go

Go godog ctx.Step registration in InitializeScenario

.ts

TypeScript cucumber-js Given , When , Then from @cucumber/cucumber

Format Detection Rules

• Glob bdd/features/**/*.feature.md .

• Glob bdd/features/**/*.feature (excluding .feature.md matches).

• If .feature.md files exist → use MDG format (Markdown-Gherkin).

• Else if .feature files exist → use standard Gherkin.

• Else → default to standard Gherkin (.feature ).

• Never mix formats within bdd/features/ .

Domain Detection Priority

Determine domain subdirectories under bdd/features/ using this priority — stop at the first source that yields names:

• User-defined rules: Glob bdd/.claude/rules/*.md for explicit domain mappings.

• BDD conventions file: Read bdd/CLAUDE.md for domain conventions.

• Existing domain folders: Glob bdd/features/*/ — preserve existing domains.

• Changelog: Read prd/changelog.md for domain-organized sections.

• PRD specs: Glob prd/specs/*/ and group slugs into logical domains.

• Codebase structure: Glob top-level and server/ /src/ subdirectories.

If no sources yield domains, create a single general/ domain folder. Always ensure cross-domain/ exists. Use kebab-case naming.

File Naming Rules (FR-0KTg-016)

• Use kebab-case: user-registration.feature , not userRegistration.feature or user_registration.feature

• Name must describe the feature, not a scenario: password-reset.feature , not forgot-password-click.feature

Tagging Rules (FR-0KTg-017)

Every scenario must have at least one tag. Choose from:

Tag When to use

@smoke

Core happy-path scenarios that must always pass

@regression

Standard coverage scenarios

@critical

Scenarios testing security, data integrity, or financial correctness

@backend

Scenarios that test server-side behavior only

@fullstack

Scenarios requiring UI + backend interaction

@{domain}

Domain-specific tag matching the folder name (e.g., @auth , @billing )

Scenarios may have multiple tags. Feature-level tags: @{domain} and one priority tag (@smoke , @regression , or @critical ).

Step Writing Rules

Rule Requirement Good example Bad example

Declarative Given (FR-0KTg-018) Given steps describe state, not procedures Given user alice is logged in

Given I open the login page and type alice into the username field

Exact Then (FR-0KTg-019) Then steps make exact assertions Then the balance is exactly $94.00

Then the balance is around $94

Reusable patterns Use parameterized patterns for similar steps Given user {name} is logged in

Given user alice is logged in

• Given user bob is logged in as separate steps

Gherkin Construct Selection (FR-0KTg-046 through FR-0KTg-049)

Situation Construct Example

Unique flow with specific setup and assertion Scenario

Login with valid credentials

Same flow tested with different inputs/outputs Scenario Outline

• Examples

Login with various invalid credentials

Multiple scenarios sharing the same preconditions Background

All scenarios need a logged-in user

Structured input data in a step Data table Creating a user with multiple fields

Prefer Scenario Outline over multiple near-identical Scenario blocks. Use Background sparingly — only for truly shared preconditions, not convenience.

Step Reuse Policy (FR-0KTg-012)

Before creating any step definitions, read bdd/steps/INDEX.md to identify existing reusable patterns. For each step in the generated feature file:

• Search INDEX.md for a matching pattern (exact or parameterized).

• If match exists → reuse. Do not create a duplicate.

• If no match → create a new step definition.

Step File Placement

Category File When to use

Common common_steps.[ext]

Generic steps reusable across domains: login, navigation, time manipulation, basic CRUD

API api_steps.[ext]

HTTP request/response steps: sending requests, checking status codes, validating response bodies

Database db_steps.[ext]

Database assertion steps: checking row counts, verifying column values, seeding test data

Domain-specific {domain}_steps.[ext]

Steps unique to a business domain: billing calculations, notification rules, auth policies

If the target step file exists, append new definitions. If not, create it using the matching template from templates/ .

Step Definition Rules (FR-0KTg-020)

Every new step definition must include:

• A docstring (Python) or doc comment (Go, TypeScript) describing what the step does

• Parameter descriptions with types in the docstring

• A TODO: implement step placeholder body (not an empty body)

Index Maintenance Rules (FR-0KTg-029)

Both bdd/features/INDEX.md and bdd/steps/INDEX.md must be updated together after any generation. Never leave partial index state — updating one without the other could introduce drift.

Reference Files

File Description

references/scaffold.md Scaffold creation and index validation procedure (Steps 2a-2h)

references/exploration.md Codebase exploration for generic feature names (Steps 2-exp-a to 2-exp-e)

references/generation.md Feature file and step definition generation (Steps 3-pre to 3d)

templates/ Individual file templates (INDEX.md, world modules, features, steps)

references/splitting.md Feature file splitting when scenario count exceeds 15 (Step 3e)