Welcome to the architecture Corner.
You know, if you feel like we've been stuck in a bit of an AI
Groundhog Day lately, well, you're probably right.
It does feel that way sometimes, doesn't.
It yeah, it's late 2025, investments are still pouring
into AI development huge amounts.
But thankfully the conversation, at least professionally, seems
to be moving past that whole developers are obsolete phase.
Oh thank goodness, that was getting tiresome.
It feels like we're finally shifting out of that Wild West
phase of just pure generative AI, right?
And into something a bit more structured because let's face
it, vibe coding, you know, type of prompt.
Hope for a miracle. App, huh?
Yeah, the miracle. App, It all just creates a mess,
right? Yeah, unmaintainable technical
debt. The industry is starting to get
that speed is kind of useless if you don't have governance.
So structure is the keyword and the technical term we're hearing
more about is specification driven development or SD
requirements driven development. Same idea.
Exactly. When you look at the landscape
now, you've basically got those like prompt to full app systems.
You mentioned the Vibe coding camp.
And then you have the more traditional AI assisted tools,
think copilot cursor things living in your IDE helping out
right the assistance. And the big problem historically
was how do you govern those assistance if you wanted them to
follow your specific rules, maybe use PostgreSQL, Stick to
certain security standards. You ended up building these
enormous custom instruction. Files.
Oh yeah, the massive prompt engineering headache.
Exactly, and they were a nightmare to maintain.
SD flips that script. It aims to make the
specification, the requirements, the rules of first class
citizen, something you actually maintain as part of the whole
development process. OK, that sets the stage
perfectly for what we want to do.
Today we're going to do a deep dive into.
Spicket, spicket. Yeah, it's a newer open source
player specifically designed for this SDK approach.
We really need to unpack how it works, what it actually delivers
and, importantly, what the early reviews are saying about its
strengths and maybe its weaknesses.
And what's really interesting about Secret, I think is how it
does this. You might remember some early
proprietary tools like Hero. They often followed a similar
requirements design implementation flow.
Right, but they often locked you into their ecosystem.
Precisely. KIRO for example often meant
using their specific environment or IDE fork spec.
It takes a different path. It's basically delivered as a
collection of open source custom prompt miles and shell scripts.
So the lighter weight. Much.
It essentially acts as an orchestration layer on top of
the AI assistant you might already be using.
It's there to enforce discipline, to provide that
governance layer. I like that framing the
governance layer, not the AI engine itself.
OK, so walk us through the workflow.
It sounds like it's a pretty specific, maybe cyclical
process. It absolutely is cyclical.
That's key. You expect to iterate The basic
loop goes something like this. Create principles, they call
this the constitution. Then define requirements, the
specification. Then you might clarify
ambiguities. After that, create the plan,
generate tasks, optionally analyze consistency, and only
then do you implement tasks. And if that analysis step finds
something off, you just loop back, maybe to clarify, maybe
even back to the specification stage, OK.
That sounds thorough, maybe a bit heavy up front.
How complex is the actual setup getting started?
You know, surprisingly straightforward based on the
source material. They recommend using the UV tool
for installation, which is pretty standard now.
OK, and here's what I think is the crucial architectural bit.
When you initialize Spec it in your project, it sets up
dedicated folders that are meant to be source controlled.
You get a GitHub folder holding all the custom prompts files,
actual markdown files like secret plan prompts, and ah OK.
You also get a specify folder for templates, scripts and
importantly, the artifacts that generates along the way.
Right, so because these are just regular files marked down shell
scripts living inside your project repo, they instantly
become part of your source control.
Exactly. That's a huge win for
governance, isn't it? The whole team shares and can
customize how the AI behaves. The team owns the AI behavior,
not just one person fiddling with prompts.
That's the core idea. You establish that shared
ownership right from the start, beginning with that very first
artifact, the Constitution. OK, let's unpack the
Constitution. How should we think about this?
Is it like the projects 10 commandments, the non-negotiable
architectural? Laws.
That's a great way to put it, yeah.
It dictates the mandatory project wide conditions, things
like coding standards, required frameworks or libraries, and
crucially, architectural patterns.
What kind of patterns are we talking?
Yeah, well, the review we looked at mentioned a constitution that
mandated, for example, layered architecture, specifically using
Domain Driven Design or DDD principles.
OK. D that's significant.
And it also mandated Command Query separation CQRS.
Wow. OK.
Mandating CQRS from the start, that's a serious architectural
commitment. That force is a really clear
split between how you change data versus how you read.
It it does, and it means even a junior developer guided by the
AI assistant using these prompts has to adhere to that
potentially complex enterprise level pattern right from the
gecko. It guarantees a certain level
consistency. Consistency, right?
And what's really neat is that spec, it doesn't treat the
Constitution as this static document you write once and
forget it actually tracks changes to it.
Oh yeah. It generates what they call Sync
Impact Report. So if you decide later to add a
new principal, say, enforce specific Jess testing standards
for TypeScript, the report tells you how that change might impact
other parts of the system downstream.
So it makes architectural evolution a managed, traceable
thing. Exactly, it's not just someone
changing a wiki. Page OK, So once we've defined
how we build with the Constitution, we move on to what
we're building. That's the specification.
Right, the specification focuses purely on the functional
requirements. It's all about the what and the
why of the feature, and it deliberately avoids getting into
the how. Give me an example.
Let's say we're building that multi user movie tracking app we
mentioned earlier. The specification would define
things like users must be able to add movies, or the system
must prevent duplicate movie titles per user, or it must
display the average user rating for each movie functional stuff.
Got it. What it does?
Why it does it not the implementation details yet.
Now, before we go further, I think it's important we credit
the author whose detailed review really guided this exploration.
That's Mario Bittencourt. Absolutely.
His walkthrough was incredibly helpful in understanding the
structured flow. He really emphasized the value
of taking the time in these early planning stages, didn't
he? He did, and the specification
phase is also where spec it starts.
Doing some practical setup, it automatically creates a new git
branch for the feature and sets UA dedicated SEC solder to hold
all the artifacts generated for that specific feature.
OK, the output from this stage is a pretty granular list of
numbered requirements like FR003 system amest enforce unique
titles, very explicit. And right after we define what
we want, we hit the clarification step.
This feels really important. This is where we stop the AI
from just making wild assumptions, right?
That's exactly its purpose. Think of it as an early quality
gate to prevent what you might call integration debt later on.
The clarification step scans both the Constitution and the
specification you just created, looking for ambiguities or
missing pieces. How does it present those?
The author noted it usually gives you a limited list of
questions, maybe 5 or so, often suggesting recommended options.
It forces the human developer to make a decision and commit to a
specific direction. Like it might ask for
authentication. Do you prefer GitHub Oath,
Google Oath or maybe Azure? AD exactly that kind of thing.
If you don't answer that explicitly, the AI might just
pick one, potentially locking you into a dependency or
architecture that's completely wrong for your project.
So we nail down this big decisions early, avoids costly
rework. Correct.
You prevent potentially catastrophic assumptions before
they get baked in. Only once those core artifacts,
constitution and specification are clarified and stable do you
move to the plan phase. This is where we finally get to
the how. The how?
What happens here? Here, the AI takes everything
defined so far, the rules from the constitution, the
requirements from the specification, and synthesizes
it all to propose a concrete implementation plan.
Often it starts by outlining necessary research.
And what does that plan look like?
Is just a big text file saying do this then do.
That oh, much more than that. This is where the structural
detail really starts to emerge. The plan phase generates several
key artifacts, all designed for human review.
You typically get a data model dot MD outlining entity
relationships like user, movie entry, rating, entities useful.
You'll get an Openapi YAML file if it involves an API, plus
explanatory markdown files like plan dot MD itself, maybe your
research dot MD summarizing findings, and even a quickstart
dot MD how to get things running.
Wow, OK, that's quite comprehensive documentation
generated before code. Right, all ready for inspection
before the AI even thinks about generating.
Code seems thorough, but then there's another optional step,
the checklist. What's this about?
How is it different from clarification?
Good question. The checklist step is focused
more on non functional requirements and quality
attributes. Think security, user experience,
API design best practices. But it's not just a generic
checklist, it's customized to generate it spec.
It first asks the user clarifying questions about the
checklist itself, like what things like what is the security
focus scope for this feature? Or what's the risk priority?
Critical, high, medium? And maybe are there specific
compliance standards we need to meet like OWASP Top 10?
I see. So instead of just giving me a
generic 100 point security checklist, it generates 1
tailored to the fact that we decided this feature is critical
and we need to ensure it covers, say, the Oauth top 10
vulnerabilities. Exactly.
That specificity is a major step up from just asking an LLM.
Make this secure in a basic prompt.
Definitely more targeted OK plan is set quality checks defined
now? What now?
We break it down the tasks phase.
This takes the high level plan and decomposes it into smaller
actionable instructions for the LLM.
These also serve as review points for the developer.
OK, this is where I start to get a little skeptical.
Based on the review it mentioned the example feature generated
205 tasks 205. Isn't that just trading the work
of coding for the work of auditing a massive AI generated
waterfall plan? That is the core tension,
absolutely, and spec it seems to anticipate this, trying to
mitigate it with the very next optional step, which is analyze.
Yes, 205 tasks sounds like a lot, but the goal seems to be
granularity. The tasks dot MD file it
generates lists them out, often organized by phase or user
story, and even tries to mark tasks that could potentially be
run in parallel with AP. All right, let's talk about
analyze. Why is this stuff so important,
especially if you have that huge task list?
This, I think is where the real power of this structured,
specification driven approach comes through.
The analyze step cross references everything generated
so far, the constitution, the specification of the plan, the
individual tasks looking for inconsistencies or divergences
between. Them so it's checking its own
work essentially. In a way, yes.
It quantifies the cost of any overlooked details or
contradictions before you commit to writing actual production
code based on that. Plan.
Can you give an example of what it might catch?
Something concrete. Yeah, the source material
highlighted some really critical issues.
It found things that human might easily miss until much later,
like during integration testing. For instance.
It flagged a missing Docker Compose setup task that was
needed early on, even though the overall plan clearly required
containerization. Huh.
Subtle but important. Or another one.
It noticed that the task list failed to include logic to
prevent deletion of platforms or tags if they were still in use,
which directly violated A requirement probably stated way
back in the specification or even the Constitution.
That is impressive, catching a potential data integrity or
business logic flaw just by analyzing the generated
documents. That could save days, maybe
weeks of debugging and rework later.
That's the value proposition, right?
Yeah, it aims to catch those high severity architectural were
requirements violations before you even start the
implementation phase. That alone could justify the
structured overhead for many teams.
It really ensures the code you do eventually generate actually
matches the requirements you set out.
OK, so assuming we run analyze, fix any high severity issues it
finds, then we finally get to implementation.
Then we get to implementation and even here spec it throws in
one last little safety check. The final warning shirt.
Kinda, yeah. Before it starts executing the
tasks, it checks those quality checklists we defined earlier,
like that customized security one.
If any are still marked as fail, it alerts the user.
But it lets you proceed. Yes, the human is still in
control. You get the warning, but you can
decide to proceed anyway. We'll pause, go back and resolve
whatever failed the checklist. Right.
And how does the implementation itself work?
Does it just dump a huge amount of code on you at once?
No, it seems more controlled. It follows the phases or user
stories laid out in that tasks dot MD file.
As it executes each instruction prompting the underlying LLM, it
marks the task complete, usually with an.
X and the developers role during this.
You get to decide the review cadence.
You could, in theory, let it run and accept all files
automatically, or you could review each file 1 by 1 as it's
generated. Or maybe you review a batch of
files at the end of each phase or user story.
You choose the level of scrutiny.
OK, so we've gone through this entire pretty detailed journey,
5 to 8 steps depending on the optionals from the high level
constitution, all the way to implement hopefully consistent
code. What was the bottom line for
Mario Bittencourt's review? How viable is this in the real
world? Well, the overall assessment was
definitely positive. The main take away was that
Specht successfully brings that much needed governance and
predictability to AI assisted coding.
The structure really pays off in 2 main ways.
First, it delivers a working solution faster than purely
manual coding would likely achieve.
Second, and maybe more importantly, because of things
like the Constitution, the resulting code was
architecturally bound and stylistically close to what was
desired, adhering to those DDD and CQRS patterns they mandated
up front. So you get speed, but it's speed
coupled with mandated quality and consistency that sounds like
the Holy Grail. Where did this structure become
a potential drawback or burden? The biggest caution flags was
around scope management. If you try to use spec kit for a
very large monolithic feature, the sheer volume of generated
artifacts you need to review can become overwhelming.
Ah, the review burden. Exactly.
The author mentioned one feature generating 30 or more created or
updated files. The planned files, the tasks
file, the data models, and the code itself.
Reviewing all of that effectively can be really
challenging and frankly tiresome.
It's almost like trying to learn a new complex domain just by
reading a huge pile of new documentation and code dropped
in your lap. That's the critical tradeoff
then, isn't it? You potentially solve the AI
generating inconsistent or architecturally unsound code
problem, but you might introduce a new cognitive load problem for
the human reviewer if the scope is too big.
That nails it. If I have 30 new files to check,
am I really in the loop or am I just becoming a post hoc auditor
for the AI? Yeah, you're just checking the
homework after it's all done. Right, so the clear
recommendation for you listening seems to be use spec it or tools
like it, but stick to smaller, more focused features or user
stories. Use it to enforce consistency on
manageable chunks of work. That way the human in the loop
is genuinely reviewing and guiding as things are generated,
not grounding in documentation. Afterwards, and if you're
someone who really loves that freewheeling vibe coating
approach. Then this highly structured
multi step process might feel, well, tedious or like overkill.
It's definitely a shift in mindset.
So spec It represents a kind of maturing middle ground.
It acknowledges that just prompting for speed leads to
fragile chaos in the long run. But it demands that upfront
investment in planning and specification in defining the
rules. It's trading that immediate may
be deceptive speed of generation for longer term consistency,
maintainability and architectural integrity.
Well put. It really feels like the
structured future for leveraging AI assistance effectively in
serious development, offering those quality checks and
governance layers that pure prompt engineering just doesn't
have. Which brings us nicely to our
final provocative thought for you to consider for development
teams, especially those working in complex or regulated
industries where architectural governance and consistency
weren't just nice to haves, but are absolutely critical.
And we know there are many teams like that.
For those teams looking to scale how they use AI assistance,
doesn't this kind of specification driven
development, maybe using open source orchestrators like Spec
Hit start to look less like an option and more like a
necessity? Is the discipline it imposes
ultimately worth the quality and predictability of the output?
Based on what we've discussed today, the early signs seem to
point overwhelmingly towards yes, the discipline seems to pay
off. Definitely something to think
about now. Don't forget to check the
description for links and more information on the sources we
discussed today, including Mario Bettencourt's full review of
Spec It. It's worth a read.
And please make sure you subscribe absolutely free onto
the Architecture Corner newsletter over at
architecturecorner.substack.com. Thanks for joining us.