Picture this right, You were staring at your IDE.
You just you fed this really complex prompt into your AI
assistant. Oh yeah, we've all been there.
Right, you're trying to build out a new data pipeline
integration, and like 10 seconds later it spits out 500 lines of
just incredibly elegant, perfectly formatted code.
Flawless syntax. Exactly so syntax is flawless.
The variable names actually make sense.
So you drop it into your repository, you hit compile, and
bam, the entire application immediately crash.
Yep, it completely misunderstood the core architecture of the
existing code base. Right, the code looks right, but
it solves like the completely wrong problem.
I mean, it is the defining frustration of modern
development right now. We've essentially traded basic
syntax errors for these massive, severe architectural
hallucinations. Yeah, you're not hunting for a
missing semi colon anymore. Yo, exactly.
Developers are spending way less time writing boilerplate, which
is great, but they're spending significantly more time
untangling these really opaque, complex logic failures.
Well, welcome to Build Wiz AI and welcome to our latest deep
dive. We are really digging into a
huge stack of research today to figure this out.
Yeah, we pulled from a lot of great places for this one.
We did got stuff from Mark Tech post, the GitHub blog,
ThoughtWorks, there's an ARC for research paper in here, the
Blink blog, and a bunch of deep dive presentations on AI
workflows. It's.
A lot of ground to cover. It is, but our mission today is
pretty simple. We want to get you out of what
the industry is calling the Vibe Coding Trap.
Vibe coding. I love that term, but I hate the
practice. Right.
It's where you just sketch a vague goal, you hit enter, and
you honestly just hope the AI's vibes align with your system's
reality. Which they usually don't.
You're treating the AI like a magic search engine you know,
instead of a deterministic engineering.
Tool, exactly. So what is the alternative here?
Because looking through all these sources, there's a very
clear paradigm shift happening. Yeah, the core thesis emerging
everywhere is this concept of Spec Driven Development or SDD.
SDD OK so how does that actually fix the vibe coding issue?
Well, it flips the standard AI workflow totally on its head.
In SDD, the specification document, not the code, is your
primary engineering artifact. Wait, so the code is secondary?
Yes, you define the exact intent as the absolute source of truth
and the resulting code. You basically treat it as a
highly disposable generated byproduct.
I mean, the idea of code being just a disposable byproduct is a
massive psychological shift for any developer.
Oh. Absolutely, it's hard to let go
of the code. Is the main event.
There is this quote in the sources actually from Andrage
Carpathy that frames this perfectly.
He said spec driven development is quote the limit of imperative
to declarative transition, basically being declarative
entirely. That is such a profound way to
look at it, because if we, you know, breakdown the mechanics of
what Carpathy is arguing there, imperative programming requires
you to define the exact control flow.
Like the loops and state changes.
Right, the loops, memory allocation.
You are telling the machine exactly how to do everything.
Yeah, but declarative programming abstracts that away,
like you write SQL to declare what data you want.
And the database engine just figures out the execution plan
on its own. Exactly.
So STD scales that exact concept to entire code bases.
Human judgement dictates the business logic and constraints
the what, and the AI handles the imperative implementation, the
how. I want to put a technical
metaphor on this. Just make it really concrete for
everyone listening. Think about a 3D rendering
pipeline. OK, I like where this is going.
Vibe coding is like trying to build a 3D environment by
directly editing the lighting and texture engine without
defining the underlying geometry first.
Oh wow, yeah, that's going to look like a chaotic mess.
Right, it would be terrible. So spectrum development is
building the wireframe first you define the collision meshes, the
boundaries, the really strict geometry.
And then the AI is just the rendering engine.
Exactly. It applies the textures and the
ray tracing on top of that rigid structure.
You would never let the texture engine decide where the actual
walls go in your game. That's a perfect analogy, yeah.
And when you apply that rigid structure to a real engineering
team, the value just becomes instantly obvious.
How so? Like day-to-day.
Well, let's say a product manager, a front end developer,
and a back end developer are all looking at the exact same vague
prompt to implement a notifications feature.
Oh I see. They all have different
assumptions. Completely different without a
strict spec the PM is envisioning like transactional
emails. While the front end dev assumes
it's a real time web socket pop up in the UI.
Right. And the back end dev.
They're already sketching out a distributed Kafka queue.
And then the AI, if you just leave it to its own devices with
that vague prompt, it will probably hallucinate some weird
amalgamation of all three. Yeah, and it won't actually
integrate with your database at all.
Yeah, so STD forces that alignment upfront.
It captures the architecture in a version controlled format
before a single token of code is ever generated.
OK, so the transition into this workflow, how does it actually
happen? Because the sources highlight
this really structured 4 phase framework.
Yeah, it's heavily popularized by GitHub Spec Kit, which by the
way has over 93,000 stars now. It's huge.
That's massive adoption. So what are the four phases?
It moves sequentially through specify plan tasks and
implement. OK, let's break those down.
Phase one is the specify phase, right?
So this is where you feed the AI your raw high level business
goals and your user personas. And the AI basically acts as a
product analyst. Exactly.
It generates this detailed specification document that has
strict user stories and acceptance criteria.
It defines the boundaries of the problem.
OK. So then Phase 2 is the plan
phase. I assume this is where we get
technical. Yes, here you introduce the
technical reality of your project.
You feed that phase one specification into an
architectural prompt alongside all your system constraints.
So if your stack relies on React on JS and maybe requires strict
IPA compliant data handling, you declare that here, right?
And the AI generates A comprehensive technical plan
based on that. It maps out the data models, API
contracts, the exact dependencies needed.
Which brings us to phase three, the tasks phase.
Yeah, this is where it gets really granular.
The AI takes that massive technical plan and slices it up
into an execution graph of really tiny reviewable units.
It's essentially Test Driven Development or TDD mapped onto
AI generation. That's a great way to put it
because instead of asking the AI to generally build the auth
system, the isolated task becomes like implement a JWT
validation middleware. Yeah, that checks for expiration
and returns a four O 1 status code.
It's incredibly specific. And then finally phase 4 is
implement. Right, the AI just iterates
through that execution graph, writing code for each specific
task and constantly validating it back against the master
specification document. OK, so I have to push back a
little here. Just looking at the cognitive
load of this. Sure.
Yeah, as a developer I am no longer reviewing a mass tangled
500 line pull request full of AI logic guesses which.
Is a good thing. It is, but instead I'm reviewing
natural language documents, the specs, the plans, the tasks
before the code even exists. That feels like a really massive
shift from doing code review to doing requirements review.
It is. It forces the whole engineering
effort heavily into the design phase.
Does it feel slower upfront? Oh, upfront it absolutely feels
slower because you are iterating on markdown files rather than
watching cool code magically appear in your editor, right?
But mechanically you're catching drift at the architectural
level. I mean, debugging A
misunderstood requirement in a natural language document takes
what, 2 minutes? Yeah, it's just reading English.
Exactly. But debugging that exact same
misunderstood requirement after the AI has woven it into 500
lines of interdependent functions that can take 3 days.
That makes a ton of sense, but the tooling ecosystem evolving
around this is honestly wild right now and a bit
overwhelming. Yeah, there are dozens of
frameworks trying to automate these 4 phases.
So let's map out this landscape based on architectural
complexity, just so you, the listener know exactly what fits
your current stack. Let's start at the foundation
with GitHub Spec Kit. So Spec Kit is the baseline.
It's entirely open source and Asian Gnostic, but it's defining
feature is this thing called the Constitution file.
The Constitution file sounds very official.
It is. It's a root level markdown file
that acts as an immutable set of laws for your project.
Coding standards, architectural patterns, prohibited libraries,
it's all in there. And because it doesn't enforce a
specific LLM, you can pipe these specs into, you know, copilot or
Claude code or the Gemini CLI. Right.
It's very lightweight and highly flexible, but as we move up the
complexity ladder we get into specialized IDE's.
Like KIRO, the sources really highlight KIRO which is an AWS
native agentic environment. Yeah, and what stands out about
KIRO isn't just that it forces you to write requirements, it's
how it structures them using something called ears notation.
Ears. What does that stand for?
It stands for Easy Approach to Requirement Syntax.
It's basically a formal template for translating natural language
into a pseudo state machine. OK, how does that look in
practice? Well, instead of a vague prompt
like, make sure the user's logged in ears forces a
structure like while the system is in an unauthenticated state.
When a user attempts to access the dashboard, the system shall
redirect them to the login route.
Wow, that is brilliant. By forcing the language into
that strict while when then structure, you are essentially
defining state transitions mathematically.
Exactly, and the AI can parse that without any ambiguity
whatsoever. It catches edge cases that a
casual prompt would just completely gloss over.
So if single agent environments like Kira represent component
level automation, the next escalation has to be distributed
multi agent frameworks, right? Oh absolutely.
And the heavy hitter in the research here is the B MAD
method. The breakthrough method for
agile AI driven development. That's the one.
And this framework is intense. It orchestrates up to 21
specialized AI agents across the software life cycle.
Wait 21, the documentation for BMAD literally reads like a
corporate directory. I know it really does.
It uses named personas like Mary the business analyst, Preston
the product manager, Winston the architect.
It sounds a bit like corporate role play, I admit, but beneath
that surface level naming, the underlying architecture is
actually a highly deterministic state machine.
OK, so the personas are with specialized system prompts.
Exactly. The real power of BMAD is how it
manages the handoffs between these agents using really strict
YAML configurations. It operates as a directed
acyclic graph or a DAG of execution.
So Mary, the BA agent generates a requirements file.
The system of validates that file schema first.
And then? Only then does the YAML
configuration trigger pressed in the PM agent to ingest Mary's
output and generate the PRD. It totally eliminates the
chaotic overlap you get when one AI tries to do everything all at
once. But orchestrating a 21 agent DAG
is super heavy. It's very heavy.
If you want that distributed execution without those intense
corporate style Sprint ceremonies, there's a leaner
alternative mentioned in the sources.
Yeah, it's called GSD or get shit done.
Love the name and it has over 61,000 GitHub stars.
Yeah, it's incredibly popular, yeah, because instead of
sequential handoffs, GSD focuses on parallel execution.
Like a MapReduce philosophy. Exactly.
It spawns researcher, planner and executor agents all
simultaneously and then merges their outputs.
It allows for much faster iteration on smaller tasks.
OK, but all of these tools, BMADGSD spec kit, they work
beautifully in a Greenfield environment right when you are
building from scratch. Oh sure, starting from zero is
the easy part. Right, but the true engineering
test is brownfield development, integrating new specs into a
decade old highly coupled code base.
That is where standard AI workflows completely fall apart.
The hallucinated context just destroys everything.
So for Brownfield, the research points to two distinct
approaches. The first is Open Spec, which
enforces strict delta markers. Delta markers, right?
So before it writes code, open spec generates a proposal that
computes a different graph of your intended changes.
So it explicitly categorizes every architectural adjustment
as added, modified, or removed relative to existing functions.
Yeah, it acts as an explicit approval gate.
You can see exactly which legacy dependencies the AI is about to
touch before it breaks them. That's.
Super practical, but the second approach to brownfield operates
at the true enterprise scale, and that's augment code.
Yeah, because the issue with massive repositories is contact
window limited. Yeah, you just cannot feed a
million lines of legacy code into an LLM prompt.
It'll just forget the beginning by the time it reaches the end.
Right, so Augment solves this with a context engine that maps
semantic understanding across over 400,000 files.
Wow. And it doesn't just run dumb
keyword searches, it utilizes vector embeddings mapped over
the code bases, Abstract Syntax Tree or the AST.
So when the AI writes a new function based on your spec,
Augments Engine actually understands the AST.
It knows exactly which hidden interface or obscure legacy
utility file that function needs to.
Import exactly which prevents those massive integration
crashes we talked about at the very beginning of the.
Show OK, so looking at this escalation from basic spec kit
up to enterprise augment, it really forces a conversation
about maturity models. Yeah, like how far do you
actually push this declarative philosophy?
Right. The ARCSIF research paper we
reviewed defines 3 distinct levels of STD maturity.
Level 1 is basically spec first. Right, so you write this spec,
feed it to the AI, generate the code and then you just abandoned
the spec. It acts as temporary
scaffolding, yeah. Use it and lose it.
Then level 2 is spec anchored. This is where the spec actually
lives in the repository alongside the code base.
So if you update the code, you are expected to update the spec
to match. They're parallel sources of
truth. But Level 3 is where the
paradigm just completely shifts. They call it Speck a source.
This one blew my mind. I know in a Level 3 architecture
the human developer never touches the code at all.
You only ever edit the Natural Language Specification document.
Which feels crazy. Experimental platforms like
Tesla are actually injecting strict compiler level warnings
into the code base. Literally adding comments that
say generated from spec do not edit.
The markdown file essentially becomes the application itself.
That concept spec A source sounds incredibly futuristic,
but I think we need to ground this in the reality of daily
development. Yeah, we have to look at the
downsides. Because there is a massive,
incredibly valid counterpoint to this entire philosophy.
We found it in a deep dive by Burgitta Buckler at
ThoughtWorks. Yes, she surfaces a very real
friction point, which she calls markdown fatigue.
Markdown fatigue. It is currently the strongest
critique of STD circulating right now.
It is. Buckler points out that LLMS are
inherently verbose. Right, they love to talk.
Exactly. So when you force an AI to
generate extensive markdown specifications for every single
action, the sheer volume of boilerplate text just explodes.
He notes that for a simple one line bug fix, say you're just
adjusting a CSS padding value or fixing a typo in a database
query. Yeah, a tiny fix.
The STD workflow might force you to review an updated user story,
a modified technical plan, and a new task file before the AI is
even permitted to execute that fix.
It's overkill. The cognitive load of reviewing
3 pages of boilerplate English just to approve A1 line code
change is absurd. It.
Completely destroys developer momentum.
And from an architectural standpoint, her limitation is
mathematically sound, the overhead of a strict DAG
workflow or a four phase spec generation.
It consumes more compute time and human review time than it
saves for those micro iterations.
So STD is really designed to prevent architectural drift
during medium to large feature development or complex
refactoring. Exactly.
For rapid iterative small scale bug fixing, forcing a
deterministic spec pipeline is just the wrong tool for the job.
You need the flexibility to make direct imperative interventions.
Which brings us to the immediate practical application for you
listening today. Let's say you agree with the
philosophy of STD. But you don't want to install
some complex multi agent yaml framework right now.
Right. How do you implement the core
benefits of this workflow today? The most actionable take away
from the sources is mastering A technique called context
engineering. Context engineering is
brilliant. It's about deterministically
configuring the AI's environment so you don't have to constantly
repeat your architectural constraints every single chat
session. And the simplest, most powerful
way to do this is by creating 2 root level system files in your
repository. Let's talk about the first one.
So the first is universally referred to as the clawed MBE
file, though honestly it works for Copilot, cursor, Gemini or
any agentic IDE. OK, So what does it do?
This file serves as the ersistent root memory for your
project. Instead of relying on the AI to
just guess or infer your architecture by reading random
files, the Claude MU dot MD explicitly defines the state of
your application. So you map out your specific
text stack, your rigid naming conventions, maybe the path to
your UI component library. And most importantly, your do
not touch rules. That's crucial.
Right, like if you have a legacy authentication module that just
breaks when modified right? You explicitly fence it off
here. A well engineered 100 line
Claude MD file eliminates the need to constantly course
correct the AI. OK.
And the second file is agents dot MD right?
If you are starting to experience with tools like
cursors, multi agent features, this file acts basically as the
Riata ME for the AI workers. It explicitly defines the
constraints for different agent roles.
That way they don't hallucinate overlapping responsibilities and
cause merge conflicts with each other.
But beyond just setting up those system files, there is a vital
mechanical tip from the sources regarding how you manage the
LLMS context window during a live session.
Oh yeah, this is super important.
It's the frequent use of the slash clear command to wipe the
chat history. I have to admit, this feels
completely counterintuitive to me.
Really. How so?
Because as a developer, your instinct is to maintain a
massive scrolling chat history. So the AI quote UN quote
remembers the entire journey of the feature you're building.
Oh, I see, but technically that is exactly what causes the AI's
logic to degrade. Why is that?
Lom sucker from attention Mechanism Diffusion when you
have a 30,000 token chat history filled with previous code
iterations, dead end debugging attempts, conversational filler.
Oh right, the model's attention gets spread way too thin.
Exactly, it starts referencing deprecated code from 20 prompts
ago. Call this token pollution.
Token pollution. So by running slash clear after
every major task boundary, you are purging that token
pollution. You wipe the conversational
memory, but, and this is the key, because your keel yo E dot
MD and your spec files are saved in the repository, the AI simply
rereads those clean authoritative documents.
That makes total sense. You keep the AI's context window
sharp, grounded entirely in the current state of the
architecture rather than the messy history of how you got
there. It's.
A game changer for long sessions.
Well. We want to acknowledge and
credit the researchers and developers who are mapping out
this rapidly changing ecosystem. Yes, huge thanks to them.
The insights we explore today were sourced from deep dives on
Mark Tech Post, The architectural breakdowns from
the GitHub Spec Kit documentation, The formal
maturity models in the Arcs of Research paper by Deepak Babu
Pascala. And the highly practical counter
perspectives from ThoughtWorks. Alongside analysis from
Intuition Labs, the J Focus presentations, and the, IT is an
incredible stack of knowledge that entirely redefines how we
interact with the code base. It really does.
We started by looking at the chaos of Vibe Coding, treating
the AI like a magical slot machine.
Then we broke down the mechanics of SPECT driven development,
moving from that 3D rendering analogy to the strict execution
of ears notation. We navigated an ecosystem
stealing from lightweight constitution files all the way
to 21 agent state machines and vector embedded context engines.
And we acknowledge that while markdown fatigue is very real,
mastering context engineering through root files and token
management gives you immediate architectural control today.
Which brings us to the end. But as this tooling matures, it
leaves us staring at a profound philosophical shift in computer
science. Yeah, it really makes you wonder
about the future. If we truly reach Level 3, if
specca source becomes the standard and the generated code
is completely hidden from the human developer.
Does that mean English or any spoken human language is
inevitably going to become the highest level, most widely used
compiled programming language in the world?
It is a wild thought. You are no longer writing
syntax, you're compiling your intent.
Until next time, keep building.