There are two distinct problems hiding in every software project, and a team can be excellent at one while failing the other. Building the product right — making it correct, well-engineered, free of defects — is one problem. Building the right product — making the thing that actually solves the need — is another. You have to solve both, and they call for different practices. Specification by Example, the set of process patterns Gojko Adzic gathered under that name, is mostly aimed at the second.

Deriving scope from goals#

The central move I take from this body of work is to derive scope from GOALS rather than accepting a list of requirements as a settled solution.

When a stakeholder hands you a list of requirements, that list is usually a solution someone already designed in their head — and often not the best one. If you start from the goal instead ("reduce the time it takes a customer to reorder" rather than "add a reorder button to the account page"), you give the team room to find a better answer than the one that was guessed at up front.

A related discipline: resist specifying HOW when all the situation requires is WHAT. The example that anchors a specification should describe the behavior the business wants to see, not the mechanism. The moment your specifications start dictating implementation, they become brittle and they crowd out the engineers' judgment.

Living documentation#

When you capture those examples as executable specifications, something useful happens: they become living documentation. An authoritative, always-current description of what the system actually does — because if the description drifts from reality, the test fails and someone fixes one or the other.

This matters most when you need to change the system. Without that living documentation — without your tests — a large refactoring is a leap in the dark. You change the structure and you have no reliable way to tell whether you preserved the behavior that mattered. The tests are the net. This is the same reasoning behind so much of Extreme Programming's emphasis on testing.

Three emphases#

Teams adopt this idea with different centers of gravity, and it helps to know which one you are choosing.

• Acceptance-testing-centric (ATDD). The specs are framed as acceptance tests. This style helps a team that has many functional-quality problems — defects escaping, behavior nobody can pin down. The real pitfall: teams forget to design these tests to be easy to MODIFY. They write hundreds of acceptance tests, the product shifts, and now the test suite is a millstone instead of a safety net.
• Behavior-specification-centric (BDD). The specs read as descriptions of behavior. This style shines for explaining near-term delivery — what we are building this iteration, in language the whole team and the stakeholders share.
• Documentation-centric. Here the specs are valued first as the living reference for how the system behaves, with the executability serving to keep that reference honest.

Maintainability is the make-or-break#

The thing that determines whether any of this survives contact with a changing product is maintainability, and the key is to write specifications that reveal their underlying PURPOSE.

A specification that buries its intent under incidental detail — exact field names, click sequences, magic numbers — breaks every time the implementation twitches, and nobody can tell from reading it why it exists. A specification that states its purpose clearly tells a future engineer what is actually being protected, so when something changes they can update it deliberately instead of guessing. Design your specs to be modified, because they will be.

How to actually get it adopted#

A note on adoption, learned the slightly hard way: lead with QUALITY, not with process labels.

Walk into a team and say "let's adopt agile" or "let's do Specification by Example" and you invite resistance — you are asking people to sign up for a methodology, and methodologies feel like something being done to them. Say "let's improve quality" and you have something a team will rally around, because nobody is against better quality. Frame the conversation around the outcome people already want, and the practices follow naturally.

And there is an easy on-ramp: once a team understands TDD, executable specifications are a short step. They are simply tests for business functionality rather than for units of code. The team already believes in writing a failing test first and making it pass; you are just moving that habit up to the level of business behavior. Sold that way, it rarely meets the resistance that a process-branding pitch does.