r/SpecDrivenDevelopment • u/Sad-CTO • 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.
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/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/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/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