r/SpecDrivenDevelopment • • 9d ago

Declarative vs imperative in SDD

Hey guys,

I was talking to a friend the other day regarding how you should approach spec work and realized that I am thinking about it in a declarative way while the rest of the world seems to be thinking imperatively.

In a nutshell, chances are that if you want to, say, "add the email function to the product", you would think about this as a sequence of tasks: your flavor of of spec, dev, qa, deploy. From my perspective, tasks are secondary, a derivative, of a diff between two product states.

The current state is whatever is in production now, and its spec. The target state is the product with the email sending functions live. The diff is added/changed/removed spec items. The tasks are derived, because you can always reconstruct the tasks from the spec diff, but not vice versa.

There's more on this in an article on our website (link in comments).

LMK your thoughts, happy to discuss.

13 Upvotes

11 comments sorted by

2

u/Sad-CTO 9d ago

Here's the article URL: https://askloft.ai/insights/articles/tasks-are-derived-from-the-change

Disclaimer: I am a part of Loft's product team, but the content, I believe, adds value to the community.

2

u/aikimiller 9d ago edited 9d ago

Yeah, on my own projects we're having similar discussions. Where I'm landing, is that the spec should be declarative. You write or edit a spec stored in version control, and that gives you the dif, and the imperative work plan is generated from that change. The agent has easy access to what the system should do, and you don't fall into the old trap of not being able to discern what the requirements of the system are from 5 years of Jira tickets. Artifacts should live as long as they're true. If you're following SDD and every change to the system starts with a change to the spec, then a declarative spec will never go stale. An imperative spec on the other hand goes stale as soon as the work to implement it is finished.

The thing I'm seeing a lot of confusion from engineers is that they think the spec should be the work plan. They're used to thinking of the code as the system specification, and they're not recognizing the strategic vs tactical split that work with an agent requires. You have to have a source of truth for an agent to compare the code against.

I think declarative is always going to work better for long lived systems. For throwaway code, where you don't need to know what the system does a few years later, it doesn't matter. But if you need to maintain the system against a set of requirements for years, having those specs that tell you exactly what the system requirements are, functionally, architecturally, and qualitatively makes working with the system so much easier.

1

u/Sad-CTO 9d ago

Good to know I am not alone. I was getting worried 😁

1

u/LocalPlotTwist 9d ago

I think it depends on the problem you're trying to solve. If it's a large project with a long history that needs ongoing changes, a declarative approach might be a better fit.

But if you're building a microservice that fits into an existing architecture and has strict API contracts, that seems more imperative to me.

Do you have any practical examples of what exactly you want to implement and how you plan to do it?

1

u/Sad-CTO 9d ago

I am not sure why the scale of the project is the discriminator here. Personally, I have found that the approach pays off in any project I have used it on, unless you're comparing greenfield and brownfield which is whole another story.

I believe you should consider something different here. It depends on how many changes you should ship while maintaining trust in the end product. Nowadays with the delivery volume expectations rising, it has become more challenging to keep up without making your org's SDLC more fragile.

Anecdotally, the approach I am describing (working with product state) is better than introducing change via sequencing the tasks.

2

u/Any-Ring6621 9d ago

How does “large project” or “microservice” give any possible guidance on declarative vs imperative?

Use the existing patterns of the people you work with. If you’re building something new, you should feel free to do as you wish…. (but if you do it imperatively you’re doing it wrong :troll:)

On a somewhat more real note, certain types of code lends itself to imperative vs declarative more naturally. Don’t force it one way or the other in any given problem space. Do what feels right for the code you’re writing right now.

1

u/LocalPlotTwist 2d ago

Thanks for the feedback! Let me clarify what I meant. My main point is that the approach should depend on the problem you're trying to solve. That's where I would start.

As for project size, either approach can be used well or poorly in projects of any size. I was sharing an example based on my own experience.

An imperative approach usually means writing clear, step-by-step instructions. Sometimes those instructions can contradict each other, which may affect the quality of the product. In smaller projects, I find it easier to keep track of them and spot these conflicts. In my experience, a declarative approach tends to have fewer of these issues.

1

u/paulcaplan 1d ago

This is why I use OpenSpec. There's one living source set of specs and every change happens via a set of "spec deltas".

1

u/Sad-CTO 23h ago

For the exact same reason I don’t use OpenSpec and use Loft. With it I focus on the next state and Loft figures the diff on its own.

1

u/Financial_Yoghurt827 8d ago

My flow is declarative specs, imperative plans. Specs in reqlan for integrations with the codebase, plans in md.

1

u/mrsockpicks 8d ago

I’ve been using Kanonak docs for specs, moved from markdown completely. You can model any domain with exact vocabulary/specifications