Spec Driven Development

Specifications are more valuable than code because they capture intent and values that can align both humans and AI models, making specification authorship the most critical programming skill in the AI era.

By Sean Weldon

I recently watched a video about Specifications are more valuable than code because they capture intent and values... and wanted to share the key insights.

I Just Realized: We've Been Thinking About Programming All Wrong

I recently watched a video that completely shifted how I think about programming in the age of AI, and I need to tell you about it because it's kind of mind-blowing.

Wait, So What's Actually Valuable About Programming?

Here's the thing that hit me: apparently 80-90% of programming's value comes from structured communication, and only 10-20% from the actual code we write. I had to pause and think about that for a minute. The speaker explained that as AI models get better at generating code, the really critical skill is becoming something called "specification authorship"—basically, capturing what you actually want in documents that both humans and AI can understand and align with.

The way they put it was pretty striking: specifications are the actual source code, and the generated code is just like... compiled binaries. That's a total flip from how I've been thinking about things.

The Real Bottleneck Isn't What I Thought

When I think about my typical workflow, it's talking to users, figuring out their problems, distilling requirements, brainstorming solutions, planning how to build stuff, explaining the plan to others, writing code, testing it, and making sure it actually works. The speaker pointed out that structured communication is the bottleneck in all of this, not the coding part.

This makes so much sense when you think about it: as code generation gets automated, the programmer who can communicate most effectively becomes the most valuable. Specification writing is the core programming skill now.

We're All Doing "Vibe Coding" (And It's Wrong)

Okay, this part made me cringe a little because I'm totally guilty of this. The speaker called out what they termed the "vibe coding antipattern"—basically, how we currently use AI tools. We treat our prompts as throwaway, but we carefully version control the generated code.

But that's completely backwards! We're discarding the specification (the source) while meticulously maintaining the implementation (the binary). The prompts contain all the valuable intent and should be preserved as living specifications. Without them, we're just operating on vague vibes instead of precise requirements that can be validated, versioned, and improved over time.

I felt called out, honestly.

Why Specifications Are Actually More Important Than Code

The speaker made a compelling case that I hadn't fully considered before. Written specifications align humans on shared goals—they get everyone on the same page. Code is actually a lossy projection from specifications; it's missing all the intent and values that motivated the design decisions in the first place.

Here's what really got me: a good specification can target multiple outputs. The same spec could generate TypeScript, Rust, server code, client apps, documentation, tutorials, educational content—you name it. Specifications contain enough information to generate artifacts for any target architecture. They're the universal source of truth.

That's... actually pretty powerful when you think about it.

Real-World Example: The OpenAI Model Spec

I found the real-world example really helpful for understanding this. The speaker walked through OpenAI's Model Spec, which demonstrates specification-driven development at scale. It's implemented as versioned markdown files that express intentions and values for how models should behave, all in human-readable format.

What I thought was clever: this enables contributions from all kinds of people—product managers, legal teams, safety researchers, policy experts—not just engineers. You don't need to code to contribute to the spec.

Each clause in the specification gets a unique identifier (like "Sy73") that links to challenging prompts serving as success criteria. So the structure encodes both the policy AND the test cases in a single document. It's like executable specifications that define expected behavior and validate implementations at the same time.

The Sycophancy Bug Story

The speaker shared this fascinating case study about GPT-4. Apparently, an update introduced extreme sycophancy (basically, the model agreeing with users way too much), which eroded user trust. But here's the thing: the Model Spec had contained a "don't be sycophantic" clause since release.

That specification provided a trust anchor to identify the gap between what was specified and what was actually happening. Because the spec explicitly prohibited sycophancy, the behavior was classified as a bug rather than an intentional design choice. OpenAI rolled it back, published their analysis, and implemented fixes.

The specification enabled clear communication about expectations: while sycophancy might feel good in the short term, it damages long-term relationships with users. Having that written down made all the difference.

Getting Models to Actually Follow Specs

This is where it gets technical but stay with me because it's cool. The speaker explained something called "deliberative alignment"—basically, how to get models to align with specifications through an executable process.

Here's how it works: you combine the specification with challenging prompts, sample responses from the model you're testing, use a grader model to score how well responses align with the spec clauses, then apply reinforcement based on those alignment scores.

The clever part? This embeds the policy into the model's weights as "muscle memory" rather than having to enforce it through system messages at inference time. Moving policy from inference-time compute into the weights frees up computational resources to actually solve user problems instead of continuously enforcing behavioral constraints. The specification serves double duty as both training material and evaluation criteria.

We Need Better Tools for Specifications

The speaker argued that specifications have code-like properties—they compose, execute, support testing, define interfaces, and can be shipped as modules. So we need tooling similar to what we have for software development:

This toolchain would target intentions and values rather than syntax. I found myself nodding along—we really do need this kind of rigorous specification engineering.

This Pattern Is Everywhere

Here's where the speaker really expanded my thinking. This specification pattern extends way beyond software. They used the US Constitution as an example—it functions as a national model specification with clear policy, versioned amendments, and judicial review acting as a grader evaluating alignment. Legal precedents serve as input-output test cases that disambiguate policy. Chain of command and enforcement mechanisms create training loops aligning human behavior to shared values.

When you think about it: programmers align silicon through code specifications, product managers align teams through product specifications, lawmakers align societies through legal specifications. And anyone prompting AI models? They're already a proto-specification author, whether they realize it or not.

That last point hit me—I'm already doing this, just not very well yet.

The Big Shift That's Happening

The speaker's core argument is that software engineering has never fundamentally been about code—it's about precise exploration by humans of software solutions to human problems. We're transitioning from disparate machine encodings (programming languages optimized for compilers) to unified human encoding (specifications optimized for human understanding and AI interpretation).

The scarce skill is becoming the ability to write specifications that fully capture intent and values. Mastering specification authorship will define the most valuable programmer in the AI era.

I loved this closing thought: future development environments might evolve into "Integrated Thought Clarifiers" that extract ambiguity and crystallize intent, rather than traditional IDEs focused on syntax and compilation. How cool would that be?

My Takeaway

As code generation becomes commoditized (and it clearly is), specification authorship is emerging as the critical programming discipline. Specifications preserve intent, align stakeholders, generate multiple artifacts, and serve as executable policy for both human and AI systems.

I'm still processing all this, but I think the future of programming really is specification-first. Time to start treating my prompts and requirements docs with a lot more respect—and maybe actually version controlling them properly.

Anyone else thinking about this? I'd love to hear if you're already working this way or if this feels as much like a paradigm shift to you as it does to me.