It's 5 PM on the last working day before vacation. Your hand is already on the mouse, ready to bolt. Then your product manager appears: "Quick request—just add filtering and sorting to the user list. Super simple! The boss needs to show it to the client tomorrow."
You say "sure" while internally replaying eight hundred episodes of blood pressure drama. Whatever. Looks straightforward enough.
You open Cursor and type: "Implement filtering and sorting for the user list."
Three minutes. Literally three minutes, and AI spits out 200 lines of code. You click through a few test cases. Everything works.
In that moment, your internal monologue: This is amazing! This is the power of AI-assisted programming! You close your laptop and leave.
Then vacation ends.
New requirement arrives: "Let's add advanced filtering."
You confidently open that code and then—freeze.
data1, temp, result2... Did someone name these variables with their eyes closed? Nested if-else statements stacked like Russian dolls. Change the filtering logic, sorting breaks. Fix sorting, pagination crashes.
You spend an hour trying to understand all the branching logic. You can't.
Finally, you make the painful decision: this code has to go. You tear it down and rebuild from scratch. Two days later, you're done.
Three minutes to write. Two days to pay back the debt.
What Did AI Actually Steal From Us?
First: Code Quality Became a Lottery
The AI-generated code runs, but why does it run? No idea. Every generation is like pulling gacha—variable naming depends on AI's mood, architectural design relies on luck.
Initially it feels great, like ordering takeout—delicious, who cares if the kitchen is clean? The problem: technical debt compounds with interest that makes loan sharks look generous.
Second: We Became "Steering Wheel Anxiety Patients"
Simple tasks get fully delegated to AI—we just Ctrl+C/V. Complex architecture, we want AI to handle it but don't dare fully let go. You oscillate endlessly between "full autopilot" and "manual control," never finding the right moment to take over.
AI doesn't feel like a tool. It feels like an unreliable colleague—you never know what pit they're digging next.
Third: We're Losing Our "Architectural Intuition"
Notice anything? When receiving requirements now, your first reaction isn't "how should I design this?" but "let me ask AI."
It's like GPS addiction—use it enough and you can't even find your way to your own apartment complex without it.
I'm starting to fear: if this continues, will we devolve from "engineers" to "AI code couriers"?
So Is the Problem That AI Isn't Smart Enough?
Quite the opposite. AI is too powerful—so powerful we haven't learned how to work with it yet.
Remember: You Define the Problem
We need to clarify something fundamental: in the AI era, what is a programmer's real value?
AI is a tool with exceptional execution capability, but it's not the decision-maker. We understand business, judge value, and take responsibility for outcomes—this is our irreplaceable part.
The correct relationship: we decide "what to build" and "why build it." AI handles "how to build it."
Not us saying "build me a filter" and AI freestyling while we passively inherit the results.
This sounds like common sense, but increasingly few people operate this way. Notice the pattern? Development used to involve consulting documentation and prototype validation. Now with AI, we jump directly from vague requirements to code—the "intent distortion" is unrecognizable even to its own mother.
The root cause: we're missing an explicit specification.
Hello, Spec-Kit: Giving AI the Blueprint
GitHub recently launched a toolkit called Spec-Kit. After trying it, my biggest takeaway: pair programming with AI finally has a playbook.
The philosophy is direct: before writing code, clarify the specification. Like home renovation—you don't tell the contractor "just fix it up." You create design blueprints, plan electrical systems, specify materials.
That's exactly what Spec-Kit does. It doesn't replace AI; it makes AI more useful. According to GitHub, it integrates seamlessly with Copilot, Cursor, and Claude, helping you input more precisely so AI outputs more reliably.
The Spec-Kit Four-Step Workflow
Step 1: /specify — Don't Rush to Code, Talk First
Use natural language to explain what you need, where the boundaries are, and how it might evolve. AI helps organize this into structured specification documents.
Step 2: /plan — AI Proposes, You Approve
AI generates technical proposals based on specs: data models, design patterns, test cases. Remember: you review, you approve. You're not passively accepting.
Step 3: /tasks — Break It Down, One Step at a Time
Generate an executable task list—who does what, in what order. Crystal clear.
Recommendation: Use TDD—write tests first, implementation second.
Step 4: /implement — Dancing in Chains
AI writes code, but must stay within the framework of specifications and proposals. You maintain control. AI is the executor, not the designer.
What's the Biggest Difference From Vibe Coding?
Vibe Coding: "AI, build me a feature." → AI freestyles → You pray there are no bugs.
Spec-Kit: "Let me first clarify what I need." → AI follows blueprints → You supervise throughout.
The key question: who's defining the problem?
A Real Story: 30 Hours vs. 9 Hours
Consider a simple example: user permission management system. Initially requires two roles: admin and regular user. But real-world requirements inevitably evolve.
❌ Vibe Coding Approach
First version (2 hours): Tell AI "build a user permission system." AI generates a bunch of if (role === 'admin'). Tests pass. Shipped.
First iteration (4 hours): Need to add "reviewer" role. Looking at the code, I'm stunned—8 hardcoded locations! Should I patch it with || 'reviewer' or refactor? Nervously make changes, terrified of missing a spot.
Second iteration (24 hours—three full days!): Product wants "permission groups" support (one user, multiple roles). Discover the previous architecture used user.role (string), impossible to extend to user.roles (array). Complete rebuild required.
Total time: 30 hours.
Mental state: tortured with every iteration.
✅ Spec-Kit Approach
Step 1 (2 hours): Write specification + technical planning
User Permission Management Spec:
- Must support flexible extension—adding roles is inevitable
- Users can have multiple roles
- Permission checks can't be hardcoded—must be pluggable
- Handle no-permission and permission-conflict scenarios
AI proposes: Four tables (User, Role, Permission, UserRole), many-to-many relationships, strategy pattern for permission checks. I review and approve.
Step 2 (6 hours): Implement following task list with AI assistance
Initial version took 8 hours—6 hours slower than vibe coding. But the subsequent payoff:
First iteration (5 minutes): Add "reviewer"? Insert one row in the Role table. Zero code changes.
Second iteration (1 hour): Add "permission groups"? The architecture was already designed for this—just add a PermissionGroup table and associations.
Total time: 9.1 hours.
Mental state: calm, even anticipating the next requirement.
The Numbers Don't Lie
| Dimension | Vibe Coding | Spec-Kit | Difference |
|---|---|---|---|
| Initial velocity | 2h | 8h | 6h slower |
| First iteration | 4h | 0.1h | 3.9h faster |
| Second iteration | 24h (refactor) | 1h | 23h faster |
| Total time | 30h | 9.1h | Save 20.9h |
| Code quality | Drowning in debt | Clean architecture | Night and day |
| My mental state | Daily collapse | Calm confidence | Found joy in coding |
You see? Invest 6 extra hours upfront, save 21 hours later. "Slow is fast"—this is what it means.
How Did Spec-Kit Solve Those Three Problems?
About code quality:
Specifications are the blueprint. Variable names no longer arbitrary, logical structure guided by design patterns, edge cases covered by tests. AI becomes a chef who strictly follows recipes—consistent output, never crashes.
About human-AI collaboration:
Division of labor has never been this clear. I define business requirements, review proposals, make final decisions. AI proposes solutions, writes code, handles grunt work. I'm the director. AI is the cinematographer. I call the shots on how the scene plays.
About architectural capability:
Not only didn't it decline—it got stronger. Because every time I write specs, I'm forced to do requirements analysis. Every time I review proposals, I'm training architectural judgment. Every time I consider extensions, I'm cultivating foresight. AI became my "architecture sparring partner," not my "thinking replacement device."
Ready to Try? Three Steps to Get Started
Step 1: Installation (5 Minutes)
# Using uv (recommended, fast)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# Or use pip
pip install git+https://github.com/github/spec-kit.git
Initialize:
specify init --here --ai cursor
# Also supports claude / chatgpt / copilot
A specs/ folder appears in your project. All specification documents will live here.
Step 2: Write Your First Spec
Don't aim for perfection. Just communicate like you would with a colleague:
/specify I want to build user filtering that can filter by registration
date, status, and role. Conditions should be combinable with pagination.
We'll likely need to add more filter dimensions later.
AI organizes this into a structured specification document.
Step 3: Let AI Propose, You Review
Input /plan. AI generates a technical proposal based on specs.
Important: Think critically here! Review it, challenge it—don't rubber-stamp it.
Then use /tasks to break down work, finally /implement to have AI write code within the framework.
My Practical Advice
Don't tackle super-complex features right away. Choose medium difficulty projects that will likely require future changes. First time using it, don't aim for perfection—just feel the rhythm of "design first, code second."
If interested, build the same feature with both vibe coding and Spec-Kit. Experience that massive psychological contrast firsthand.
Of Course, Spec-Kit Isn't a Silver Bullet
Don't use it for:
❌ One-off throwaway scripts
❌ Emergency hotfixes (no time for documentation)
❌ Pure learning experiments (unclear direction)
❌ Trivial features requiring just a few lines
When should you use it? Three diagnostic questions:
- Will this feature change later? → Yes? Use it.
- Will others struggle to understand this code? → Yes? Use it.
- Can you quickly pinpoint issues when problems arise? → Not confident? Use it.
A Different Friday at 5 PM
Imagine: same scenario, same Friday at 5 PM, same product manager with "quick request."
But this time, you don't immediately open AI and start coding.
You spend 20 minutes writing a simple specification: What exactly is needed? Where are the boundaries? How might this evolve?
Then you hand this "blueprint" to AI. It proposes solutions. You review.
Initial version takes an extra hour. But when product adds new features later, you finish in ten minutes.
More importantly: you always understand the project. The code never becomes a mountain of shit you're afraid to touch.
The Real Competition in the AI Era
It's not about who makes AI write code faster. It's about who can define problems more clearly.
Spec-Kit isn't making you "slow down"—it's helping you "think clearly." And thinking clearly before acting is often the shortest path.
Remember: in this human-AI collaboration, we must be the ones who define problems and make final decisions.