Tech & ToolingEmerging Pattern

Use TDD with Gherkin syntax to create living documentation that stays current because tests must pass

Q: How many founders have validated "use tdd with gherkin syntax to create living documentation that stays current because tests must pass"?

1 founder has proven this pattern works. Examples include David Heijl (Vist).

Write acceptance criteria in Gherkin syntax that become executable Cucumber/RSpec specs. Unlike traditional documentation that becomes outdated the moment it's written, test-driven specs stay current because they have to work. Test output reads like plain English documentation.

When to use

When building products where specs historically get outdated, or when working with AI coding agents that need clear specifications

Don't do this

Writing extensive traditional specs that become outdated immediately; treating tests and documentation as separate concerns

1 Founder Who Did This

Vistby David Heijl

As a product manager frustrated with specs getting outdated immediately, switched to Gherkin/Cucumber for acceptance criteria that become executable tests

Result:When wondering what code does, runs tests and literally reads the specs in the output—spec-driven development that stays current

Read full story →