A practitioner’s guide to the new agentic development frameworks, and an honest look at whether the specs are worth it.

It was a Saturday night, and I was looking at a Word document older than my youngest kid.

For years I’ve helped run a large swim meet. Hundreds of kids, heat sheets, ribbons sorted into little labeled envelopes, and at the end of it a team trophy that comes down to a points calculation nobody fully remembers how to do. The institutional knowledge lives in one document and an Excel spreadsheet, written more than a decade ago, that explains how to build the divisions, print the award labels, and tally the team points. Every year for the last six years I followed it, clicking through a desktop program from another era, exporting, re-importing, squinting at columns. It takes patience, and it feels like forever with a crowd of kids waiting on their medals, staring at you. It’s the kind of repeatable, fiddly, rules-heavy work software was supposed to have eaten long ago.

So that night I opened Claude Code and started talking.

I didn’t write a spec. Didn’t interview myself about edge cases, didn’t draft acceptance criteria in EARS notation. I described the trophy problem, pasted in the relevant chunk of the ancient document, and let the model hallucinate its way toward a website. It guessed at the data model. It guessed wrong a few times. I fixed it by looking at what came out. The division boundaries were off, so I said so. The PDF labels printed two millimeters past the margin, so I nudged them. We went in circles like that for a few hours. By the time I went to bed I had a working app that ingested the results, built the divisions, generated print-ready award PDFs, and spit out the team points. It ran overnight. It worked.

Here’s the uncomfortable part. Almost everything I just did is what an entire emerging discipline, “spec-driven development,” is now built to prevent.

If you haven’t been watching this corner of the industry, the speed of it is genuinely hard to track. A March 2026 survey mapped more than thirty agentic coding frameworks and sorted them into four layers: spec frameworks that generate the planning documents, task systems that turn those documents into work graphs, execution agents that coordinate the actual coding, and the AI-native IDEs that wrap the whole thing. The center of gravity, the part everyone’s arguing about, is that first layer. The spec.

The shared premise is simple. Letting a model jump straight to code, the argument goes, produces code that solves the wrong problem. Anthropic says it plainly in their own best-practices guide: “Letting Claude jump straight to coding can produce code that solves the wrong problem.” So you front-load the thinking. You write down what you want, precisely, and the spec becomes the thing the agent reads, builds from, and is checked against.

The frameworks differ mostly in how much ceremony they wrap around that idea, and they range from cathedral-heavy to almost weightless.

BMAD is the cathedral. The Breakthrough Method for Agile AI-Driven Development runs twenty-one agent personas in sequence: an Analyst interviews you, a Product Manager writes the PRD, an Architect picks the stack, a Scrum Master shards all of it into story files, and only then does a Developer agent start typing, allowed to see one story at a time. Its creator, Brian Madison, is proud of the weight. “I don’t consider BMad vibe coding,” he says. “I think of it as the antithesis of vibe coding because you’re actually putting some thought in working with a plan.”

A step lighter, GitHub’s Spec Kit marches you through a fixed pipeline (a project “constitution,” then /specify, /plan, /tasks, /implement), treating the spec, in GitHub’s words, as “a contract for how your code should behave.” AWS Kiro borrows the rigor of safety-critical engineering, writing requirements in a formal notation that came out of Rolls-Royce and firing background agents every time you hit save. LID, Linked-Intent Development, is the reaction against all that weight: one lean chain from intent down to code, organized around a single sharp idea it calls the “Intent Gap,” the distance between what you wanted and what the agent assumed you meant. LID claims you should be able to delete all your code and regenerate it from the specs.

And then there’s Tessl, which takes the premise to its logical end and turns it into a $125-million company. Tessl wants the spec to be the source code. The code it generates comes stamped // GENERATED FROM SPEC - DO NOT EDIT, like a receipt you’re not supposed to touch.

The frameworks are only half the picture. The other half is how working engineers actually drive these tools day to day, and there the spectrum runs from “forget the code exists” to “the test is the only thing standing between you and disaster.”

At the loose end is vibe coding, the term Andrej Karpathy coined in February 2025 for the practice of fully giving in to the vibes and forgetting the code even exists. It became Collins Dictionary’s word of the year. At the disciplined-but-fast end is Geoffrey Huntley’s “Ralph” technique, which in its purest form is a bash loop feeding the same prompt to Claude Code over and over: while :; do cat PROMPT.md | claude-code; done. Huntley’s view is that bad output is operator error, because “LLMs are mirrors of operator skill.”

Toward the middle, Harper Reed runs a fifteen-minute ritual that turns an idea into a spec.md and then a prompt_plan.md before any code gets written. Armin Ronacher, who created Flask, runs Claude Code nearly hands-off inside a Docker sandbox and optimizes everything for the agent, preferring “the dumbest possible thing that will work.” Simon Willison draws the cleanest line in the discourse: vibe coding means you don’t read the diff, and agentic engineering means you do, because “writing code is cheap now” and the scarce thing is judgment. Kent Beck, who has been doing test-first development longer than most of these tools have existed, found that the agent actively resists it: “The genie doesn’t want to do TDD. It wants to write the code and then write tests that pass.” He has watched models delete failing tests to make the suite go green.

Map all of them onto a single axis from speed to spec and almost nobody’s at the extremes. The interesting people are in the middle, fighting about exactly how much structure is worth it.

I came into this biased, and I want to represent the other side as well as I can before I argue with it, because the steelman is better than I expected.

The sharpest version comes from Sean Grove of OpenAI, in a 2025 talk called “The New Code.” His argument is that when you prompt a model, get code, keep the code, and throw away the prompt, you’re doing something backwards. You’re version-controlling the binary and shredding the source. The spec is the source. It holds the intent, the constraints, the decisions; the code is just one compilation of it. OpenAI lives this internally, where their model spec is a document in which every clause has a unique ID linked to test prompts.

The second argument is about memory. Context windows are finite, sessions reset, agents get swapped. A spec survives all of that in a way that a chat history and a pile of code comments don’t. Anthropic’s own framing, echoed in a DeepLearning.AI course on the topic, is that specs “preserve context across agent sessions, reduce cognitive debt, and improve intent fidelity.”

The third argument is the one that lands hardest for anyone who has shipped real systems, and it’s the reason I can’t wave the whole movement away. Specs exist to remove variability. We’ve had spec-driven code generation for decades and it works beautifully: you write a Protobuf schema, run the generator, and get exactly the same code on every machine, every time, forever. The code is a pure function of the spec, which is precisely why you trust generated code you never read. LLMs throw that determinism out. Give a model the same requirements twice and you get two different implementations. Both might be correct. Neither is the same. The code is no longer a function of the spec, it’s one sample from a distribution of solutions that satisfy it. For most of what I build, I don’t care which sample I drew. But when the outcome has to be identical and provable rather than merely equivalent, the spec and its tests are the only thing pinning the variance down, because the code underneath stopped being stable.

I believe all three of those things are real cases to consider.

Start with the lineage, because the “let the code be the answer” position isn’t a 2026 invention by people too lazy to write docs. It’s one of the oldest serious ideas in software engineering.

In 1985 Peter Naur wrote “Programming as Theory Building,” arguing that a program isn’t its source code or its documentation. It’s a theory living in the minds of the people who built it, and “reestablishing the theory of a program merely from the documentation is strictly impossible.” In 1992 Jack Reeves argued that the source code is the design: traditional engineers produce design documents and hand them to a factory, but software developers hand source code to a compiler, so the code isn’t the construction, it’s the design itself. “It is cheaper and simpler to just build the design and test it than to do anything else.”

Even waterfall gets this wrong. The 1970 paper everyone cites as the birth of big-design-up-front actually warned against it. Its author, Winston Royce, laid out the rigid do-everything-in-order model and then said plainly that building software that way was risky and invited failure. The industry spent the next fifty years enshrining his diagram and ignoring his warning.

The modern version of this skepticism is David Heinemeier Hansson, the creator of Ruby on Rails who writes as DHH, and he put it about as sharply as it can be put: “What you asked for before you began building was based on the absolute worst understanding of the problem.” You learn the real shape of the thing by building a wrong version and looking at what you got. My swim-meet app is small, literal proof of that. I didn’t know the right division boundaries until I saw the wrong ones on screen. The spec was discovered, not specified.

Elon Musk gave the builder’s version of this on Lex Fridman’s podcast, an engineering algorithm he says he runs “as a mantra.” Step one is to “make the requirements less dumb,” because “the requirements are always dumb to some degree, no matter how smart the person who gave you those requirements,” and the trap is getting “the perfect answer to the wrong question.” The part that should worry the framework vendors is the order he puts things in. You delete and simplify first, and you automate dead last, because “the most common mistake of smart engineers is to optimize a thing that should not exist.” A twenty-one-agent pipeline that turns a PRD into sharded story files is automation bolted onto a process nobody stopped to try deleting first.

And Karpathy, the same person who coined vibe coding, drew the line that I think actually matters in the agent era: “Traditional computers automate what you can specify in code. This latest round of LLMs can automate what you can verify.” That’s the whole argument in one sentence. When code generation is nearly free, the bottleneck moves from specification to verification. The test, the screenshot, the end user squinting at the output and saying “no, the points are off here,” becomes the real source of truth. A spec that disagrees with the running code isn’t a safety net. It’s false confidence, that’s all it is. As Ron Jeffries likes to say, “code never lies, comments sometimes do.”

There’s a scene in Tommy Boy where a guy wants a guarantee, and Chris Farley tells him exactly what one is worth: “Hey, if you want me to take a dump in a box and mark it guaranteed, I will. I got spare time.” The sticker on the box is there to make you feel all warm and toasty inside. The thing inside the box is either good or it isn’t. A spec is the guarantee on the box. The running code is what’s actually in the box, and the user lifting the lid is the only one who ever finds out which.

I’m not going to leave that as a vibe. The numbers that matter fit in your head.

The most rigorous study we have, METR’s 2025 randomized trial, put experienced developers on code they knew well and found they were 19 percent slower with AI tools. The kicker is that they were sure they’d been faster. Read it carefully (small sample, experts on mature code, not a weekend greenfield build like mine) and it’s a warning, not a verdict. But it’s a warning worth taping to your monitor.

The second number is organizational. The 2025 DORA research found AI makes individuals faster while making the system around them shakier: more bugs, slower reviews, a bigger blast radius when something breaks. DORA’s own one-liner is that AI is an amplifier, magnifying whatever your organization already is. Thoughtworks put it less diplomatically. Without the right structure, AI “simply becomes a faster way to create chaos.”

The third number is the bill, and it’s the one nobody warns you about. A single planning step in BMAD has been clocked at nearly 100,000 tokens before a line of code exists, and the heavyweight frameworks stack that cost up before you’ve got anything you can run. Speed has a meter running, and the cathedral runs it hot.

Now the other side of the ledger, because none of the above kills the case for specs. It just locates it.

Every one of those failure modes gets worse in exactly the environment where specs are mandatory anyway. In April 2026 the ACM’s technology policy council published a formal brief stating that AI-assisted coding “lacks key safeguards” and that safe use “still requires strong software engineering practices, including clear specifications, meaningful testing, and enforced standards.” At least 20 percent of vibe-coded applications, they note, contain security vulnerabilities. Martin Fowler’s site made the operational version of the point: “It is not sufficient to merely tell the LLM the desired behavior of your output artifacts. If you absolutely do not want something to be true, it must be codified in non-negotiable rules somewhere in your development lifecycle.”

In a regulated bank, a hospital, or anything touching SOX, HIPAA, or the EU AI Act, “I iterated until it looked right” isn’t an audit trail. Those regimes require traceability that ties a decision to an identifiable human and a documented rationale, and an informal loop simply can’t produce it. My swim meet has no auditor. A loan-decisioning system does.

So the spec isn’t ceremony everywhere. It’s ceremony in some places and a load-bearing control in others, and the skill is telling the two apart.

Here’s the part the frameworks never account for. Most of the code I touch, and most of the teams I sit on, live in the user experience layer. We build UI. We author APIs. Sure, some of that surface is binary and easy. The customer needs a capability exposed, the power user needs that knob for modeling, ship it. Those are the provable bits, and a spec serves them fine.

But that’s not the hard part, and it’s not most of the job. Most of the job is taste, and we work hard to pretend otherwise. We stare at page-load times, click-through rates, and scroll depth, and we call ourselves data driven. Then you walk through a museum and watch one person stop in front of a canvas the next person calls trash, and the pretense falls apart. The experience layer is art. We’re the mapmakers, and the job is to guide a human to the thing they came for. There’s no unit test for “this flow feels right.”

The manager wants an assembly line, a predictable and repeatable process, because that’s what software engineering trained all of us to want. Great software doesn’t come out that way. The process is messy. I’ve spent months wrestling a single page into shape, then watched the next one fall out in minutes because the flow was already there and the experience was simple. No spec written up front would’ve told me which page was going to be which.

So yes. Software is Art, at least in the corner I like to dabble in. There are provably correct systems underneath us too, and they’ve got their own tools. The whole trick is knowing which kind of problem is actually in front of you, then clearing away the dumb requirements until you can see it.

The piece of this I find hardest to settle isn’t about documents at all. It’s about people.

My swim-meet app had no product manager writing requirements, no designer mocking the PDF, no engineer translating either. It had me, sliding between all three roles at the speed of a chat window, because the cost of building had collapsed far enough that the handoff would’ve been the slowest part of the process. That makes the role-collapse thesis feel obviously true. When one person with an agent can cross the whole stack faster than three people can coordinate, the coordination is the tax.

The data partly backs this up. Analysts are watching the boundaries dissolve, with engineers making product calls and designers reaching into the code, and the academic reviews keep landing on the same conclusion: the scarce human skill is no longer writing code but judgment, knowing what to ask for and whether you actually got it.

But the same sources that back me also check me, and honesty means sitting with that. Accountability, the AllStacks analysis notes, “doesn’t automate away. It concentrates among fewer people with more leverage.” Conway’s Law doesn’t retire either. As the Team Topologies group put it, “an agent will not fix a messy organization; it will just scale it faster.” And against the headcount-compression story sits a stubborn data point: Tesla’s QA team grew 50 percent between 2020 and 2025 despite heavy automation. When generation gets cheap, verification doesn’t shrink. It grows. The roles that survive may be the ones pointed at the output, not the input.

So I land somewhere I didn’t expect when I started. The handoff-heavy, three-roles-and-a-PRD model really does look like a tax on the kind of work I did that Saturday night, and I wouldn’t give up that speed to get a spec I didn’t need. But the further the work gets from a swim meet and the closer it gets to a system where being wrong is expensive, the more those roles and those documents stop being friction and start being the point.

The frameworks are all answering the same question with different amounts of confidence: when the machine will write whatever you can describe, what’s worth writing down? Spec-as-source says everything. The outcomes camp says the code and the tests already are the writing, and the rest goes stale. I know which one I reached for at midnight with a trophy to award. I’m much less sure which one I’d reach for if the thing I was building could hurt someone. As Dirty Harry put it, a man’s got to know his limitations.

Here’s the rule I’ve landed on, and it has nothing to do with which camp is winning. Match the weight of your process to two things: how expensive it is to be wrong, and how cheaply you can find out.

When you can look at the output and know whether it’s right, go outcomes-first. Build the wrong version fast, run it, and let what comes out correct you. I could see the medals print and the points add up, so the running app was a better spec than any document I could’ve written first. Most of the software most of us write lives here, and we pretend it doesn’t.

In practice that’s less mystical than it sounds. I plan in Claude’s plan mode, talk through the approach, let it lay out the steps, and then I let the plan evaporate. What I keep, what I commit, are the tests. The tests are the verification of what actually got built, they live in the repo next to the code, and they break loudly the moment the code drifts away from them. Could I check the spec in too and keep a committed PRD in sync with the code and the tests? Sure. But then I’m maintaining three sources of truth instead of one, and the spec is the only one that can quietly lie while everything stays green. What is that third document actually buying me? Most days, nothing.

When being wrong is expensive and you can’t cheaply see it (a payment path, a database migration, a model that decides who gets a loan, anything a teammate or a regulator inherits long after you’ve forgotten how it works), write down the part you can’t verify by running it. That’s the honest job of a spec. Not to make you feel warm and toasty inside, but to carry the intent to the people and the moments your tests can’t reach.

So I don’t start with the spec. And I don’t skip it. I write exactly as much of it as I can’t test, and not one page more.

The frameworks and tools - “Spec-Driven Development Is Eating Software Engineering” (a map of 30+ frameworks) - Anthropic, Claude Code best practices - BMAD: interview with creator Brian Madison (Nearform) · token-cost issue #1235 - GitHub Spec Kit announcement - AWS Kiro - LID (Linked-Intent Development) - Tessl

How practitioners actually work - Andrej Karpathy coins “vibe coding” - Geoffrey Huntley, the “Ralph” technique - Harper Reed, my LLM codegen workflow - Armin Ronacher, agentic coding recommendations - Simon Willison, agentic engineering patterns - Kent Beck on TDD and AI agents (Pragmatic Engineer)

The case for specs - Sean Grove, “The New Code” (OpenAI) - DeepLearning.AI, Spec-Driven Development with Coding Agents - ACM Technology Policy Council, TechBrief on vibe coding - Martin Fowler, the VibeSec reckoning

The case for outcomes, and the data - Peter Naur, “Programming as Theory Building” (1985) - Jack Reeves, “What Is Software Design?” (1992) - Why waterfall was a misunderstanding: reading Royce’s 1970 paper - DHH, software estimates have never worked - Elon Musk’s 5-step engineering algorithm (via Lex Fridman) - Andrej Karpathy, Sequoia Ascent 2026 - METR, randomized trial on AI and experienced developers - DORA 2025, analyzed (Faros) · Thoughtworks 2025 DORA report - AllStacks, the 2030 software-engineering team - Team Topologies, when AI agents dominate

Originally published on LinkedIn.