View the full-size workflow diagram →

OpenSpec 1.0 is officially released.

In an earlier post, I wrote about how the OpenSpec workflow anchors development to specs as the source of truth, ensuring that what gets built stays aligned with what was intended. This spec-anchored approach has been central to OpenSpec from the beginning.

In this post, let us look at some of the major changes that come with the 1.0 release.

Explore Before You Build

One of the most significant additions is the Explore Mode. Before diving into implementation, you can now use OpenSpec to think through ideas which require more clarity, investigate problems, and clarify requirements.

Step-by-Step Generation

OpenSpec 1.0 introduces a more deliberate artifact creation process. Instead of generating everything at once, you can now step through each artifact such as proposal.md, design.md, etc. one at a time.

This step-by-step approach helps improve the review process as each artifact can be checked before the next one is generated.

Intent Verification

Before archiving a completed change, OpenSpec now includes a verification step. This checks that the implementation actually matches what was specified in the change artifacts. It’s a final checkpoint that catches any intent alignment issues.

Noteworthy mentions in 1.0 release

The config.yaml file in OpenSpec 1.0 looks really interesting.

Seamless Integrations

OpenSpec’s config system makes it straightforward to integrate with external tools. For example, you can connect OpenSpec with Linear using MCP to automatically sync issues and track progress. I had earlier achieved this by forking and modifying OpenSpec, that may not be necessary anymore.

Customizable Workflows

Beyond integrations, config.yaml lets you tailor the OpenSpec workflow to your team's needs.

Video Walkthrough

Originally published at https://intent-driven.dev on January 26, 2026.

OpenSpec Release 1.0 was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Before selecting a tool for Spec-Driven Development (SDD) it is good to get a bearing on our workflow and the level of rigor our project demands. This post intends to provide a practical way of thinking through which tool to use.

Context Engineering Approaches

Before we jump into Spec-Driven Development, itself let us quickly look at how it differs from “Plan Mode”. This is a question I often get asked and thought I will start with that first. There are two ways to look at Context Engineering.

Tactical (Plan-Mode)

What it is: Best for rapid problem-solving. We create a plan or to-do list to think through the solution, build it, and then discard the plan. The code is the only long-term asset. Now based on our preference for CLI vs IDE based tools, there are several choices. Here are some examples that I have used.

Tools:

• Claude Code (CLI): Plan mode creates temporary implementation plans
• Antigravity (IDE): Implementation plans that guide development. Even though the plan appears in your IDE window it is not part of your repo.

Strategic (Spec-Driven)

What it is: Here the specification is a first-class citizen. It is as important as the implementation itself. Maybe even more important in comparison to the code itself (Theoretically, we can generate the code all over again if we have the spec). These specs are persistent and version controlled or stored through other means.

Again here, based on our preference for CLI vs IDE based approaches we have several choices.

IDE

• Kiro

CLI

• OpenSpec
• SpecKit
• BMAD-Method

Other Considerations

1. Levels of “Spec-Driven”

Not all of the above tools handle the relationship between spec and code the same way.

Spec-First:

• Tools: Kiro, SpecKit
• Philosophy: The purpose of the spec is to articulate intent. Over time, the code and spec might not be aligned.

Spec-Anchored:

• Tool: OpenSpec
• Philosophy: In addition to articulating intent, the spec remains aligned at all times with the implementation.

For a deeper dive into the spec-anchored philosophy, see my LinkedIn post on Spec-Driven Development with OpenSpec: Source of Truth Specification.

2. Rigor vs. Speed

How many steps do you actually want to follow?

More rigor is not always better, it depends on how much groundwork we have already done. If we already have stories in our familiar tools like Linear, GitHub boards, Jira, etc. then maybe better to choose a tool that works with smaller features. If we want to think through a solution from an overall nebulous idea, BMAD may be necessary.

3. Legacy Code and Lock-in

Compatibility: Greenfield vs. Legacy

• Greenfield-friendly: Most tools work well with new projects where you can establish patterns from day one
• Legacy-specialized: OpenSpec claims to be specifically designed to handle the complexity of existing codebases (brownfield and 0 to 1 projects)

Exit Strategy: Portability and Lock-in Since most of us are evaluating these tools, it may be a good idea to see if the approach allows being able to switch from one tool to another without context loss when we switch spec formats.

Video Walkthrough

For a visual explanation of this decision framework and tool landscape, watch this walkthrough:

Conclusion

Better not to overthink it, start with the tool that feels most aligned with your workflow, and adjust as you learn what works for your team.

Want to dive deeper into spec-driven development practices? Explore the Knowledge Hub on https://intent-driven.dev for detailed guides on workflows, best practices, and OpenSpec.

Originally published at https://intent-driven.dev on December 26, 2025.

Which Spec-Driven Development Tool Should You Choose? was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

One of the most common ways to critique vibe coding is by pointing to technical limitations such as context length, token limits, or LLM “amnesia.” While those are real constraints, the deeper issue IMHO is the workflow.

In real life, we rarely expect a human counterpart to take a single-line request or a short PRD and return a perfectly working solution. We expect clarifying questions, intermediate artifacts, reviews, and course correction which can be expensive. Over time, engineering practices such as Behaviour-Driven Development emerged precisely to help teams articulate intent clearly before implementation by promoting better dialogue between stakeholders.

When working with AI coding agents, the same principle applies. If we cannot articulate our intent clearly to ourselves first, what eventually gets built will almost certainly deviate from what we originally wanted, regardless of how capable the model is.

This article looks at the fundamental workflow differences between vibe coding and spec-driven development, and how those workflows either amplify or reduce intent-to-implementation deviation.

The Vibe Coding Lifecycle

In a typical vibe coding flow, we describe what we want in a single prompt, review the generated code, provide feedback, and iterate until we are satisfied. It is fast, flexible, and requires very little upfront planning.

How Vibe Coding Works

The vibe coding workflow usually follows a linear loop:

1. Single-line prompt describing what needs to be built
2. General-purpose agent that interprets the prompt and fills in gaps
3. Code generation based on those assumptions
4. Review and feedback from the human
5. Iteration using the updated prompt or follow-up instructions

This feels natural, especially because chat-based interfaces encourage getting something working quickly and using that output as the basis for further refinement. The workflow optimizes for speed and momentum.

Implicit Assumptions Accumulate

The core problem emerges as iterations progress.

Each prompt and correction focuses on the current concern. To satisfy new feedback, the agent often revises or overrides earlier decisions. Constraints that were previously implied or loosely stated are weakened or forgotten.

Initially, intent deviation may reduce as obvious gaps are fixed based on feedback. Over time, however, corrections become fragile. Changes in one area introduce regressions in another. The human ends up in a sustained negotiation loop with the agent, repeatedly restating intent in different ways to keep the output on track.

This is not a model failure, it is a workflow limitation where context is not managed effectively.

The Spec-Driven Development Workflow

Spec-driven development takes a fundamentally different approach. Instead of starting with implementation, it focuses on establishing clear intent before asking the agent to write code.

By breaking work into explicit phases with review gates, the spec-driven workflow makes intent articulation deliberate and verifiable, significantly reducing downstream deviation.

The Four Phases of Spec-Driven Development

Each tool may have a few more or a few less, however overall these aspects are usually covered.

Phase 1: What (Specify / Propose / Requirements)

This phase focuses on defining what needs to be built:

• Feature requirements and acceptance criteria
• User needs and business goals
• Scope, boundaries, and non-goals
• Success metriccs

Phase 2: How (Design / Plan)

Once intent is clear, the next phase addresses how it will be implemented:

• Architecture and technical approach
• Technology and pattern choices
• Data models, APIs, and interfaces
• Risks and dependencies

Phase 3: Task (Granular Steps with Checks)

With design approved, work is decomposed into concrete tasks:

• Small, verifiable work items
• Clear validation criteria per task
• Explicit dependencies and ordering
• Testing and verification strategy

At this point, task ordering and parallelization opportunities can be reviewed. Tasks may also be delegated to sub-agents, reducing context burden in the primary thread while keeping intent anchored.

Phase 4: Build (Implementation)

Only after intent, design, and tasks are validated does implementation begin:

• Tasks executed sequentially or in parallel
• Validation against acceptance criteria
• Automated tests run
• Implementation reviewed against specs

Output: Working code that matches documented intent.

Conversation Matters

Spec-Driven Development is sometimes criticized as an anti-pattern because it appears to conflict with “Working software over comprehensive documentation” from the Agile Manifesto. This criticism often stems from viewing specs as artifacts rather than as a mechanism for intent negotiation.

To give you an analogy, Behaviour-Driven Development was never about Gherkin syntax for its own sake. It was about enabling collaboration between business and technology through structured conversation. That aligns with “Collaboration over contract negotiation.”

Similarly, SDD facilitates structured conversation between humans and coding agents. Specs and plans are not the goal, they are scaffolding that helps clarify and stabilize intent.

Tooling quality and verbosity vary, but the underlying purpose remains the same, ensuring that intent is explicit, reviewable, and durable across iterations.

Watch: Deeper Dive into Vibe Coding vs Spec-Driven Development

For a comprehensive walkthrough of these workflows and their practical implications, watch this video:

Conclusion

Vibe coding and spec-driven development represent two fundamentally different philosophies for working with AI coding agents.

Vibe coding optimizes for speed. It favors rapid iteration, minimal planning, and flexibility. It works well for prototypes, scripts, and exploratory work.

Spec-driven development optimizes for intent alignment. It emphasizes clarity, validation, and verifiable outcomes. This makes it better suited for production systems, team environments, and long-lived codebases, and, over time, even for smaller prototypes.

The critical differentiator is intent management.

Vibe coding accepts deviation as a cost of speed. Spec-driven development reduces deviation by introducing structure, review gates, and explicit intent articulation.

If intent matters beyond the next prompt, structure wins.

Ready to Learn More?

Explore our Knowledge Hub for in-depth guides on:

• Spec-Driven Development fundamentals
• OpenSpec framework
• Workflow best practices
• Tool ecosystem

Related viewing: No Vibes Allowed: Solving Hard Problems in Complex Codebases — Dex Horthy, HumanLayer

Originally published on intent-driven.dev

Learn more about Spec-Driven Development on intent-driven.dev.

Vibe Coding vs Spec-Driven Development was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

In one of my previous articles I mentioned that I have been experimenting with several Spec-Driven Development (SDD) tools, both to evaluate them and to use them in my own work. Among these, OpenSpec has increasingly become one of my preferred SDD tools. It introduces an interesting idea of having a single top level “source of truth” spec. In this article I will look at the workflow, advantages of the “source of truth” spec and other observations about OpenSpec.

OpenSpec — Change Workflow

Why the “Source of Truth” Spec Matters?

To understand its importance, it helps to reflect on some of the difficulties I faced with tools like Spec-Kit and Kiro in this context.

Without a top-level spec, feature-level specs are often fragmented across subfolders within the “specs” directory. This fragmentation introduces below issues:

1. Fragmented Understanding — The overall intent of the system becomes scattered across multiple files, making it difficult to maintain a cohesive picture.
2. Evolving specs — There are several questions and confusions that seem to arise in the context of spec evolution which has been well discussed here — Evolving specs #152.
3. Unintended Interactions — Every new feature added risks unintentionally affecting existing behaviour, since there is no unified view for validation. (I had attempted to address this to an extent with an optional “/cross-feature” command to analyse across features).

Originally published on intent-driven.dev.

Spec-Driven Development: OpenSpec was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

We often need to mock APIs (both internal and external) to isolate the system under test or development so that we can make progress independent of dependencies. WireMock is a great tool if your goal is to just mock APIs. However API mocking is only effective if the mocks are truly representative of the provider / services they are emulating. Deviations between mocks and providers can lead to integration issues much later in the development cycle. In order to avoid such issues it is important to keep in mind that selecting an API mocking tool is not an isolated decision. It has to be in line with your overall microservices development, testing and deployment goals.

WireMock is an API Mocking tool and Specmatic is a Contract Driven Development tool that leverages API mocking (Smart Mocks) to identify contract compatibility issues in Consumers of an API. So this is not an apples to apples comparison. We are only going to look at a subset of capabilities where there are overlaps between Specmatic and WireMock. However if you believe we have missed any aspects in this comparison, please do leave us a comment.

Here is my blog post comparing Specmatic with WireMock in detail.

Comparison: Specmatic vs WireMock - Specmatic

Specmatic vs WireMock was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

The key point here being API Specifications (such as OpenApi) themselves are leveraged as API Contracts with Specmatic. This is significantly different from Consumer Driven Contract Testing (Example: Pact.io) where the API Contracts and API Specifications serve separate purposes. This difference in approach (CDD vs Consumer Driven Contract Testing, etc.) is quite a deep topic. So we put together a comprehensive comparison chart.

Here is my blog post comparing Specmatic with Pact.io and Pactflow.io in detail.

Comparison: Specmatic vs Pact.io and Pactflow.io - Specmatic

Specmatic vs Pact and Pactflow was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

This post expands on the concepts I had covered in my earlier post about “Refactoring to Railway Oriented Programming”. Other than being a great approach to handling errors, in my experience, Railway Oriented Programming also serves as a great use case for explaining the need for Monads to first timers. While understanding Monads is hard enough, trying to explain it to others is a lot harder. However, this post is not a tutorial on Monads, instead it just explains the concepts in the context of ROP.

We will be leveraging Arrow-kt library and specifically the Either monad, FlatMap and Fold operators to refactor below snippet.

Step-1: The “Either” Monad

All we are going to do in this step is to extract the code in each “if ” condition to methods. More importantly these methods should return an “Either.Right” or “Either.Left”. Right is returned on success and Left is returned on Error.

fun matchUrl(anotherRequest: HttpRequest): Either<String, HttpRequest> {
    if (this.url != anotherRequest.url)
        return Either.Left("URL did not match. ${this.url} not equal to ${anotherRequest.url}")
    return Either.Right(anotherRequest)
}

fun matchMethod(anotherRequest: HttpRequest): Either<String, HttpRequest> {
    if (this.method != anotherRequest.method)
        return Either.Left("Method did not match. ${this.method} not equal to ${anotherRequest.method}")
    return Either.Right(anotherRequest)
}

fun matchBody(anotherRequest: HttpRequest): Either<String, HttpRequest> {
    if (this.body != anotherRequest.body)
        return Either.Left("Body did not match. ${this.method} not equal to ${anotherRequest.method}")
    return Either.Right(anotherRequest)
}

Step-2: The “FlatMap” Operator

Either is a Monad, or in over simplified terms a wrapper around raw values that allows a bind transformation. Let us understand this in detail.

1. Wrapper around raw values. Example: In the above step, we are wrapping the error message String in “Either.Left” and the HttpRequest in “Either.Right” respectively.
2. Bind transformation. The bind operator that we will be leveraging on Either monad is FlatMap. FlatMap takes a function as an argument and applies it on the wrapped value of the Either Monad and returns a Monad. The function that FlatMap takes as the argument, should accept the unwrapped value of the the Either Monad as the argument and return another Monad. Example: We have written such functions in Step 1.

Why all these rules? Because now we will be able to sequence method calls as shown below.

matchUrl(request).flatMap { matchBody(it) }.flatMap { match... }...

The matchUrl method returns an Either monad. The flatMap applies matchBody to the unwrapped value (“it”) if the Either monad. Now matchBody returns and Either monad and flatMap applies the next function and so on.

This all sounds good when the matchUrl returns “Either.Right” and then matchBody also returns an “Either.Right” and so on because the wrapped value in “Either.Right” is the HttpRequest which each of the subsequent functions take as argument. However what if matchUrl returns “Eight.Left”? The wrapped value is a String. What do we do?

Either Monad is “Right-Biased”

What is right bias? I earlier mentioned that the bind operator applies the function on the wrapped value. However, Either can have two possible values (Classified as Sum Type in ADT). Which value should we apply the function on? This is why flatMap in Either only applies the function on the Right.

What about the errors? We still need to stop the execution of other functions when a function returns error. On Left, the flatMap in Either short circuits the execution and does not continue. Example: When matchUrl returns Left, matchMethod and matchBody are not invoked.

I now need to be able to extract the error message when there is a problem and I want the HttpRequest when it is successfully matched.

This is where “Fold” operator is necessary. “Either.Fold” takes two functions, ifLeft to apply when the overall result is “Either.Left”, ifRight to apply when the overall result is “Either.Right”. It is also able to access the wrapped value, error String when “Either.Left” and HttpRequest when “Either.Right”.

With flatMap and fold we can now solve this refactoring.

private fun matchAnotherRequest(anotherRequest: HttpRequest) =
    matchUrl(anotherRequest).flatMap {
        matchMethod(it)
    }.flatMap {
        matchBody(it)
    }.fold({ Failure(it) }, { Success(it) })

Step-3: Extracting “then” and “handleError”

This step is optional. To improve readability I have formatted above code to keep all the method names on the left. All the machinery has been moved to the right.

matchUrl(anotherRequest)    .flatMap {
matchMethod(it)             }.flatMap {
matchBody(it)               }.fold(
                                { Failure(it) }, { Success(it) }
                            )

This code on the right can be moved to its own place. The flatmap related code can move to “then” and fold related code can move to “handleError”.

Putting it all together.

The code is available on GitHub.

Related Reading List:

1. Kotlin Functors, Applicatives, And Monads in Pictures
2. Monoids without Tears

Refactoring if-else: Either and FlatMap was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Procedural code can become hard to read, hard to test and more importantly hard to maintain. Sometimes error conditions and “not so happy path”s tend to govern the codebase to a large extent. We are left searching for the happy path in such applications. The usual approach I may have taken to refactoring long and highly conditional code would be to go with OOP to decompose it into classes and leverage polymorphism or patterns to remove if conditions. However, are there other approaches?

Railway Oriented Programming (highly recommended article) is an approach that applies functional programming techniques to keep code focused on the happy path without sacrificing error handling. This post is about the steps I took to refactor procedural code to functional paradigm.

It may not help to show procedural code and directly jump to the functional equivalent. What will be interesting is to trace the steps we need to take to refactor our code. So we will be going over each incremental step to refactor a method written in procedural style to ROP.

This post assumes little to no Functional Programming knowledge. We will only briefly touch function composition.

Sample Problem

Requirement: Write a “matches” function in HttpRequest which allows us to verify if it matches another instance.

1. Input: HttpRequest A and Http Request B
2. Output: Whether A and B match and if they do not match, return error message that mentions which part did not match.

The request parts should be matched in the order given below

matchUrl -> matchMethod -> matchBody

Example: If the method did not match, it should return below error immediately. The body should not be matched.

Method did not match. GET not equal to POST

If everything matches we should get a success result.

Procedural

Good old procedural code with a generous serving of “if” conditions.

Observations

1. Even with the “guard clause” style programming the error handling code is becoming quite a distraction.
2. At this point it takes some time and effort to glean out the happy path of this code which we mentioned earlier.
3. Such code easily decays into chaos if we need to add exception handling and more if conditions.

Refactoring to ROP

Step 1: Method Extraction

The code is currently just a long list of “if”conditions. Let us start by extracting methods that embody major parts of this code, matching url, matching method and matching body.

Observations

While this code looks a little nicer, it is hardly a picture of the happy path.

1. The when blocks are more or less just if conditions. We are also having to check the result of each step.
2. Repetition of returning on Failure.

Step 2: Setting up the pipeline

If you stare at the code long enough, you would have noticed that all these functions (matchUrl, matchMethod, matchBody) are very similar in what they accept as parameters and what they return as result.

1. Argument: HttpRequest
2. Return: Result.Success or Failure

We will be able to build a pipeline of methods if we return the HttpRequest on Success so that it can be passed as argument to the next method.

So going by this requirement (highlighted in bold) we need to make matchUrl, matchMethod etc. return the HttpRequest when the matching is successful, so that we can pass it to the next function.

Observations

The code is hard to read because we have to deal with “return on failure”. The HttpRequest inside Success has to be extracted and passed to next method.

Step 3: Extracting the Error Handling

We need a way to extract “return on failure” and on success, the code that extracts HttpRequest from Result.Success to a separate function to avoid repeating ourselves.

Explanation

1. “then” is handling “return on Failure” — In line number 9 when the result is Success, we are calling “f” with this.message (HttpRequest). Here “f” is function that needs to be called next. Example: matchMethod is the “f” to the result of matchUrl. On error we just wrap the errorMessage in a Failure and return.
2. “pipeTo” is starting the series of functions by passing the Http request to matchUrl. To begin the pipe we call pipeTo which wraps the “anotherHttpRequest” as a Success and sends it to “then”. “then” realises that this is a Success, extracts the httpRequest inside the Success and calls matchUrl with it.
3. “error” is called when any of the functions matchUrl, matchMethod or matchBody (these functions can be thought of as junctions) return Failure. This behaves like the switch in the railway track and immediately moves execution to error when any of the junctions return Failure.

Kotlin infix helps us call the functions without “.” or parentheses.

Recap

1. Method Extraction — extract major code sections as functions
2. Setting up the pipeline — refactor these functions to return the parameter that they take in as input
3. Extracting the Error Handling — compose these functions such that error handling is extracted to the ROP code

There are more ROP constructs that you can experiment with once you have got the basics.

The code is available on GitHub.

Railway Oriented Programming was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

If we already have a mature Blue Green deployment setup, it is better to stick with it. However if we are going from having downtime based deployments to zero downtime deployment then it may be important to consider below points before you decide if Blue-Green is the right fit.

Cost

It is expensive to maintain two complete production environments. In its most basic version your infrastructure cost is double.

We can save cost by standing up green infrastructure just in time for a release and then tear down the blue after you switch to green. If you can do this you will also avoid Snowflake servers in the process. However consider additional infra automation cost.

An application has to be loosing significant business during downtimes to justify the cost.

Zero downtime

It depends. Even under the best scenarios, we will only have read availability. In any OLTP system we have to put the application in read only mode for some time to allow data to migrate over to green infrastructure before we can commence testing and then switch.

So technically it is a good idea to still plan a release when there is low traffic. Sometimes this may not sit well with business stakeholders when there is a blip in availability after all the spending.

Database

Strictly speaking we need to have two Database instances, a blue and a green. Even here we have put the application in readonly mode as mentioned above. There are some teams that perform Blue-Green deployments with a single logical database unit. In these cases we may even have to take a write availability downtime when we are applying DDLs on the shared DB.

Rollback

This can happen. Not all verifications result in a green signal to switch. Any errors caught in the verification phase is still good. You will not have accumulated any data or exposed your features to users. Just call off switching.

However once we switch to Green instances, then the switch back to the Blue environment may not be as simple as it appears.

Any data accumulated in the new release should be retained even after the flip. Also after a rollback when we deploy another release with the fixes this data that was collected by the erroneous release may need some correction.

In such scenarios, Roll-forward (Deploy another release with the fixes to Blue environment and switch over. Even if you cannot fix it, disable any broken features and cut a release) may be a better option.

In a Monolithic application or an application with a small number of Monolithic services, we usually have to stick with a uniform deployment strategy and have to think long and hard to choose the best fit.

With MicroServices, just like how we can choose language and stack for each service, we can also choose deployment strategies. Expensive strategies such as Blue-Green can be reserved for critical services. Less important services can still take a downtime and deploy.

Features which need to be released based on user cohorts can go through Canary releases. We can limit sticky sessions only to those services.

Rolling deployments are handy when you may want to deploy without any perceived downtime in a cost effective manner.

Blue-Green Deployment Nuances was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.

As a Developer, it is useful to have a repertoire of metaphors to better articulate our thoughts. This post is about a parallel in supply chain management I thought was useful to me in explaining my approach to implementing features both to myself and to others.

At a high level there are two ways you could implement a feature.

Inside Out/Backend First approach — Begin with database design. And then the backend classes (read domain) and services. UI is usually the last bit to get built.

Outside In/UI first approach — Like the name suggests, we start with UI, then build the APIs and then the DB schema.

This can look like a matter of preference at the surface. However we can try and explain which approach is better with some theoretical backing.

Let us look at how each approach sequences the tasks.

Inside Out/Database First approach

1. Database — Build schema based on the feature.
2. Domain — Build abstraction over schema
3. Services — Build functionality on domain
4. API — Expose functionality
5. UI- Build UI with API

This is typical of a “Push Strategy” where we forecast demand (read demand as in “Demand and Supply”). The demand here being what the UI needs.

Outside In/UI first approach

1. UI — Build UI with API stub
2. API — Build API that satisfies the stub in above step. API itself now depends on Stubbed out Services.
3. Services — Build Services that satisfy the stub in above step. Stub out Domain and DB
4. Domain and DB — Build Domain and DB to satisfy the stub in above step

This is a “Pull Strategy” where we generate demand. See how UI creates the demand for what it needs from the API. And the API does just enough to satisfy the demand of the UI.

Push vs Pull

A complete comparison is out of scope of this post.

In short, push strategy is suitable when the problem at hand is well known and so is easily predictable. If you have already built the same feature a 100 times over, you have historical data and you know exactly what fields to include in the DB, what domain objects are involved etc. However this is hardly the case in Software. If you are building a feature more than twice, you extract a re-usable component.

Pull strategy is suitable when there is no historical data. So prediction errors can be large. UX is evolving fast and the experiences we are building requires a complete re-thinking of how we build backends.

Inventory and shortage

Inside Out approach, as already mentioned requires us to forecast/predict what we will need. For example: We are architecting the DB schema to fit the overall feature at a point in time when we have not built the UI.

With no historical data, forecasting errors can occur.

1. Shortage: The schema does have all the necessary fields the UI needs. This leads to rework. While rework is bad, shortage is a visible problem and we know how much time and effort was wasted. What is worse is how we usually handle shortage.
2. Inventory: To overcompensate shortage scenario we may include additional fields in the schema (Overproduction). So when UI does not consume it, there will be inventory or dead code. Inventory in manufacturing actually consumes warehouse space. Since that is visible and measurable it is monitored closely. In Software, inventory problem is not as visible as shortage. Dead code does not take up physical space, it only consumes valuable cognitive space in the Developers mind. So there may not be a measurable loss. Only an inkling that we are lugging some unnecessary weight.

I personally prefer “Outside In” approach. Starting with components that are close to end consumer helps us build features with minimum design errors. This goes for “API First” approach also. While being API Centric is good, it does not mean we design APIs in a void without actual demand. If an API has more than one client, they can all generate the demand.

With network style architecture like MicroServices, it is easier to go with “Outside In” approach to trace changes.

I have only scratched the surface of Push and Pull strategies in this post to justify my preference of approaching feature implementation. Once you get past the initial theory this topic can get immersive.

Inside Out vs Outside In was originally published in polarizertech on Medium, where people are continuing the conversation by highlighting and responding to this story.