you are here

What is Spec Driven Development

Disclaimer: this is a living document while this approach is tested and made more concrete

Over the past couple months I have been talking about something I’ve called Spec Driven Development, or rather a software development ideal where your application is built in two distinct phases:

  • The creation of a Spec
  • Development of code to match the Spec

Example of the two stages utilizing MuleSoft’s API Contract Design Cycle:

Spec Driven Development is not to be confused with Document Driven Development, as you are not creating a full document with behaviors and prototypes, but rather a concise spec that can be used to describe your application’s interactions in a pragmatic way.

It is also not Behavior or Test Driven as the definition of success with Spec Driven Development, while incorporating expected behaviors, is that the application structure and interface matches the spec verbatim.  In other words, the Spec is a blue print for your application, detailing how the user interacts with it, rather than just expected behaviors/ results.

Spec Driven Development is best used with strict types of applications, for example when building a REST API due to the numerous user expectations and constraints.  However, Spec Driven Development does not need to be restricted to API development.

In order to be successful with Spec Driven Development, the Spec must be:

  1. Standardized – Use of a standardized spec related to the type of application you are building
  2. Consistent – The spec should remain consistent throughout in operations, utilizing consistent design patterns.
  3. Tested – Agile development of the spec, incorporating repeated user feedback with a long-term focus in mind
  4. Concrete – The creation of a complete, foundational spec to be used for your application
  5. Immutable – Coding to the Spec without deviation
  6. Persistent – The spec is not changed without strong reason and careful testing


Spec Driven Development encourages the use of a standardized format applicable to the type of application you are building.  In the case of building an API for example, the following specs would be considered standard, or common among the industry: RAML, Swagger, API Blueprint, IO Docs.

Utilizing a standard spec ensures easy portability among developers, while also ensuring that the spec your application relies on has been thoroughly tested by the community to ensure that it will meet both your short-term and long-term needs while maintaining consistency in its own format.


In developing your spec you should utilize pattern driven design as well as code reuse when possible to ensure that each aspect of your spec is consistent.  In the event of building an API, this would mean ensuing your resources are all formatted similarly and your methods all operate in a similar format – both in regards to the request and available responses.

The purpose of consistency is to avoid confusion in both the development, and use of your application as all aspects of the application work similarly providing the end user with the freedom to move seamlessly from one focus to another.


Spec Driven Development requires a strong, tested spec in order to build a reliable application.  This means that the spec has to be carefully crafted and then tested with both internal and external uses to ensure that it accomplishes its goals, and meets all parties needs.

The spec should be crafted, mocked/ prototyped, and tested to retrieve user feedback.  Once user feedback is received, the spec should be modified appropriately, mocked, and tested again- creating a continuous cycle until you have perfected the spec – or at the least eliminated a large majority of the design issues to ensure spec and application longevity.


The specification should be the very foundation of your application, or in essence the concrete foundation of the house you are building.  The spec should encompass all aspects of your application, providing a solid blueprint that your developers can code to.  The spec does not have to encompass future additions, but should have taken as many of them into consideration as possible.  However, there is nothing that relates to the spec that is coded outside of existing inside of the spec.


The spec is the blueprint for development and is unchangeable by code.  This means that at no time is the code to deviate from the spec, or to override the spec.  The spec is the ultimate authority of the application design, being the aspect that has been most thought-out and carefully designed and tested by real-world users.  It is important to realize that short-term coding implementations can be detrimental to an application’s longevity, and as such have no place in spec driven development.


All things evolve, and the application and spec are no different.  However, each evolution must be just as carefully thought out as the original foundation.  The spec can change, however each change must be justified, carefully evaluated, tested, and perfected.  In the event of development, if the spec is found to be not renderable, it is important to go back and correct the spec, re-engaging in user testing and validation, and then updating the code to match to ensure that your code is consistent with your spec while also ensuring that the necessary changes do not reduce the longevity of your application.

Advantages of Spec Driven Development

Spec Driven Development was designed to reduce the inefficiencies in many of today’s design methodologies in regards to highly constrained applications.  it does this by:

  • Providing a clear, concise plan for developers to build off of
  • Helping to ensure that your application meets best and standard practices
  • Injecting user testing at the very beginning of the application lifecycle to provide critical feedback on both usability and functionality
  • Forcing long-term thinking and planning to avoid backwards incompatibilities, while encouraging pattern based design to help reduce discrepancies in the consistency of the application
  • Allowing for parallel development of dependencies based on prototypes, expediting the ability to release to production (ie you can start building your mobile app based on the prototype before having completed the code necessary to make your API functional)
  • Enabling use of the open source communities and tools surrounding the spec (ie RAML, API Blueprint, Swagger can also be used for documentation, interaction, and SDK generation)

Share this Page:
Facebook Twitter Linkedin Reddit Tumblr Email

Leave a Reply

Your email address will not be published. Required fields are marked *