How SDD helps in real world software engineering?
Stop “prompting and praying” through brownfield projects. It’s time to move from Vibe Coding to Spec-Driven Development.
The Day the Vibe Fails
Imagine this: It’s 4 PM on a Friday. You’re using a top-tier AI coding assistant to refactor a legacy authentication module. You give it a simple prompt:
Update the login logic to support JWT instead of session cookies.
The AI responds instantly. It generates 200 lines of flawless-looking TypeScript. You skim it. It uses modern libraries, it’s clean, and it even adds comments. You hit “Apply” the linter passes, and you push to staging.
Ten minutes later, the “Vibe” fails.
The staging server is throwing 500 errors. Why? Because the AI didn’t know that three layers deep in your `utils/db.js` file, there’s a legacy decorator that expects a session object to be present on the global request. The code was “perfect” but it was **architecturally incompatible** with your specific history.
This is the failure of Vibe Coding.
The Greenfield Illusion vs. The Brownfield Reality
We’ve all seen the demos. An AI agent builds a Todo app from scratch in 30 seconds. It’s magical. It’s effortless. It’s Greenfield. But for 99% of professional engineers, the reality is different.
We don’t build Todo apps; we maintain 5-year-old monoliths, fix bugs in distributed systems, and refactor “spaghetti” code that no one on the current team actually wrote. This is Brownfield development — an “ambiguity engine” where:
Context Blindness: The AI sees the file you’re working on, but it’s blind to the implicit “handshakes” happening in your `node_modules` or your legacy database schema.
Technical Debt Hallucinations: The AI suggests `fetch()` because it’s modern, but your system is hard-wired to an old version of `axios` with custom interceptors.
The Entanglement Problem: In legacy systems, “simple” changes have a high “blast radius.” AI tends to propose optimistic, localized fixes that ignore the systemic impact.
The “Vibe Coding” Trap
The industry has fallen in love with “Vibe Coding” — the practice of relying on intuition, shortcuts, and “feeling” your way through a prompt. It’s approachable and fast, but it’s the antithesis of engineering.
Vibe coding treats AI as a magic box. You pour prompts in, hope for code out. When it fails, you blame the AI. But in a brownfield project, vibe coding is a disaster. The AI doesn’t know your naming conventions, your test framework, or which files are still in use, and which are technical debt waiting for retirement.
Are you Vibe Coding? (The Red Flags)
- You spend more time “correcting” the AI than writing code.
- You find yourself saying “Wait, why did it change *that* file?”
- Your PR reviews are dominated by comments about “breaking existing behavior.”
- You feel like you’re “fighting” the assistant to respect your project’s structure.
The Solution: Spec-Driven Development (SDD)
What if specifications weren’t an afterthought, but the driver of development? Spec-Driven Development (SDD) inverts the power structure. In SDD, specifications don’t guide code — they generate it.
Introducing SpecPack
SpecPack is a pragmatic, git-friendly CLI designed to bridge the gap between AI speed and engineering rigor. It’s a fork of the GitHub Spec-Kit, specifically re-engineered for the complexities of real-world “messy” codebases.
How SpecPack Fixes the Gap
SpecPack doesn’t just “talk” to AI; it provides a structured environment for it to work within.
I. Brownfield Profiling (The AI’s Map)
Before the AI writes a single line of code, SpecPack runs a Codebase Profile. It doesn’t just read files; it identifies:
Implicit Conventions: Do you use Tab or Spaces? Functional or Class-based components?
Dependency Constraints: What versions are actually locked in your `package.json`?
Logic Patterns: How does the system handle errors? Where does logging happen?
II. Progressive Parallel Validation
Standard CI is too slow for the AI era. If you have to wait 10 minutes for a test suite to run every time the AI makes a change, you lose the “flow.”
SpecPack uses **Progressive Parallel Validation**. It breaks your specification into atomic tasks and validates only the “Delta” — the specific surface area being touched — in parallel. You get a “green light” on the architecture in seconds, not minutes.
III. Delta Tracking
In legacy systems, knowing what *didn’t* change is as important as knowing what *did*. SpecPack tracks the Delta across your Spec, Plan, and Tasks:
[ADDED] New `auth.verify()` method.
[MODIFIED] `user.login()` now returns a Promise.
[UNCHANGED] The encryption salt logic (High Risk — DO NOT TOUCH).
IV. Feature Archiving
In 6 months, when a bug appears, no one remembers why the AI made a specific architectural choice. SpecPack solves this with Feature Archiving.
Once a feature is validated, SpecPack generates an Audit Trail that captures the original Spec, the Implemention Plan, and the exact validation results (including performance baselines) at the time of merge.
It turns your specs/archive folder into a searchable knowledge base of why your system evolved the way it did.
Quickstart
Stop “vibing” and start engineering. Here is how you bootstrap a spec-first workflow:
1. Initialize SpecPack in your project
uv tool install specpack-cli
specify init . — ai claude
2. In your AI agent, profile the codebase
/specpack.analyse-codebase
3. Write your feature specification
/specpack.specify
4. Generate the plan and stub tests
/specpack.plan
/specpack.tasks
5. Confirm stubs are failing (RED), then implement
/specpack.validate-stubs
/specpack.implement
The Bottom Line
AI coding agents are powerful, but they need guardrails to succeed in real-world engineering. They fail when we lack specificity.
The future of software development isn’t “prompt and pray” It’s specify, validate, ship. SpecPack gives you the toolbox to make that a reality, even in your messiest legacy repositories.
Take back control of your codebase. Stop the vibes. Start the specs.
👉 Explore more about SpecPack on GitHub
Beyond Prompting: Spec-Driven Development was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.