The Framework Trap

The numbers: Spec Kit (50k stars), BMAD (30k), Claude Flow (12k), GSD (7.5k), SuperClaude (6k). Amazon shipped an entire IDE. Combined: over 100k GitHub stars in months, each promising to bring order to AI-assisted development.

The pattern across all of them: phases, gates, personas, commands. Specify, Plan, Tasks, Implement. Analyst agent, PM agent, Architect agent, Developer agent, QA agent. It maps perfectly to how software has always been built.

It’s waterfall with a language model bolted on.

The Proliferation

Every dev paradigm speed-runs this phase:

• Rails spawned 100 gems before “convention over configuration” won
• jQuery gave way to Backbone, Angular, Ember before React settled it
• Node produced Express, Koa, Hapi, Restify before Express won by being minimal
• React state cycled through Flux, Redux, MobX, Recoil before hooks absorbed the pattern

Claude Code’s turn. Spec Kit adds four gated specification phases. BMAD adds 19 agents mapping to traditional SDLC roles. GSD enforces max-3-task plans in fresh sub-agent windows. SuperClaude adds 19 commands and 9 cognitive personas. Kiro bakes phase gates directly into an IDE.

100k stars doesn’t mean 100k developers shipping better code. It means 100k developers looking for structure in a paradigm that hasn’t settled yet.

Big Design Up Front has proven to fail most of the time because it piles up hypotheses. Software development is fundamentally a non-deterministic process, so planning doesn’t eliminate uncertainty.

— Marmelab, 'Spec-Driven Development: The Waterfall Strikes Back'

What They Get Right

The impulse is correct. Vibe coding produces garbage on complex projects. Unstructured prompting leads to context rot, architectural drift, and code that works in isolation but collapses when integrated.

Spec-first thinking is genuinely valuable. Planning before executing is valuable. Verifying output is valuable.

The diagnosis is right. The prescription is wrong.

The Waterfall Boomerang

Spec Kit’s four phases (Specify, Plan, Tasks, Implement) are waterfall stages renamed. BMAD’s 19 agents are an org chart. Kiro’s hooks are phase gates.

These structures existed because humans have limited context and expensive coordination. A PM holds maybe 50 requirements in working memory. Handoffs between specialists lose information. Synchronization across a team costs meetings, documents, and calendar invites.

AI has neither constraint. A model holds 200k tokens of context. It doesn’t lose information in handoffs to itself. It doesn’t need a standup to synchronize.

So why are we reimporting the scaffolding designed to compensate for human limits?

Scott Logic’s hands-on review of Spec Kit found exactly this: “a sea of markdown documents, long agent run-times and unexpected friction.” The AI “creates detail that fundamentally lacks depth of value.” Faux context that consumes tokens without adding information.

Against the Grain

Here’s the argument nobody’s making: LLMs are trained on conversational data and code. Not multi-phase planning documents with persona handoffs. Not specification workflows with gate reviews. Not agent orchestration protocols.

When you force a language model through a 19-agent pipeline with role-specific system prompts, you’re fighting its training distribution. The model performs best when given clear context and conversational instruction. Every layer of framework ceremony pushes further from what the model actually learned to do well.

Process overhead designed to make AI productive reduces AI effectiveness. The irony is structural, not incidental.

I tend to lean towards them being snake oil. A lot of process and ritual around using them, but for what? I don’t think the models themselves are a good fit for the way these frameworks are being used. It probably goes against their training.

— Hacker News discussion on AI framework proliferation

Microsoft’s defense of SDD tried to distance it from waterfall: “SDD is about making your technical decisions explicit, reviewable, and evolvable.” But Marmelab’s counter lands harder: “Developers haven’t been mere executors for a long time.” The premise that specs should drive development assumes a separation between thinking and building that AI collapses entirely.

The Predictable Cycle

The pattern repeats because the incentives repeat. New paradigm creates uncertainty. Developers reach for familiar structures. Frameworks multiply. Then the ecosystem matures and the simple approach wins.

• CGI to PHP frameworks to Rails: Convention over configuration won
• jQuery plugins to MV* frameworks to React: Component model won
• Express/Koa/Hapi: Minimal middleware won
• Flux/Redux/MobX to hooks: Native integration won

We’re in the proliferation phase for AI coding tools. The 100k+ stars will consolidate. What survives will look like CLAUDE.md and native tooling - not 19 agents and four gated phases. The scaffolding becomes native. The platform absorbs the patterns.

What Actually Wins

Anthropic’s own guidance: “Keep CLAUDE.md files concise and human-readable.” And: “A common mistake is adding extensive content without iterating on its effectiveness.”

The minimalist stack that works:

• CLAUDE.md under 300 lines. Focused rules, not comprehensive specifications. A “do not repeat” ledger, not a process manual.
• Plan Mode. Built into Claude Code. Conversational, iterative, matches the model’s training distribution.
• Verification loops. Tests, type checkers, linters. Give the model a way to check its own work.
• Path-specific rules. Directory-scoped instructions in settings instead of global persona systems.

The framework trap isn’t that frameworks exist. It’s that they feel productive while adding friction.

A year from now, the surviving patterns will be the simple ones. They always are.