Spec‑Driven Development in Practice: BDD, Gherkin & Living Documentation

Part 2 of 3 — Moving from “writing specs” to “running specs”

Part 1: Spec-Driven Development: A Gentle, Practical Guide for Beginners

If Part 1 was about learning to think before you type, Part 2 is about making that thinking executable.

Let me be honest with you.

When I first heard “Behavior-Driven Development,” I thought it was one of those buzzwords that consultants throw around to justify their day rate. Another acronym. Another framework to learn. Another reason to rewrite the wiki.

I was wrong.

BDD turned out to be the thing that finally made my specs mean something — not just to me, not just to developers, but to everyone on the team. Including the stakeholders who never open an IDE in their lives.

This is what Part 2 is about. Not just writing specs. Making them run.

A Quick Recap (For Those Who Jumped Straight Here)

In Part 1, we talked about Spec-Driven Development — the practice of writing a clear, agreed-upon specification before writing a single line of code. The core idea is simple: if you don’t know exactly what you’re building, you’re going to build the wrong thing.

But Part 1 left us with specs that lived in documents. Google Docs. Confluence. Notion. Or worse — emails.

The problem with specs in documents? They go stale. The code moves forward, the document doesn’t, and six months later nobody trusts either one.

Part 2 fixes that.

So, What Exactly Is BDD?

BDD stands for Behavior-Driven Development. Think of it as the natural next step after SDD.

• SDD says: Write the spec first.
• BDD says: Make the spec executable.

That’s it. That’s the relationship.

With BDD, you write your specifications in a format that both humans and machines can understand. Then a BDD framework (like Cucumber, Behave, or SpecFlow) reads those specs and runs them as tests.

The result?

• Your spec becomes your test.
• Your test becomes your documentation.
• Your documentation is never out of date.

That feedback loop is genuinely powerful once you feel it working.

Gherkin: The Language of Executable Specs

Here’s where people sometimes get nervous. “A new language? Great.”

Relax. Gherkin is not a programming language. It’s barely even a language. It’s closer to a template. A structured way of writing requirements that happens to be machine-readable.

Gherkin uses just a handful of keywords

Turning Gherkin into Living Documentation

BDD tools generate beautiful HTML reports automatically. These reports show:

• All features
• All scenarios
• All steps
• Which ones passed
• Which ones failed

Example: Say you’re building a banking app and you need to spec out the money transfer feature. Here’s what that looks like in Gherkin:

Now imagine handing this to your product manager, your QA engineer, and your backend developer. All three of them will understand it. All three will agree or disagree with it in plain language. No code review needed. No technical translation required.

Step-by-Step: How to Use BDD in Real Life

Step 1 — Write the Feature File : Create a file called money_transfer.feature and drop in your Gherkin scenarios. This file lives alongside your code in version control. It's not in Confluence. It's not in a Google Doc. It's in your repo, next to the code it describes.

Step 2 — Implement Step Definitions : Each line of Gherkin needs to be mapped to actual code. These mappings are called step definitions. Here’s an example in Java with Cucumber:

Each method handles one Gherkin step. The {int} in the pattern automatically captures the number from the scenario. It's surprisingly elegant.

For Python users, Behave uses almost identical syntax:

Step 3 — Run the Tests : You run your BDD tool (Cucumber, Behave, SpecFlow — whatever fits your stack) and it walks through every scenario, line by line.

• Green means the code behaves as the spec says it should.
• Red means something is off — either the code is wrong, or the spec needs to change.

That red/green feedback is immediate and unambiguous. No interpretation required.

Step 4 — Publish the Living Documentation : BDD tools can generate beautiful HTML reports automatically. These reports list every feature, every scenario, every step — with pass/fail status clearly marked.

Share that report with your team. Pin it to your internal dashboard. Send it to stakeholders before a sprint review.

This is your living documentation — always accurate, always current, because it’s generated directly from the tests that just ran.

Cucumber HTML report

Why BDD Makes SDD Even Stronger

SDD gives you clarity. BDD gives you verification.

Without BDD, spec is a promise. With BDD, spec is a contract — one that’s enforced by your test suite every time the code runs.

Here’s how each role benefits:

• Developers know exactly what behavior to implement
• QA engineers know what scenarios are already covered and what isn’t
• Product managers can see feature status without reading code
• Stakeholders see working demos grounded in agreed-upon specs
• New team members can understand what a system does by reading the feature files

That’s cross-functional alignment without a single alignment meeting.

Common Mistakes (I am not perfect and I do make mistakes )

1. Writing too many scenarios : Don’t try to cover every edge case in Gherkin. Scenarios should represent meaningful business behaviors, not every permutation of input. When in doubt, ask: “Would a stakeholder care about this scenario?” If no, it probably belongs in a unit test, not a feature file.

2. Writing UI-level scenarios : This is a big one. Gherkin scenarios should describe behavior, not clicks.

❌ When the user clicks the "Submit" button ✅ When the user submits the transfer request

The first locks your spec to a UI implementation. The second survives a redesign.

3. Using technical language : If your product manager can’t read it, rewrite it. Gherkin is for communication first, automation second.

❌ Given the POST request to /accounts/transfer returns HTTP 200 ✅ Given the transfer was processed successfully

4. Treating Gherkin like code : Gherkin is a conversation tool. If you’re optimizing for DRY principles and abstracting step parameters, you’ve probably gone too far. Write it like you’d say it to a teammate.

Tools to Know

Here’s a quick map of the ecosystem, since different teams use different stacks:

All of them support Gherkin. All of them generate reports. All of them integrate with standard CI/CD pipelines. Pick the one that matches your stack and the workflow is essentially the same.

Remember ✨

Gherkin is for humans first, machines second.

👋 If this helped you, follow along for Part 3. Drop a comment below with your first Gherkin scenario — I’d love to see what you’re working on and lets learn together.

Part 1: Spec-Driven Development: A Gentle, Practical Guide for Beginners

Part 3: Collaborative Spec‑Driven Development: How Dev, QA & Product Build Together