jesus manrique

Posted on May 15 • Originally published at guayoyo.tech

Spec-Driven Development with Claude Code: UI, Deploy & The Living Spec — Part 3 of 3

#webdev #ai #devops #tutorial

Series: Spec-Driven Development with Claude Code — Part 1 · Part 2 · Part 3

In Part 1 we created the spec and scaffold. In Part 2 we implemented auth and data access. Today we close the loop: UI, route protection, deployment, and — most importantly — how to keep the spec alive as your product evolves.

Because a spec that doesn't get updated is worse than no spec: it gives you false confidence.

Step 1: Auth Middleware

Protecting routes sounds simple but gets messy without a clear spec. Ours (US-5) says exactly what to protect:

/products requires authentication
/login and /register redirect to /products if already authenticated

We ask Claude Code:

> Read @specs/catalogo-guayoyo.md US-5. Implement the auth middleware in middleware/auth.ts. Use defineNuxtRouteMiddleware. No duplicated logic — the middleware should be generic.

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  const { user, loading } = useAuth()

  // Wait for session initialization
  if (loading.value) return

  const publicRoutes = ['/login', '/register']

  if (!user.value && !publicRoutes.includes(to.path)) {
    return navigateTo('/login')
  }

  if (user.value && publicRoutes.includes(to.path)) {
    return navigateTo('/products')
  }
})

Clean, generic, no external dependencies. Exactly what the spec asked for. In pages/products.vue, we activate the middleware:

<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
</script>

Step 2: Product Catalog UI

Now the fun part. We build a polished UI with Tailwind, handling every state defined in our spec: loading, error, empty, and success.

> Read @specs/catalogo-guayoyo.md US-3. Implement ProductCard, ProductGrid components and the /products page. States: loading (skeleton), empty ("No products available"), error (with retry button), success (grid). Tailwind, responsive (1/2/3 cols). Subtle hover animations.

components/ProductCard.vue:

<script setup lang="ts">
import type { Product } from '~/composables/useProducts'

defineProps<{ product: Product }>()
</script>

<template>
  <article class="group rounded-xl bg-white shadow-sm border border-gray-100 
                  overflow-hidden transition-all duration-300 hover:shadow-md 
                  hover:-translate-y-1">
    <div class="aspect-square overflow-hidden bg-gray-50">
      <img
        :src="product.image_url"
        :alt="product.name"
        class="h-full w-full object-cover transition-transform duration-300 
               group-hover:scale-105"
        loading="lazy"
      />
    </div>
    <div class="p-4">
      <span class="text-xs font-medium text-guayoyo-600 uppercase tracking-wider">
        {{ product.category }}
      </span>
      <h3 class="mt-1 text-lg font-semibold text-gray-900 line-clamp-1">
        {{ product.name }}
      </h3>
      <p class="mt-2 text-xl font-bold text-guayoyo-700">
        ${{ product.price.toFixed(2) }}
      </p>
    </div>
  </article>
</template>

pages/products.vue:

<script setup lang="ts">
definePageMeta({ middleware: 'auth' })

const { products, loading, error, fetchProducts } = useProducts()
const { user, signOut } = useAuth()
const router = useRouter()

await fetchProducts()

async function handleLogout() {
  await signOut()
  await router.push('/login')
}
</script>

<template>
  <div class="min-h-screen bg-gray-50">
    <!-- Header -->
    <header class="bg-white shadow-sm">
      <div class="mx-auto max-w-7xl px-4 py-4 flex justify-between items-center">
        <h1 class="text-xl font-bold text-gray-900">Catálogo Guayoyo</h1>
        <div class="flex items-center gap-4">
          <span class="text-sm text-gray-500">{{ user?.email }}</span>
          <button @click="handleLogout"
            class="text-sm text-red-600 hover:text-red-800 transition-colors">
            Sign out
          </button>
        </div>
      </div>
    </header>

    <!-- Content -->
    <main class="mx-auto max-w-7xl px-4 py-8">
      <!-- Loading State -->
      <div v-if="loading" class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        <div v-for="n in 6" :key="n" 
             class="h-80 rounded-xl bg-gray-200 animate-pulse" />
      </div>

      <!-- Error State -->
      <div v-else-if="error" class="text-center py-20">
        <p class="text-red-600 text-lg">{{ error }}</p>
        <button @click="fetchProducts"
          class="mt-4 px-6 py-2 bg-guayoyo-600 text-white rounded-lg 
                 hover:bg-guayoyo-700 transition-colors">
          Retry
        </button>
      </div>

      <!-- Empty State -->
      <div v-else-if="products.length === 0" class="text-center py-20">
        <p class="text-gray-400 text-lg">No products available</p>
      </div>

      <!-- Success: Product Grid -->
      <div v-else class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        <ProductCard v-for="product in products" :key="product.id" :product="product" />
      </div>
    </main>
  </div>
</template>

Notice how every state (loading, error, empty, success) is implemented exactly as the acceptance criteria specified. No "the user sees something weird while loading." The spec forces you to think about all states before writing code.

Step 3: Wire Everything Together

With middleware, auth, and UI ready, the application flow is:

User lands at / → middleware redirects to /login
User registers or signs in → redirects to /products
/products fetches products from Supabase
User sees the catalog with loading skeleton while data loads
User signs out → back to /login

All of this works because each piece was implemented against its spec. There are no "surprise" integrations — the US-5 spec (protected routes) already anticipated that /products would require auth and that /login would redirect if already authenticated.

Step 4: Deploy to Vercel

The app is ready. Deploy in 3 commands:

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set environment variables on Vercel
vercel env add SUPABASE_URL
vercel env add SUPABASE_ANON_KEY

Or connect your GitHub repo to Vercel and deploy automatically on every push. Your app will be live at catalogo-guayoyo.vercel.app.

Step 5: The Living Spec — SDD's Most Important Practice

Here's the lesson that separates a tutorial from real engineering practice.

The spec isn't a document you write at the start and abandon. It's a living artifact that evolves with your product.

Real scenario: Your boss says "add category filtering." In traditional development, you open the code, find where to modify, implement, break something, fix it, commit. In SDD:

Update the spec first:

## Change: Category Filter (v1.1)

### US-6: Filter Products by Category
**As** an authenticated user
**I want** to filter products by category
**So that** I can find what I'm looking for faster

Acceptance criteria:
- [AC-6.1] Dropdown or tabs with existing categories
- [AC-6.2] Selecting a category filters products without page reload
- [AC-6.3] "All" option to view the complete catalog
- [AC-6.4] If a category has no products, show specific empty state

Commit the spec:

git add specs/catalogo-guayoyo.md
git commit -m "spec: add category filter (US-6)"

Ask Claude Code to implement against the updated spec:

> Read @specs/catalogo-guayoyo.md. The spec changed — US-6 (category filter) was added.
> Implement the filter while maintaining compatibility with everything existing.
> Don't break anything from US-1 through US-5.

This is radically different from "Claude, add a filter." The difference:

Claude Code knows what NOT to touch (US-1 through US-5 are documented)
The implementation respects acceptance criteria (doesn't guess how the filter should look)
The change is traceable (git log shows what changed in the spec and why)
If something breaks, you go back to the spec — not to debug old prompts

💡 Pro tip: Alex Op's article on SDD with Claude Code shows how to use Claude Code's subagents to research, plan, and implement specs in parallel — an advanced pattern for when your project grows.

What You Learned in This Series

In 3 parts you built:

🎯 A real app with auth, database, and UI — not a TODO list
📋 A specification that is your project's source of truth
🤖 A workflow where Claude Code executes, you decide
🔒 Auth with Supabase, protected routes, Row Level Security
🎨 Responsive UI with all states (loading, empty, error, success)
🚀 Production deployment in minutes
🔄 The living spec: how to iterate without losing direction

All with a consistent pattern: spec → review → implement → validate.

SDD Is Not Waterfall

The most common myth about SDD is that it's "waterfall with AI." François Zaninotto from Marmelab is one of the most cited critics, and his point is valid: 1,300-line specs for displaying a date is bureaucratic nonsense.

But SDD done right isn't waterfall. It's minimum viable discipline:

For an auth feature: 40-line spec
For a product filter: 15-line spec
For changing a button color: you don't need a spec

The practical rule: use specs where the cost of architectural drift is high (auth, payments, multi-tenant data, APIs) and skip specs where being wrong costs a page refresh.

What's Next?

Clone the complete repo: github.com/guayoyo-tech/catalogo-guayoyo (coming soon)
Read the original spec in specs/catalogo-guayoyo.md
Try modifying the spec and asking Claude Code to regenerate
Implement US-6 (category filter) as an exercise
Share your own spec-driven app with #SpecDrivenDev

Liked this series? Let us know what you'd like to build with Spec-Driven Development. Or share it with someone who's still debugging 300-line prompts.

DEV Community