0:01AI agents are writing more and more of your code every month.
0:04So here's an interesting thought experiment.
0:06Take your most recent project.
0:08Now go to your source folder.
0:10And, just delete it.
0:13All the code. Gone.
0:15The only thing left, are the docs and specs.
0:18Now point an AI assistant at what remains.
0:21Can it reconstruct the application?
0:24What will you get?
0:26Are you thinking, "yeah, no big deal."?
0:29Or does your stomach drop at the thought?
0:31For most teams today, that second reaction is the honest one.
0:36Here's why that reaction matters.
0:38We spend years maintaining old implementations.
0:40Patching legacy code. Running migrations. Carrying forward decisions that made sense three years ago.
0:46But if agents can reliably rebuild the code from clear intent, then maybe code stops being the thing we preserve.
0:52Maybe the durable artifact is the "INTENT" behind it.
0:57So this is the shift we’re going to make concrete. Code is becoming easier to regenerate.
1:02So the thing that matters most is the thing you regenerate it from.
1:05The "spec" is becoming the source of truth.
1:09Let's go back to our thought experiment.
1:11If that thought experiment feels reckless, there's a reason.
1:14Most of the knowledge needed to rebuild your system was never fully written down.
1:18It lives in people's heads.
1:19It lives in old code paths.
1:21It lives in production incidents, Slack threads, and assumptions that never made it into any document.
1:26The intent was never fully captured in the first place.
1:29So what would it take to actually capture that intent?
1:34Take a simple requirement. Add Role based access control.
1:38Sounds clear. But a requirement like this hides a dozen decisions.
1:42What is a role exactly? Who can assign one? What wins when permissions conflict?
1:47Every unanswered question is a place where the agent has to guess.
1:50That's what the Intent Stack is for - answering them up front.
1:55Start with the outcome. What should be true when this feature works?
1:58Define the language. Words like “role,” “permission,” and “resource” need to mean one thing.
2:06Capture the behavior. What should the system actually do?
2:09Then lock down the constraints. What must it never do?
2:13Define the interfaces. Where does this feature touch the rest of the system?
2:17Add examples. Show what it actually looks like in practice.
2:21And finally, acceptance criteria.
2:23What has to be true before the work counts as done?
2:26Together, these layers form what we'll call the Intent Stack.
2:29And when the intent is clear, code becomes what it was always heading toward - a compiled artifact. Generated from intent. Regenerated when intent changes.
2:41At this point you're probably pushing back.
2:43There is no way to reproduce our entire codebase from specs. Not the way it exists today. Not with every edge case, historical decision, and production scar baked into it.
2:54And we couldn't possibly know every spec up front. Some things only reveal themselves during implementation. Some only reveal themselves when users touch the system.
3:04Yes. So let's talk about that.
3:08Let's clarify this first - the goal is not to reproduce the exact same codebase. It never needed to be.
3:13If four capable teams built the same feature from the same spec, you'd get four different implementations, all of them correct.
3:20Your current codebase is just one valid implementation. What you actually want is functional reproducibility. Not the same code. The same intended behavior.
3:30A good spec doesn't force one answer. It defines what must be true.
3:34So when we return to the thought experiment, this is the answer.
3:37If the source folder disappears, the goal is not to bring back the old code.
3:41It is to preserve what the code was supposed to mean.
3:45Okay, so does this mean we start writing down detailed specs for our codebase?
3:50To be honest, most teams should not try full spec-as-source tomorrow. Nobody's stopping all work to document everything you've already built.
3:57The practical version is smaller.
3:58Most teams already have fragments of an Intent Stack -you have schemas, policies, runbooks, agent files.
4:06So just start with the next change you are implementing.
4:09A new feature tells you what behavior the system now needs to support.
4:12A bug fix reveals an edge case your intent never captured.
4:16A production incident exposes an assumption the system was relying on.
4:20Over time, each change leaves behind more than code. It leaves behind clearer intent.
4:26That's how a mature codebase starts moving toward spec-as-source. By making sure every meaningful change leaves the spec stronger than it found it.
4:36Fred Brooks said it in 1987 - the hardest part of building a system is deciding precisely what to build.
4:41He was right. We just spent forty years pretending implementation was the hard part because implementation was where all the time went.
4:48Now the time is shifting. The hard part is finally where the value is, the "Intent".
4:52And the biggest opportunity now is to become the person who makes that intent clear.

Specs Are the New Source Code

Created by Abhyuday DesaiPublished 2 Oct, v1Runs 5 min 10 sec

0 views

About this video

Delete your source folder and keep only the docs and specs. Could an AI assistant rebuild the project from what remains? Episode 3 argues that as implementation gets cheap, ambiguity gets expensive, introduces the Intent Stack for layering what a system must do, uses the score versus screenplay comparison to judge how much detail a spec needs, and shows how specs become the system's memory over time. It closes with three practical moves for Monday and a bridge to system design.

What changed

v102 Oct 2026abhydesai5 min 10 sec

First published version.

0 views0 likes on this version