Why did spec-driven development never take off - the workflow tools like Amazon’s Kiro or GitHub Workspaces encouraged? dex, founder of HumanLayer: “These projects have a really interesting idea: you maintain a set of specifications for your software, and then you maintain the code itself, and the dream is... the coding part is just compiling specs into code. But that part never really materialized. I’m on a GitHub issue in spec kit that’s been open for a year, and every couple of weeks I get a new email on the thread of people complaining about the same problem: I edit my specs and then I edit the code, and the code drifts from the specs. How do I keep the specs up to date as the code is changing? You now have two sources of truth, and it stops being useful. That’s why with RPI (Research, Plan, Implement), the docs are tactical execution docs - I do the research, the plan, the implementation, and I throw the docs out. The next time I need research I just do it from scratch, because tokens are cheap and my time is expensive.”show more

Learn more about context engineering, loop engineering and how Dex Horthy’s approach to AI-assisted software has evolved, on The Pragmatic Engineer podcast • YouTube: • Spotify: • Apple: • Summary and transcript:

Excellent point here @dexhorthy . Where I think spec driven works is if you view SDD like jira or linear. feature => story with a tech design doc targetted for a feature. Feature is your functional spec. Tech Design is your program design and Story/Issue is your plan for constructing and verifying. You don't attempt to keep your features and story/issues in sync with your app. No one expects that. Jettison the spec as source code idea, and embrace it as a way of generating better features and issues that are streamlined for execution. But you still let them roll off naturally. This approach is the one that is most likely to get traction with enterprise teams filled with people who aren't on the cutting edge AI train. This is how I'm getting my enterprise teams with good but not cutting edge ai programmers and ba's and po's to get acceleration across the team

I solved this problem. But you are not gonna like the answer. You have to read the code. What is different about my research project is that I know why failed and I'm not gonna repeat this mistake. You can't generate code from specs because English semantics are very different from Code semantics. It's like trying to describe 3D model using words. You can easily describe sphere, cube, pyramid. But try describing a human or a car engine. That quickly becomes a nightmare. So I understand these are two separate semantic graphs, and I am deliberately separating them, but also connecting. How? Simple. We just make specs granular enough: states + state transitions: - Entity exists with these attributes: a=x, b=y, c=z. - Entity transitions from state A to state B. And then single acceptance criteria is just one state transition or one state measurement. And so that means one test. It can be contract, integration, unit, e2e test. We link it. BAM. Product spec exists, you read it, you understand it, you built mental model in your head. Go read the test now. Does it do same thing as product spec does? That's tricky to verify, because you need to launch the test and see what changed on every single step: DB record, component input, HTTP request, and so on. If you verified this and it works as expected, then this spec is valid, and you can forget about it, until code that is connected to it changes. How do we know when spec is stale? Simple. SCIP graph connects test file to your models, classes, services, even cross-repo. Something changes in other repository that connects to this test -> BAM, GO READ SPEC YOU JUST TOUCHED. This is hard research project. I've been doing this all by myself. No funding. And my next step is to visualize mental model when you write the intent graph. The bottleneck is understanding. When you create spec, you have to load mental model in your head. That's exhausting and unproductive if you don't read code. So my solution is to pull the minimal code you have to read, and minimal context you need to understand the feature you are working on. Here's example: ALSA driver / USB / microphone / application vertical slice. This is much easier to understand than reading a manual or even reading code. Yet you see that these structures is literally code, just rendered as HTML components, and you can play with them. That's how I plan to reduce cognitive bottleneck when writing software and understanding what it does. And it can be used outside of Software too. Biology, Laws, Physics, Science. Anything.

@dexhorthy You have to define spec-driven development. I believe everyone is using some kind of specs with AI coding. Specs go out of sync with code, sure, that is a problem to solve, but how else do you communicate with agents if not through specs?

@dexhorthy The funniest part about this is that Amazon hard mandates this bs when using tools other than Kiro too

@dexhorthy good addition here:

@dexhorthy turns out writing perfect specs is harder than actually writing the damn code 🤷‍♂️

@dexhorthy @dexhorthy so you just don’t have docs of the projects? Not even ADR? (Didn’t listen to the podcast)

@dexhorthy If you have no written specs and if the coding agent doesn’t use the spec as system functionality, then nothing stops it from changing any rule and policy and there’s no real way to limit the code output.

@dexhorthy Curious to hear @dexhorthy’s thoughts on

@dexhorthy the spec the spec the spec the fucking spec which it kinda forgets to follow? I was fast, by the time i write the spec i would have finished whole poc, i was using AI and enhanced my speed as well, then fall for this spec driven development bullshit

@dexhorthy hell yeah

@dexhorthy Our tools that can help to save the time for the journey of content creators.we call it's an Ai powered time saving time tools. I don't have traction and not too much followers on X. If u like it then u please use and feature it on X.

@dexhorthy Spec drift is real, but tactical plans and durable obligations are different. Plans can be discarded. Requirements, invariants, guarantees, and architecture boundaries can't be reliably recovered from code. Keep that authoritative layer machine-checkable.

@dexhorthy Specs are just docs that pretend they'll stay current

@dexhorthy Precommit hooke are easy enough to trigger documentation writers.

@dexhorthy i dropped spec driven workflows when specs drifted faster than code reviews caught them

@dexhorthy Ya. Detailed initial definition of what to build is important but don’t be dogmatic about specs Amazon being overly dogmatic and wrong about this is so onbrand

@dexhorthy Missing the obvious: 1. You rev your spec and command - now update the code to do this spec change. 2. If your code drifts, you have no idea if the code drifted correctly or incorrectly. 3. Top down specs give the agent the skills to understand the broader context.

@dexhorthy "Because tokens are cheap" I do agree with the other part, though.

@dexhorthy The problem described above is more about the full SDLC and not about SDD. What's missing from SDD here is getting past build time verification alone to where you can enforce behavior into your CI system so it acts as enforcement going forward. There's a similar need at runtime

@dexhorthy I argue we can (as I do) non-drifting spec if we clearly distinguish short term « ChangeSpec » and long term « ReqSpec »

@dexhorthy Because most specs are designed to make it easier for a human to implement and manage, and llms don't have that same hang up.

@dexhorthy What stands out to me is that documentation doesn't fail because it's written. It fails when it becomes a second version of reality. Trust usually comes from having one source of truth, not two.