Spec-Driven Development: How AI Is Changing the Way We Think About Software Design

When we started Project Weaver, we weren’t trying to replace engineers or reinvent software development from scratch. We were experimenting with something both simpler and more ambitious:

What does it take for an AI system to operate as a genuine engineering partner- not a code autocomplete, but a collaborator that can meaningfully participate in the creation of real backend applications? As soon as we began putting serious workloads through AI agents, a pattern emerged. Whenever the agent succeeded, there was clarity. Whenever it struggled, there was ambiguity. And the difference almost always came down to one thing: Specifications.
Not the heavy, bureaucratic kind that live untouched in Confluence pages; not the “requirements documents” written because a process demands them; and not the endlessly detailed diagrams only a handful of people understand.
We’re talking about something more fundamental: clear expressions of intent.
AI is not good at inferring intent. It doesn’t fill gaps the way human engineers do. It doesn’t construct mental models automatically. It doesn’t make assumptions unless you force it to. And that changes everything about how we design and implement software.
Over time, we realized that spec-driven development isn’t just helpful in an AI-assisted workflow - it’s foundational. But only when you understand that there are actually two kinds of specifications at play.

The First Type: Human Specifications - The Architecture of Thought

Human engineers form specifications instinctively, even when nothing is written down. We imagine how the system should behave, what the components will do, how the data flows, what constraints matter, what trade-offs we’re making. These internal mental models are a form of specification- just implicit.
AI can’t read implicit intent. It can only operate on what is typed, not what is meant.
So part of spec-driven development in Weaver is the discipline of making this engineering intuition explicit. These specifications describe what we want built and why. They capture architecture, constraints, responsibilities, failure conditions, interactions, and downstream impacts.
When done well, these documents are short, sharp, and decisive. They give the AI boundaries to operate within, guardrails that keep it from hallucinating structure, and a shared vocabulary for the system we’re creating together.
In this view, a specification is not a bureaucratic artifact- it’s the interface between human judgment and AI execution. If the human doesn’t express the shape of the idea, the AI has nothing to honor.

The Second Type: AI Specifications - The Model’s Memory and Method

Then there’s the other kind of specification- one that humans rarely think about but AI absolutely depends on.
As the agent works, it creates its own internal scaffolding: summaries of code it’s explored, a list of relevant functions, a breakdown of the next steps, a compact restatement of the architectural pattern it must follow. These aren’t long-term documents; they’re temporary, tactical artifacts that help the model stay focused as it moves through complex tasks.
A human engineer does something similar. We draw quick sketches, jot down notes, break large tasks into smaller ones, and reread code to anchor ourselves before making changes. We are constantly summarizing, condensing, and reorganizing our understanding of a problem.
For AI, these “thinking artifacts” must be written out. They become lightweight specifications that exist only long enough to support the next action. And while they may appear ephemeral, they dramatically improve the reliability of the agent’s output.
This is where the idea of spec-driven development becomes richer.It’s not only about human-authored specs guiding the system; it’s also about AI-generated specs guiding itself.
Both matter. Both are essential. And both must work together.

Why Project Weaver Uses a Spec-Driven Approach

Weaver is intentionally opinionated. It’s not trying to generate all possible applications in all possible ways. It builds robust NestJS backends using a consistent structure and a predictable architecture. That focus allows us to design specifications - both human and AI-generated- that are tailored to exactly what Weaver needs.
Human specifications define the architecture. They form the “spine” of the application and dictate the structure the AI must respect. They are the engineering decisions, the boundaries, the responsibilities, the reasons.
AI specifications let the model operate intelligently within that structure. They are the working memory, the notes, the plan, the wayfinding tools the agent uses to keep itself aligned as the codebase grows.
Without human specifications, Weaver lacks direction.Without AI specifications, Weaver loses coherence.With both, Weaver becomes far more powerful and far more reliable.
This reinforcing loop sits at the heart of everything we’re building.

How Spec-Driven Development Shapes the Three Phases of Weaver

As Weaver grows more capable, the role of specifications shifts, but never disappears.
In Phase 1, specifications act as the scaffolding for the agent’s reasoning. We focus on understanding how it plans, how it digests a codebase, how it organizes steps, and why certain specification formats improve outcomes dramatically.
In Phase 2, when parts of the workflow become automated, specifications become the connective tissue. The human writes a high-level description; the system expands it into working specifications the agent can execute; the agent uses those to produce the feature.
And in Phase 3, when Weaver begins influencing the project planning itself, specifications become the blueprint for entire applications. They guide the decomposition of a product vision into epics, features, and actionable tasks—each of which can be implemented safely and consistently.
What began as a tactical necessity eventually becomes the architectural backbone of a full AI-assisted development lifecycle.

Why We Aren’t Using a One-Size-Fits-All Specification Framework

There are powerful general-purpose tools out there, SpecKit is one example, that aim to standardize how AI agents work with specifications across many environments. They are doing valuable work.
But Weaver is different.
We’re not building a general AI coding assistant.We’re building an AI engineer for a specific domain.
Because the stack is fixed and the architecture is opinionated, Weaver can lean into much tighter, more precise forms of specification. The formats can be optimized for the conventions we require. The instructions can be sharper. The workflow can be more reliable because the variability is reduced.
General tools solve for breadth.Weaver solves for depth.
And in this context, tailored specifications, both human and AI-generated, are far more effective than any universal template.

The New Frontier: Engineering as Specification One of the quiet transformations happening across the industry is the shift from “engineering as typing” to engineering as describing.

The value of the engineer moves upward - away from mechanical implementation and toward clear reasoning, architectural thinking, decomposition, constraint setting, and planning. AI handles more of the hands-on construction. Humans handle more of the design and judgment.
This isn’t a loss. It’s a refocusing.AI isn’t replacing engineers; it’s pushing engineering back into what makes it a deeply intellectual discipline.
Spec-driven development is the language of that shift.
It is how humans and AI communicate.
It is how we encode clarity into a workflow that demands it.And it is how Weaver learns to build software not as a string of prompts, but as a coherent system.

What Comes Next

We’re continuing to refine how Weaver uses specifications in all three phases. Over the coming weeks, we’ll share more about:

• The structure of human-authored specs optimized for NestJS
• The minimalistic working specs the AI uses to stay focused
• How specs allow Weaver to automate large parts of the development process
• How project-level specifications evolve into orchestration in Phase 3

If you’re exploring AI-assisted engineering in your own teams, or experimenting with how specifications can improve reliability in agent workflows, we’d love to compare notes. We’re learning a lot, and building in a space that is changing faster than anyone expected.