bdd-specification

Files (1)

• SKILL.md

SKILL.md (first lines)

# BDD Specification

Act as a software architect who enforces Living Documentation through
Behaviour-Driven Development (BDD). For every feature, write a language-agnostic
Gherkin specification that describes business behaviour, and map each scenario to
at least one automated verification — regardless of whether the target language
supports a BDD framework natively.

A Gherkin scenario and a unit test sit at different abstraction levels: a
scenario describes observable business or system behaviour, while unit tests
verify its technical decomposition. Do not force a one-to-one scenario-to-unit-test
mapping. One scenario may need several supporting unit tests (boundaries, error
paths, persistence, events), and many legitimate unit tests do not justify a
separate business-readable scenario. Keep the feature files as Living
Documentation, not as technical test catalogues written in Gherkin.

This skill is guidance and reusable content only. Do not implement a runner or
add automation as part of using this skill. Treat AI-created specifications and
tests as proposed until a human reviewer accepts them.

Apply the repository contract hierarchy: this skill narrows `AGENTS.md`, and
`AGENTS.md` adapts `general-semantic-contracts.md`. Do not duplicate general
metadata, anchor, testing, or Docs-as-Code rules here unless the BDD workflow
needs a stricter rule.

This skill is the strict default for any change that adds or changes observable
behaviour — new features, behavioural enhancements, and behaviour-changing bug
fixes. `../architecture-impact/SKILL.md` invokes it when the behaviour change is
requested, and `../implement-issue-workflow/SKILL.md` invokes it at the latest
when the change is implemented. Specify the behaviour as Gherkin as early as
request or analysis time; the specification and its test bridge must exist by the
time the change is implemented. Use those skills for backlog, branching,
verification, and PR mechanics, and use this skill for the specification and its
test bridge.

The only way out is an explicit, recorded human waiver. Do not skip the
specification on your own judgement: relax it only when a human explicitly asks
for a lighter treatment, and record that decision and its rationale where the
project keeps such decisions (for example the issue, the pull request, or the
Q&A document). Pure refactorings do not add behaviour, so they need no new
scenarios, but they must keep the existing `.feature` specs and their bridged
tests passing.

## Required Reading

- `../references/bdd-writing-guide.md` before writing `.feature` files, choosing
  scenario names, or translating scenarios into test names.

## Core Workflow

Follow three steps: decide the framework, write the feature documentation, then
build the bridge into code.

### Step 1: Technology & Framework Decision

Analyze the project's tech stack and decide whether to use a native BDD framework
or a classic unit-test framework.

- **Native BDD available** (for example Python/`pytest-bdd` or `behave`,
  JS/TS/Cucumber, Java/Cucumber-JVM): use the native runner so `.feature` files
  execute directly against step definitions.
- **No native BDD, or a classic unit-test framework is preferred** (for example
  Ruby/Minitest, C#/xUnit, Go/`testing`): use the classic framework and apply
  the bridge rules in Step 3 to keep the specification coupled to the tests.

Prefer the framework the repository already uses. Do not introduce a new BDD
dependency when a classic framework is established; use the bridge instead.
Record the decision and its rationale where the project keeps such notes (for
example an ADR via `../adr/SKILL.md` when the choice is architecture-significant).

### Step 2: Documentation Duty (the Feature File)

Create a `.feature` file in Gherkin style for every feature. This file is the
long-lived, living project documentation, not a throwaway test artifact.

- Write scenarios declaratively, focused on business behaviour, not on UI
  mechanics or implementation detail.
- One feature per file; a clear `Feature:` intent line and focused `Scenario:`
  blocks with `Given` / `When` / `Then` steps.

#### Where to store feature files

A `.feature` file has a dual nature: it is an executable specification that the
test runner must discover, and it is long-lived documentation. Resolve the
tension by authoring it once and surfacing it into the docs, never by copying it.

- **Authoritative location: code-side, where the runner discovers it.** Use the
  project convention (for example `features/`, `tests/features/`, or the
  language's own convention such as `spec/features/`). An executable spec that
  the runner never runs rots and stops being trustworthy documentation, so
  runner discovery wins for the source-of-truth location.
- **Surface it as documentation with an AsciiDoc `include::`, do not copy it.**
  Gherkin is plain text, so include the `.feature` file into the architecture
  documentation as a source or literal block. This keeps a single source of
  truth: the runner executes it and the docs render it.
- **Choose the arc42 location by architectural relevance, not by default.** Not
  every scenario is an architecture-relevant runtime scenario. Use Chapter 6
  (Runtime View) when the scenario explains runtime collaboration between
  building blocks, Chapter 10 for quality-related behaviour, and
  requirement-oriented sections or references for functional acceptance
  behaviour. A scenario that carries no architectural significance may stay in
  `features/` and need not be surfaced into arc42 at all. Avoid turning
  Chapter 6 into a collection of validation and acceptance details.
- Do not move `.feature` files under `src/docs/` and point the runner at the docs
  tree; that couples runner configuration to the documentation layout and is more
  fragile than including the spec into the docs.
- When no convention exists yet, propose one and keep it consistent.

### Step 3: Technical Implementation & Naming Convention (the Bridge)

When implementing in test code, keep reviewer-verifiable traceability between the
documentation and the code. This bridge is a review convention, not build-time
enforcement: no CI check proves the link, so a reviewer must be able to confirm
it from stable identifiers or naming.

1. **Every scenario has at least one identifiable automated verification.**
   Prefer a one-to-one mapping to an acceptance, component, or use-case test
   where practical. A scenario may instead map to a test class, a nested test
   group, or several supporting tests. Supporting unit tests that exist only to

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit