DEV Community: A. Rahman Bishal

Starting with Spec-Driven Development: Spec first, Prompt later.

A. Rahman Bishal — Wed, 01 Jul 2026 12:31:57 +0000

Bringing the ideas I've been thinking about for months into life has never been easier, thanks to AI agents. The basic intuition is—give it a prompt, it builds the whole feature, the result looks good. Done. It takes only minutes to build the same thing that would've taken hours otherwise.
Yes, I know, everyone's doing that. Right?
The reason I'm opening like this is to point out what happened afterwards.
I tried to use the search bar, and it fired a request on every keystroke.
Wait, what? I didn't do that. Of course I'd add a debounce here. But the agent didn't. Why? I didn't ask it to. I said—build me a search bar, and it built me one that works; but I didn't say exactly what I wanted.
Also, I noticed that the search button changes color on hover, but I'd already told it not to do that. The agent forgot, it hallucinated. What's missing then?
What was missing was I did not provide the agent with the exact decisions to work with the feature; or did not provide a proper reference point to fallback to, to remediate the hallucination. In other words, I did not provide it with a proper spec. Hence, it took the hidden decisions itself; even though it pulled the feature off. This is the core problem that Spec-Driven Development (SDD) solves.

The Hidden Product Decisions Your AI Agent Is Making For You

Here's what happens when you describe something to an AI agent and it generates code: lots of decisions get made. Let's take the search bar implementation as an example. Does the filtering happen on the client or the server? Does the URL update so results are shareable? What does an empty query show? Everything, or nothing?
I tend to miss nitty-gritty details while reviewing tons of AI generated code in a short amount of time. The code works, the UI looks right, I move on… Every one of those is a decision that belongs to my product. If I don't make the decisions consciously, the agent takes them based on whatever pattern shows up most often in its training data.
Take that search filter. Left to its devices the AI gives you something like this:

onChange={(e) => fetchResults(e.target.value)}
const filtered = results.filter(item =>
  item.name.includes(query) && activeCategory === item.category
)
if (!query) return <div />

Looks fine. But AND logic might be wrong for my product. Maybe users expect OR. Return nothing on a query might be backwards from what my users need. That onChange is silently hitting my backend on every keystroke, firing off requests and abandoning them mid-flight.
The agent did nothing except following the conventions it had in its training data. Convention just wasn't the answer for my specific situation and I never got the chance to weigh in.
I used to think the fix was reviewing AI output carefully. But it doesn't always work. The problem was that by the time I was reviewing anything the decisions were already buried in code.

What a spec is, and what it isn't

"Write a spec first" can be inferred as a post-it-note to a 30-page PRD. Let me be more concrete.
It's a markdown file. One file, written before I open my editor, that answers every behavioral question I can think of. What does the component render in each state? What interactions trigger what behavior? What happens at the edges? Not aspirational, not "we'll figure this out later." Decided.
If you've done Behavior-Driven Development (BDD), a practice that defines feature behavior in plain language before writing any implementation, this is the same instinct with the tooling stripped away. BDD got the philosophy right, but the problem was it required maintaining a whole parallel infrastructure that most teams abandoned quietly after six months. A markdown file that an AI can read gets you the same thing without any of that overhead.
It's not a new idea either. GitHub shipped a tool called spec-kit built specifically for this workflow in 2025. There's a heavier version too—machine-readable specs in OpenAPI or JSON Schema, where the spec itself generates tests and mocks automatically, but that's a real tooling investment. A markdown table gets you most of the benefit in twenty minutes, which is where I'd start.
But the tooling isn't the interesting part. The interesting part is what happens when you sit down and try to write the spec.
You'll get maybe two rows into your behavior table and hit a question you've never consciously asked yourself. What does "no results" look like? A message, an illustration, or nothing? If the user types while a request is in flight, do I cancel the old one or wait? Can users share a filtered URL with a teammate, or do filters live only in component state? Who owns this file when requirements change?
That said, I must warn that a spec is only valuable if it stays current. If it drifts from what the code actually does, it becomes something worse than no spec—it's documentation that confidently lies.

How SDD Differs From Test-Driven Development (TDD)

If you write tests first, this fits naturally. Test-Driven Development (TDD)—the practice of writing failing tests before writing the code that makes them pass, makes you consistent. It doesn't make you right. You can write a test that encodes the wrong behavior, and that test will defend that wrong behavior forever. Tests verify implementation, but what verifies the tests?
The spec. That's the decision source above the tests. If a test fails, fix the code. If the spec changes, you update the spec first, then the test, then the code. In that order, always. For me it doesn't feel like adding a layer on top of TDD—it is a source of truth that validates my tests.

The SDD Workflow in Practice: Spec, Tests, Implementation

Let's proceed with the same component—a search and filter UI for a product listing. The kind of thing I could prompt for without thinking.

Step 1: Defining the spec.

I opened a blank SPEC.md and started filling in scenarios. Just this forced me to make decisions I'd have otherwise skipped entirely.
The debounce question came up immediately—once I wrote "user types query" as a row, I had to fill in the behavior column. And that pulled in the next question: what if they type faster than the debounce window? What if a request is already in flight when the debounce fires?
The URL update requirement showed up because I asked myself: can a user share a filtered search with a friend? A product question, not a technical one. It wouldn't have occurred to me in a prompt.
Here's what the spec looked like when I was done:
SearchFilter component

State / Interaction	Behavior
Page loads, no query or filters	Show all results
User types query	Debounce 300ms, then fetch
User types while in-flight req	Cancel previous, start new debounce
Results returned	Replace list, update URL params
Query returns no results	Show "No results for [query]"
User clears query	Reset to all results immediately
User applies category filter	AND logic with active query, fetch now
Multiple filters active	AND logic—must match all
Request takes > 200ms	Show loading skeleton
Request fails	Inline error, preserve previous results

Case-insensitive matching
URL updates on every search (q= and category= params)—results are shareable
Sort order persists across filter changes

It's more rows than you'd expect for a "simple" component. That's kind of the point.

Step 2: Writing the tests.

Then I handed the spec to the agent: Read SPEC.md and write contract tests derived from it. Do not write any implementation yet.
The first pass came back testing things I hadn't specified. I pushed back. The second pass was better but still had invented behavior. The third pass was finally just the spec, nothing else.
This is worth mentioning: "read the spec and write tests" is not a magic prompt. The agent will add its own ideas. Treat the generated tests like a pull request—read every line.

The thing that breaks this workflow most often: Don't ask the agent to write both the spec and the tests from scratch. If you do, they'll agree with each other—and they might both be wrong. The AI bakes its assumptions into the spec, writes tests that enforce those assumptions, and you end up with a green test suite that proves nothing. This is why the spec has to come from you. The AI can help you think through edge cases, but the decisions have to be yours before the tests are written.

Step 3: Implementation.

Once the tests were genuinely spec-derived and failing, I prompted for implementation: read the spec, make the tests pass, add nothing that isn't in the spec. Green. Done. No guessing about debounce timing, no creative interpretation of empty state. The AI moved fast because it had something specific to work against.
One rule I kept the whole time: if a test fails after implementation, I fix the code. Never the test. The moment you change a test to make code pass, you've quietly changed the spec—and the whole point was that the spec is yours, not the AI's.

What SDD doesn't solve

SDD doesn't help if the spec is wrong. If I specify the wrong behavior, wrong status codes, wrong business logic, wrong security model—the implementation will faithfully build exactly that. A good spec process catches a lot of mistakes, but it's not magic. I still have to think carefully, and thinking carefully is a skill that takes practice.
Writing a good spec is also harder than it looks the first few times. The tendency is to write the happy path and stop. The edge cases, the error scenarios, the security implications—those take effort to surface.
And finally, SDD doesn't replace domain knowledge. If you don't understand the problem well enough, the spec will reflect that. Talking to users, understanding the system's context, knowing what actually matters—none of that gets skipped just because you wrote a spec first.
What SDD does is make your thinking visible before it becomes code. If the thinking is wrong, you find out faster and cheaper. If it's right, the rest of the process gets dramatically smoother.

Why AI Agents Make Spec-Driven Development More Critical Than Ever

SDD has always been good practice. Skipping the thinking used to be recoverable. You'd catch the missing case in code review, or QA, or production where you'd patch fast and learn something.
AI collapsed that timeline. The gap between "vague idea" and "running code" used to be hours of manual work, and somewhere in those hours you'd catch the questions you hadn't answered. Now it's seconds. The questions don't surface. They get buried under code that already passes tests.
SDD puts the thinking back at the front—before the prompts, before the code, before anything runs. Not because AI is bad at generating code. Because deciding what to build is still your job, and always will be.

Spec first. Prompt later.

Of Type and Interface: TypeScript Tales Ch. 01

A. Rahman Bishal — Wed, 19 Nov 2025 09:24:21 +0000

As you are reading this, I’m going to assume that you have a basic idea of what TypeScript is (which is basically JavaScript with syntax for types, according to the official docs). The purpose of this piece of writing is to discuss and look into the contrast between two commonly used constructs widely used in TypeScript: Type, and Interface.

In short, we use type as type aliases, which is, a name for any type. With the help of this, we can use the same type more than once and refer to it by a single name. On the other hand, interface, or interface declaration is basically another way to name an object type, actually a contract for a structure.

Now, they may not seem very similar by the definition. But here we are here, talking about what are the differences, and maybe trying to choose only one between type and interface, there should be some similarities that might make you confused, right?

In a bunch of cases, we can use type and interface interchangeably, and choose them freely. For object shapes and function signatures, both can work the same way. Let’s see an example. We will define objects and functions using both type and interface.

// defining object

type ObjectType = {
  name: string;
  author: number;
  fun(): void;
}

let thrillerBook: ObjectType;

interface ObjectInterface {
  name: string;
  author: number;
  fun(): void;
}

let fantasyBook: ObjectInterface;

// defining function

type FunctionType = (author: string) => string;

const getAcademicAuthor: FunctionType = (author) => {
  return `The academic author is ${author}`;
}

interface FunctionInterface {
  (author: string): string;
}

const getFictionAuthor: FunctionInterface = (author) => {
  return `The fiction author is ${author}`;
}

But yes, there are some obvious differences. Both of the keywords has some superpowers of their own, that the other one does not have. Let’s dive into those.

Superpowers of type

You can use type to represent anything from primitives, unions, tuples, and various complex type. But interface is mostly limited to defining shapes e. g. objects (as well as callable & constructable signatures).

type Title = string;                // primitive
type Published = string | number;   // union
type Binding = [string, string];    // tuples
type Spine = "flat" | "round";      // template literal
type ReadonlyBook = {
  readonly [K in keyof Book]: Book[K];
}                                   // mapped types

There are cases, when we must fall back to using type alias. We can roughly list them down like this:

Union types
Intersection types
Mapped types
Conditional types
Template literal types

These are some mere examples that interface does not support. It can be used for far more complex typing.

Superpowers of interface

While using interface for defining shapes or structure, there are several perks over using type. One of the major distinctions between type and interface is that type cannot be re-opened and redeclared, whereas interface can be. We call this declaration merging.

interface Book {
  title: string;
  author: string;
}

interface Book {
  published: number | string;
  reprint(): void;
}

// we can do this, no error.

Now, if we declare an object of type Book, it will have all the properties from both definitions, i. e. title, author, published, reprint(). But such is not the case for type.

type Movie = {
  title: string;
  released: number;
}

type Movie = {
  director: string;
}

// we cannot do this, TS will throw error.

To achieve the same with type, we must define a new type, and intersect the old one with it. Something like this:

type MovieWithDirector = Movie & {
  director: string;
}

But this method has a little overhead comparing to the one we saw earlier with declaration merging.

Even though declaration merging is one of the biggest superpowers of interface, it comes with a warning label—overusing merging can make the codebase harder to reason about.

Extensions and Implementations

An interface can extend both interface, and a type. Remember the Book interface and the Movie type we defined earlier in the example? Let’s extend those:

// interface extends another interface
interface PaperbackBook extends Book {
  binding: "paperback";
}

// interface extends another type alias
interface AnimatedMovie extends Movie {
  medium: string;
}

But remember, for an interface to be able to extend a type alias, it must be of an object type. For example, the below extension is not possible.

type Magic = number | string | [string, string] | number[];

interface Technology extends Magic {
    ...
}

// this will throw an error

The bottom line is, interfaces can extend other interfaces and sometimes type aliases if they define shapes. But the opposite is not possible in the same way. For that, we have to use intersection, as we did before to mock declaration merging with type aliases.

This scenario remains the same if a class tries to implement either of these. Let’s continue with the previously declared Book interface and Movie type.

// a class implements an interface
class FantasyBook implements Book {
  title = "The Hobbit";
  author = "John Ronald Reuel Tolkien";
  published = 1937;
  reprint() {
    console.log("reprint this again!");
  };
}

// a class implements a type alias
class AnimatedMovie implements Movie {
  title = "Tarzan";
  released = 1999;
  isFavouriteMovie = true; 
}

But, same as before, the type alias must define a shape i.e. an object. Otherwise, it cannot be implemented.

type NoShape = number | string | [string, string] | number[];

class Shape implements NoShape {
    ...
}

// this will throw an error

So, for its very nature, interface can be extended or implemented however we like, without any worries, as they define a shape. But as type alias is more of a broader toolbox for type definition, there are some limitations and cases where we need to be careful.

Now, the end is nigh, and I shall conclude this with a million dollar question:

Type or Interface, which one to use?

As both type and interface share some common use cases, the question is: which one to use?

Well, actually, there is no obvious choice. At the end, it really depends on you. But before deciding that, here are some facts:

TypeScript provides better and more focused error messages while working with interface.
Interface was supposed to be slightly more performant than type. But this difference is practically negligible in most cases (i. e. if the defined type is not very complex or deeply nested), specially in the later versions. After version 4.0, there is no measurable performance difference in real-world scenarios—stated publicly by the TypeScript Team.
Interface has closer mapping with objects by definition.

In case of common use cases, like defining an object, or writing a contract for a class, using interface seems more intuitive from object oriented perspective. But we have no way to avoid type in some cases also i. e. while working with union types or so.

The official TypeScript docs suggests to "Use interfaces until you need to use features from type aliases". This pretty much infers to “Use interfaces to define the shape of objects. Use type aliases for more advanced type composition.” For your convenience, I can provide a decision tree—

Use interface when:

You want declaration merging.
You want cleaner IntelliSense names.
You want the error messages to make more sense.

Use type when:

You need unions, intersections, mapped types, template literals.
You work with utility types (Partial, Pick, etc.).

But if you are still confused, just go with whichever you are comfortable with. But, it is recommended to be consistent on the choice. Choose the approach that better suits your style and keeps the code more readable and maintainable.

Keep in mind that, these are compile-time only constructs. After being compiled into JavaScript, no trace of type or interface remains. So choosing one or another does not affect runtime perfomance.

References

TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html

Playground Examples 1: https://tinyurl.com/4cwazrus

Playground Examples 2: https://tinyurl.com/4hu8ebsy

The Magical CSS Display Property: Contents!

A. Rahman Bishal — Tue, 18 Nov 2025 12:13:08 +0000

There are a bunch of display properties in CSS. If you don’t write CSS frequently, you might have missed a cool property that was introduced relatively recently, though it’s not that old either (started gaining support across major browsers around 2018). Well, I’m talking about display: contents.

What does contents do?

The HTML elements like div, span, etc. are wrapped by an invisible box around themselves where we can specify their paddings, margins, and whatnot. So, in general, we work with boxes. But when display: contents is applied, that box seems to magically vanish. Rather, it will be replaced by its pseudo-elements or child-elements. Or you can say, pseudo-boxes or child-boxes. It’s like that box doesn’t exist. Let’s see an example:

<div id=”parent-contatiner”>
  <div id="container" style="display: contents">
    <h3> I am a Panda! </h3>
    <p> I love a Cat! </p>
  </div>
</div>

The container div will not have a box around it, and it will not be visible. Rather, it will be replaced by its children i. e. the h3 and p elements. So now, they are no longer the container’s children, but the parent-container’s children. It will not be gone from the DOM-Tree, it’s just that the Tree will pretend as if it’s not there. Cool right?

Where do I use contents?

You may ask, if the container itself disappears, all the styles and events will be gone, too? The answer is, no. You will still have the events attached to it, and the only styles you will lose are the styles related to box generation (like margin, padding, border, etc). So, where do we use it?

Well, I can give you two scenarios right away.

First, when you need to wrap something within a content for semantic readability, but doing so will break your design. By using contents, you will be able to stand in a sweet spot where you have both — semantic readability and the required design.

Second, you might face a situation, where all your elements need to be direct children of a container that is using flex or grid. You need to apply some styling on some children based on a condition or so. In that case, you can wrap those children within a container with display: contents based on that condition.

Does this sound like a little gibberish to you? Ok, then let me tell you how I found this property in the first place.

A little practice for you!

Let me explain the problem first. I was working on a responsive web page using a mobile-first approach. I had three boxes. In the desktop view they will be shown side by side, just like Image 1 —

Plain and simple flex-row, right? But in the mobile view, Box2 and Box3 will be shown like a stack and this stack will be side by side with Box1 like Image 2 —

Now, how can you achieve that? Think about it. This will introduce you to contents and you might as well have a little hands-on experience!

Let me give you my solution. (Please note that this might not be the only way. It’s just how I solved it personally, and I think it’s neat!)

I have the three boxes inside a parent-container having display: flex applied. I just wrapped Box2 and Box3 in a container. When we are in the mobile view, this container will have display: flex. So now, Box1 and the container are siblings and flex property will only apply to these two. Box2 and Box3 will have separate flex properties applied to them via the container. But when we are in the desktop view, this container will have display: contents. So, in the desktop view, the container visually disappears, and Box2 and Box3 are direct children of the parent-container. Now all three boxes are siblings and flex property from the parent-container applies to all of them. That’s it.

The code may look like this —

<div class="outer-container">
  <span> Box1 </span>
  <div class="inner-container">
    <span> Box2 </span>
    <span> Box3 </span> 
  </div>
</div>

.outer-container {
  display: flex;
  flex-direction: row;
}

.inner-container {
  display: flex;
  flex-direction: column;
}

@media only screen and (max-width: <breakpoint>px) {
  .inner-container {
    display: contents;
  }
}

A tiny note with warning!
I should mention that this property does not work the same with all the elements. There are some elements that are not rendered purely by the CSS box concepts may behave differently. Please see this doc for further reference.

So, yeah, that’s how I’ve found display: contents, and I think it works like magic. No?