Spec-Driven Development para Vibe Coders: La guía definitiva

Vibe coding es adictivo. Le dices a la IA lo que quieres, te genera código, funciona (más o menos), y en 20 minutos tienes algo que antes te habría tomado días. La dopamina es real. La sensación de poder es increíble. Yo lo viví.

Pero si llevas más de un par de semanas vibe codeando — construyendo proyectos reales, no solo prototipos — ya sabes lo que viene después: el momento en que todo se rompe y no tienes idea de por qué.

La IA te dio código que no entiendes. Le pides que lo arregle y rompe otra cosa. Le pides que arregle eso y rompe lo primero. Te contradice decisiones que ya habían tomado juntos. Olvida lo que le dijiste hace 40 minutos. Y de pronto llevas 3 horas en un ciclo infinito peleando con una IA que cada vez responde peor, más genérica, más vaga.

No eres tú. Es el método. O más bien, la falta de método.

Este artículo es para ti si usas IA para crear software — ChatGPT, Claude, Cursor, Copilot, lo que sea — pero no vienes del mundo de la programación tradicional. No voy a asumir que sabes qué es un API, un test unitario o una base de datos. Voy a explicarte, desde cero y con lujo de detalle:

1. Por qué tus proyectos con IA se rompen después de cierto punto (hay una razón técnica concreta, con datos científicos que lo prueban)
2. Qué es Spec-Driven Development y por qué es la evolución natural de cómo trabajamos con IA
3. Cómo funciona GSD (Get Shit Done), la herramienta que automatiza el proceso completo
4. Cada comando paso a paso — qué hace, cómo se usa, qué genera, ejemplos reales de salida
5. La estructura completa que replica cómo trabaja un equipo de desarrollo profesional
6. Ejemplos de proyectos reales construidos con este método
7. Troubleshooting — qué hacer cuando algo no funciona

Prepárate un café (o dos). Esto es largo, denso, y te va a cambiar la forma en que trabajas con IA.

Parte 1: El problema — Por qué el vibe coding te traiciona

Tu IA tiene Alzheimer temporal (y la ciencia lo prueba)

Cuando le hablas a una IA para que te genere código, hay algo que pasa por debajo que cambia todo: la IA tiene memoria limitada.

No es una limitación arbitraria. Es matemática pura. Los modelos de lenguaje funcionan con algo llamado context window — una "ventana de memoria" que determina cuánto texto pueden procesar a la vez. En el caso de Claude (el modelo más usado para programar en 2026), ese límite es de 200,000 tokens — aproximadamente 150,000 palabras.

Parece mucho, ¿verdad? Pero hay un problema: el tamaño nominal del context window no es lo mismo que el contexto efectivo.

Imagina que estás construyendo una casa con un arquitecto que tiene Alzheimer temporal. Al principio recuerda todo — los planos, tus preferencias, las decisiones que tomaron juntos, cada detalle de cada habitación. Pero a medida que avanza la conversación, empieza a olvidar. Primero olvida un detalle menor: el color de los enchufes. Después una decisión importante: dónde va la tubería del baño. Y para cuando llegas al segundo piso, no recuerda ni siquiera cómo diseñó la cocina del primero.

Eso es exactamente lo que le pasa a la IA. Su capacidad de recordar y usar información degrada conforme el contexto crece. Y esto tiene un nombre técnico: context rot (podredumbre de contexto).

Los datos son brutales — Benchmarks reales

Esto no es una teoría. No es anécdota. Investigadores de las universidades más prestigiosas del mundo midieron exactamente cómo y cuánto se degrada la calidad de los modelos cuando el contexto crece.

El estudio "Lost in the Middle" (Stanford/MIT, 2024)

Publicado en Transactions of the Association for Computational Linguistics (TACL), el estudio más citado sobre este problema se llama "Lost in the Middle: How Language Models Use Long Contexts".

Hallazgo principal: Los LLMs (Large Language Models) tienen una curva de rendimiento en forma de U:

graph TD
    subgraph RENDIMIENTO["Rendimiento según posición de la información relevante"]
        A["📍 Info al INICIO<br/>🟢 Alta precisión<br/>~85-90% accuracy"] 
        B["📍 Info en el MEDIO<br/>🔴 Baja precisión<br/>~55-60% accuracy<br/><strong>-30% de caída</strong>"]
        C["📍 Info al FINAL<br/>🟢 Alta precisión<br/>~80-85% accuracy"]
    end
    
    A -.->|"Primacy bias"| B
    B -.->|"Recency bias"| C

Traducido: la IA recuerda bien lo que le dijiste al principio de la conversación (primacy bias) y lo que le dijiste al final (recency bias). Pero pierde hasta un 30% de precisión con la información del medio — que casi siempre es donde están las decisiones más importantes que tomaron juntos.

Benchmark NoLiMa (febrero 2025)

El benchmark NoLiMa (No Limits for Language Models) midió el rendimiento de los modelos más populares en tareas de razonamiento complejo con contextos de diferentes longitudes:

Dato clave para entender tu experiencia: Claude Sonnet (el modelo que probablemente estás usando) funciona excelente hasta los ~8,000 tokens. Después, la calidad cae un 26%. Y 8,000 tokens son aproximadamente 30-40 minutos de conversación activa construyendo un proyecto.

¿Te suena familiar? Empiezas bien, todo fluye, y después de media hora la IA empieza a comportarse raro. No es casualidad. Es matemática.

Benchmark ACADEMICEVAL

Otro estudio midió precisión en tareas específicas (responder preguntas complejas basadas en documentos largos):

• Contexto <4K tokens: 89% de precisión
• Contexto 8-16K tokens: 76% de precisión (-13%)
• Contexto 32K+ tokens: 57% de precisión (-32%)

La conclusión es la misma: a medida que el contexto crece, la IA se vuelve menos confiable. No es que "se canse" o "pierda interés" — es que su mecanismo de atención se diluye entre demasiada información.

¿Por qué pasa esto? La explicación técnica (simple)

La IA funciona con un mecanismo llamado atención (attention). Para generar cada palabra, "mira" todo lo que dijiste anteriormente y decide qué partes son relevantes. Es como si tuviera que escanear todo el historial de la conversación antes de responder.

Pero a medida que el contexto crece, tres cosas pasan:

1. Dilución de atención

Es como estar en una fiesta. Si hay 5 personas, escuchas y recuerdas lo que cada una dice. Si hay 200 personas, es imposible — terminas escuchando fragmentos, perdiendo hilos, olvidando nombres.

La atención de la IA funciona igual. Con poco contexto, se enfoca bien. Con mucho contexto, se diluye.

2. Sesgo de posición (Positional Bias)

Los transformers (la arquitectura detrás de GPT, Claude, Gemini) usan algo llamado Rotary Position Embedding (RoPE) para entender dónde está cada palabra en la secuencia.

Pero RoPE introduce un "decaimiento a largo plazo" — básicamente, le da más peso a las palabras al principio y al final de la secuencia, y menos peso a las del medio. No es un bug, es una limitación inherente del diseño.

3. Compresión forzada

Cuando el contexto se acerca al límite, algunos modelos comprimen información vieja con heurísticas (reglas) que priorizan recencia sobre importancia. Es como resumir un libro de 400 páginas en 10 — algo importante se va a perder, aunque no lo notes hasta que necesitas ese detalle.

El ciclo mortal del vibe coding

Si viviste esto alguna vez, ahora sabes por qué:

graph TD
    A["💡 Idea genial"] --> B["🚀 20 min: Increíble"]
    B --> C["🟡 40 min: Degrada"]
    C --> D["🔴 60 min: Colapso"]
    D --> E["🔄 Ciclo de bugs"]
    E --> F["😤 Frustración"]
    F --> G["Borras todo"]
    G --> A

El problema no es la IA. El problema es que le estamos pidiendo que recuerde 2 horas de conversación cuando su memoria efectiva es de 20-30 minutos.

Y acá está la parte que más frustra: al principio funciona tan bien que asumes que así va a seguir. Pero no. La degradación es inevitable. Es matemática.

Parte 2: La solución — Spec-Driven Development

Externalizar la memoria

La solución es conceptualmente simple pero requiere un cambio de mentalidad:

En vez de que la IA recuerde todo, escribe todo antes de construir.

No en una conversación que se va llenando. En documentos estructurados que la IA lee cada vez que necesita contexto. Es como pasar de guardar todo en RAM (que tiene límite) a usar el disco duro (que es infinito).

Esto se llama Spec-Driven Development (SDD) — desarrollo guiado por especificaciones.

No es nuevo — pero sí es diferente

Los equipos de ingeniería profesionales llevan décadas escribiendo especificaciones antes de construir. Lo que es nuevo es aplicarlo a la era de la IA, donde el consumidor del spec no es un humano sino un modelo de lenguaje.

Y esa diferencia cambia todo:

La diferencia fundamental:

• TDD/BDD: El humano que lee el spec llena gaps con experiencia, intuición y conocimiento implícito del proyecto
• SDD: El LLM que lee el spec toma lo que está escrito de forma literal — no hay intuición, no hay experiencia, no hay contexto implícito

Ejemplo:

Si le dices a un dev senior "implementar autenticación", sabe que eso incluye hashing de passwords, rate limiting, refresh tokens, session management, y manejo de expiración.

Si le dices a un LLM "implementar autenticación", puede que te dé un if password == stored_password y técnicamente cumplió el spec. Después de todo, no dijiste cómo autenticar.

Por eso las especificaciones para SDD deben ser:

1. Completas — Todo lo que el LLM necesita saber, explícito. Nada implícito.
2. Atómicas — Cada spec debe caber dentro de un context window sin degradar
3. Jerárquicas — Del proyecto completo → a la fase → al plan individual → a la tarea
4. Machine-readable — Estructuradas para que el LLM las consuma eficientemente (no prosa libre)

Quién más está diciendo esto

No soy el único que piensa que esto es un cambio fundamental. En el último año, SDD se convirtió en tema central en la comunidad de desarrollo de software:

ThoughtWorks (la consultora de software más prestigiosa del mundo) publicó en enero 2025:

"Spec-Driven Development: Unpacking 2025's New Engineering Practices"

Red Hat (los creadores de enterprise Linux) publicó:

"How Spec-Driven Development Improves AI Coding Quality"

GitHub Blog:

"Spec-Driven Development with AI: Get Started with a New Open Source Toolkit"

Martin Fowler (una de las figuras más respetadas de ingeniería de software, autor de Refactoring) escribió toda una serie:

"Exploring Gen AI: Tools for Spec-Driven Development"

Anthropic (los creadores de Claude) recomiendan oficialmente:

Usar archivos CLAUDE.md como especificación persistente del proyecto

Esto no es una moda. Es la evolución natural de cómo trabajamos con IA.

El insight clave

graph LR
    subgraph ANTES["❌ Vibe Coding (todo en memoria RAM)"]
        BRAIN["🧠 Cerebro de la IA<br/>Context window: 200K tokens<br/><br/>Decisión 1<br/>Decisión 2<br/>Decisión 3<br/>...<br/>Decisión 47<br/><br/>📊 80% lleno<br/>💀 Empieza a olvidar"]
    end
    
    subgraph DESPUES["✅ Spec-Driven (memoria externa infinita)"]
        FILES["📁 Archivos en disco<br/><br/>PROJECT.md<br/>REQUIREMENTS.md<br/>ROADMAP.md<br/>Plans/<br/>Context/<br/><br/>♾️ Capacidad infinita<br/>🟢 Nunca se llena"]
        
        AI2["🧠 Cerebro de la IA<br/>Context window: 200K tokens<br/><br/>Solo carga lo necesario<br/>para la tarea actual<br/><br/>📊 30% usado<br/>✅ Siempre fresco"]
        
        FILES -.->|"Lee solo lo relevante"| AI2
    end

El filesystem es infinito. El context window no.

SDD mueve el estado del proyecto al filesystem y carga solo lo necesario en cada momento. Es como pasar de guardar todo en RAM (limitado) a usar disco + caché inteligente (infinito).

Parte 3: GSD — La herramienta que lo automatiza todo

¿Qué es GSD?

GSD (Get Shit Done) es una herramienta gratuita y open source que implementa Spec-Driven Development como un flujo concreto de comandos.

Podrías hacer SDD manualmente — escribir los documentos tú, pasárselos a la IA, manejar las fases a mano. Funciona. Pero GSD lo automatiza completamente.

Tú describes lo que quieres construir. GSD se encarga de:

1. Crear los documentos de especificación
2. Planificar las fases de construcción
3. Ejecutar cada fase con IAs frescas (sin problema de memoria)
4. Verificar que todo funcione

Quién lo creó (y por qué importa)

Fue creada por TÂCHES, un desarrollador que — irónicamente — no escribe código. Claude Code lo hace por él. Usando GSD.

Esto no es marketing. Es literal. TÂCHES es un creativo, no un programador. Tuvo una frustración: las herramientas de spec-driven development existentes (BMAD, SpecKit, OpenSpec) eran demasiado complicadas, demasiado "enterprise", demasiado orientadas a equipos de 50 personas con sprint ceremonies, story points, stakeholder syncs, retrospectives, y Jira workflows.

Él no es una empresa de 50 personas. No quiere jugar al teatro corporativo. Solo quiere construir cosas que funcionen.

Entonces creó GSD. La complejidad está en el sistema — context engineering, XML prompt formatting, subagent orchestration, state management. Lo que tú ves: unos comandos que simplemente funcionan.

"I'm a solo developer. I don't write code — Claude Code does. So I built GSD. The complexity is in the system, not in your workflow."
— TÂCHES

Los números (datos de enero 2026)

• 18,345 ⭐ en GitHub en ~2 meses (creado el 14 de diciembre de 2025)
• 1,646 forks — gente que lo tomó y lo modificó para sus necesidades
• 165 issues abiertos — comunidad activa reportando bugs y pidiendo features
• 15,000+ instalaciones del paquete npm
• Usado por ingenieros de Amazon, Google, Shopify y Webflow (según testimonios verificados en el repo)
• Superó en resultados reportados a: BMAD, SpecKit, OpenSpec, Taskmaster, Superpowers

Testimonios reales del repo:

"If you know clearly what you want, this WILL build it for you. No bs."

"I've done SpecKit, OpenSpec and Taskmaster — this has produced the best results for me."

"By far the most powerful addition to my Claude Code. Nothing over-engineered. Literally just gets shit done."

Reddit (r/ClaudeCode):

"GSD just made me $70,000" — Un token cripto asociado al proyecto generó royalties (contexto: esto es sobre el token, no sobre un producto construido con GSD — pero habla de la viralidad)

"I finally decided to use GSD. It's incredible. The structured, meticulous process just works. I went from vibe-coding messy garbage to shipping reliable features."

"Is GSD still relevant after Opus 4.6?" → Consenso de la comunidad: SÍ. Incluso con mejores modelos, la estructura de GSD previene errores y mantiene calidad consistente.

Cómo funciona (la versión simple)

GSD funciona como un director de orquesta. Tú le dices qué sinfonía quieres tocar. GSD contrata músicos frescos (sub-agentes de IA) para cada sección, les da su partitura (el plan), y coordina que toquen en el orden correcto.

Ningún músico tiene que recordar toda la sinfonía — solo su parte. Y como cada músico es fresco (memoria limpia), toca con la máxima calidad.

graph TD
    TU["👤 Tu idea"] --> GSD["🎯 GSD Orquestador"]
    GSD --> R["🔍 4 Researchers en paralelo<br/>200K tokens frescos cada uno"]
    R --> P["📋 Planner + Checker<br/>200K tokens frescos"]
    P --> E["⚙️ 2-3 Executors en paralelo<br/>200K tokens frescos cada uno"]
    E --> D["🐛 Debugger si algo falla<br/>200K tokens frescos"]

El resultado: Tu sesión principal de IA se mantiene al 30-40% de capacidad mientras el trabajo pesado ocurre en sub-agentes con memoria limpia.

Cero degradación. Cero olvidos. Calidad constante de principio a fin.

Parte 4: Instalación — Tu setup en 5 minutos

Pre-requisitos

Antes de instalar GSD necesitas tres cosas:

1. Node.js (el motor que corre JavaScript fuera del navegador)

¿Lo tienes instalado? Abre la terminal y escribe:

node --version

Si ves algo como v20.11.0 o cualquier número, lo tienes. Si dice "command not found", necesitas instalarlo.

Instalación:

• Ve a nodejs.org
• Descarga la versión LTS (Long Term Support — la que dice "Recommended")
• Instala (siguiente, siguiente, finalizar)
• Cierra y abre la terminal de nuevo
• Verifica: node --version

2. Claude Code (la herramienta oficial de Anthropic para programar con IA)

Claude Code es una versión de Claude que corre en la terminal y tiene acceso a tu computador (puede leer archivos, escribir código, ejecutar comandos).

Instalación:

npm install -g @anthropic-ai/claude-code

El -g significa "global" — lo instala para usar desde cualquier carpeta.

Verificar:

claude --version

Si ves un número de versión, listo.

3. GSD (el sistema de especificaciones)

Ahora sí, instalamos GSD:

npx get-shit-done-cc@latest

npx es un comando que ejecuta paquetes de npm. El @latest asegura que siempre bajes la versión más reciente.

¿Qué pasa cuando corres esto?

GSD te hace dos preguntas:

Pregunta 1: Runtime

? ¿Para qué runtime(s) quieres instalar GSD?
  ○ Claude Code
  ○ OpenCode
  ○ Gemini CLI
  ○ Codex
  ● All (todos)

Recomendación: Elige "Claude Code" (o "All" si quieres que funcione con varias herramientas).

Pregunta 2: Scope

? ¿Dónde quieres instalar GSD?
  ○ Global (funciona en todos tus proyectos)
  ● Local (solo en este proyecto)

Recomendación: Elige "Global" — así lo puedes usar en cualquier proyecto futuro sin instalarlo de nuevo.

Verificar que funcionó

Abre Claude Code:

claude

Dentro de Claude Code (verás un prompt que dice Claude>), escribe:

/gsd:help

Si ves la lista de comandos de GSD, todo está listo. 🎉

Configuración recomendada (opcional pero fuertemente sugerida)

GSD funciona mejor si le dices a Claude Code que no te pida permiso para cada operación pequeña (como hacer commits en Git, leer fechas, crear archivos). Esto es normal y seguro en herramientas de automatización.

Cuando abras Claude Code, usa:

claude --dangerously-skip-permissions

El nombre suena dramático ("dangerously" 😱) pero es una convención de la industria para flags que saltan confirmaciones. No es peligroso — solo significa que confías en que Claude no va a borrar tu disco duro.

¿Qué evitas con este flag? Detener el flujo 50 veces para confirmar cosas como:

• ¿Puedo hacer git add?
• ¿Puedo hacer git commit?
• ¿Puedo leer la fecha actual?
• ¿Puedo crear esta carpeta?

Si prefieres no usar ese flag (totalmente válido), puedes configurar permisos granulares. Crea un archivo .claude/settings.json en tu proyecto:

{
  "permissions": {
    "allow": [
      "Bash(date:*)",
      "Bash(echo:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)"
    ]
  }
}

Guarda el archivo y Claude Code usará esos permisos sin preguntar.

Parte 5: Los comandos de GSD — Tu flujo completo (con ejemplos reales)

GSD tiene 6 comandos principales + 3 de gestión. Cada uno hace una cosa específica, en un orden específico. Es como una receta de cocina profesional: sigues los pasos en orden y el resultado sale consistente.

El flujo completo con milestones

Antes de entrar en detalle, acá está el mapa completo de cómo se ve un proyecto de principio a fin:

graph TD
    NP["📋 new-project"] --> DP["💬 discuss-phase"]
    DP --> PP["📐 plan-phase"]
    PP --> EP["⚡ execute-phase"]
    EP --> VW["✅ verify-work"]
    VW -->|"Falló"| FIX["🔧 Fix → re-execute"]
    FIX --> VW
    VW -->|"OK + más fases"| DP
    VW -->|"Todas completas"| CM["🏁 complete-milestone"]
    CM --> NM["🔄 new-milestone"]
    NM --> DP

Ahora sí, comando por comando con todo el detalle.

Comando 1: /gsd:new-project — Definir tu idea

En una frase: Le cuentas a GSD qué quieres construir, y genera toda la documentación estructurada que la IA necesita para trabajar bien.

¿Cuándo usarlo? Al inicio de un proyecto nuevo. Una sola vez.

¿Cómo se usa?

Abre Claude Code (claude) y escribe:

/gsd:new-project

¿Qué pasa?

GSD arranca una conversación interactiva. Te va a hacer preguntas — muchas preguntas. Y eso es bueno. Cada pregunta que responde ahora es un error que evitas después.

Ejemplos de lo que pregunta:

GSD: ¿Qué quieres construir?
Tú: Una plataforma donde freelancers publiquen sus servicios y los clientes puedan contratarlos

GSD: ¿Para quién es?
Tú: Freelancers en LATAM que quieren cobrar en dólares y clientes que buscan talento latino

GSD: ¿Qué funcionalidades necesita?
Tú: Perfil de freelancer, catálogo de servicios, búsqueda, sistema de solicitudes, chat, pagos con tarjeta

GSD: ¿Preferencias de diseño?
Tú: Limpio, moderno, tema oscuro, responsive

GSD: ¿Qué tecnología prefieres?
Tú: Elige tú lo más simple y moderno para este caso

GSD: ¿Qué pasa si un cliente solicita un servicio y el freelancer no responde en 48h?
Tú: La solicitud se marca como "sin respuesta" y el cliente puede buscar otro freelancer

GSD: ¿Los freelancers pueden subir portafolio de trabajos anteriores?
Tú: Sí, hasta 10 imágenes por servicio

No necesitas ser técnico. Responde con tus palabras, como se te ocurra.

¿Qué pasa por debajo?

sequenceDiagram
    participant T as 👤 Tú
    participant G as 🎯 GSD
    participant R as 🔍 4 Researchers

    T->>G: /gsd:new-project
    G->>T: Preguntas sobre tu idea
    T->>G: Respuestas
    G->>T: Más preguntas (profundiza)
    T->>G: Más respuestas
    G->>R: 4 agentes investigan en paralelo
    R->>G: Reportes: stack, features, arquitectura, riesgos
    G->>G: Genera PROJECT + REQUIREMENTS + ROADMAP + STATE
    G->>T: Presenta ROADMAP para aprobación
    T->>G: ✅ Aprobado

Nota algo crítico: GSD lanza 4 agentes de investigación en paralelo, cada uno con 200K tokens de memoria limpia. No es una sola IA tratando de investigar todo (y llenándose de contexto) — son 4 especialistas trabajando al mismo tiempo en sub-tareas específicas.

El orquestador principal (tu sesión de Claude Code) solo coordina. Nunca hace trabajo pesado. Siempre tiene contexto fresco.

¿Qué archivos genera?

Después de aprobar el roadmap, GSD crea 4 archivos en la raíz de tu proyecto:

1. PROJECT.md

La visión del proyecto. Este archivo se carga siempre en el contexto de cada comando.

Ejemplo real:

# FreelanceLATAM

Plataforma de conexión entre freelancers latinoamericanos y clientes globales, con enfoque en pagos en USD y facilidad de uso.

## Visión
Ser el puente que permite a talento latino competir globalmente sin las fricciones de las plataformas existentes.

## Stack
- **Frontend:** Next.js 14 (App Router), TypeScript, Tailwind CSS
- **Backend:** Supabase (Postgres + Auth + Storage + Edge Functions)
- **Pagos:** Stripe Connect
- **Deployment:** Vercel
- **Monitoring:** Vercel Analytics + Sentry

## Decisiones clave
- **Sin app móvil en v1:** Web responsive es suficiente
- **USD como moneda base:** Simplifica contabilidad internacional
- **Magic link auth:** Sin passwords, menos fricción
- **Comisión 10%:** Competitivo vs 20% de Fiverr

## Usuarios objetivo
- **Freelancers:** Desarrolladores, diseñadores, escritores, marketers en LATAM
- **Clientes:** Startups y empresas medianas que buscan talento remoto

2. REQUIREMENTS.md

Lista completa de funcionalidades organizadas por versión.

Ejemplo real (extracto):

# Requirements — FreelanceLATAM

## V1 (MVP)

### Auth (REQ-001 a REQ-003)
- REQ-001: Registro con email (magic link, sin password)
- REQ-002: Perfil de freelancer (nombre, bio, skills, tarifa/hora, foto)
- REQ-003: Perfil de cliente (nombre, empresa, foto)

### Catálogo (REQ-004 a REQ-008)
- REQ-004: Crear servicio (título, descripción, precio fijo, tiempo estimado, categoría)
- REQ-005: Galería del servicio (hasta 10 imágenes)
- REQ-006: Catálogo público con grid de tarjetas
- REQ-007: Búsqueda por texto (título, descripción, skills)
- REQ-008: Filtros (categoría, rango de precio, rating min)

### Solicitudes (REQ-009 a REQ-012)
- REQ-009: Cliente solicita servicio → freelancer recibe notificación
- REQ-010: Freelancer acepta/rechaza en 48h (auto-expire si no responde)
- REQ-011: Chat entre cliente y freelancer (texto + archivos)
- REQ-012: Cliente marca solicitud como completada

### Pagos (REQ-013 a REQ-015)
- REQ-013: Checkout con Stripe (tarjeta de crédito/débito)
- REQ-014: Escrow: dinero retenido hasta que cliente confirma entrega
- REQ-015: Payout al freelancer (menos 10% comisión) via Stripe Connect

### Dashboard (REQ-016 a REQ-018)
- REQ-016: Freelancer ve: solicitudes activas, ganancias totales, servicios
- REQ-017: Cliente ve: solicitudes activas, historial de pagos
- REQ-018: Notificaciones (email + in-app) para eventos importantes

## V2 (Post-MVP)

### Reviews y ratings (REQ-019 a REQ-021)
- REQ-019: Cliente deja review y rating (1-5 ⭐) después de completar
- REQ-020: Rating promedio visible en perfil de freelancer y tarjeta de servicio
- REQ-021: Freelancer puede responder a reviews

### Portafolio extendido (REQ-022 a REQ-023)
- REQ-022: Proyectos anteriores con título, descripción, imágenes, link externo
- REQ-023: Testimonios de clientes externos (no de la plataforma)

### Búsqueda avanzada (REQ-024 a REQ-025)
- REQ-024: Filtrar por disponibilidad del freelancer
- REQ-025: Ordenar por: relevancia, precio, rating, reciente

## Fuera de alcance (explícitamente NO en v1 ni v2)

- App móvil nativa (iOS/Android)
- Pagos con transferencia bancaria directa
- Sistema de suscripción mensual
- Videollamadas integradas
- Marketplace de productos físicos
- Traductor automático de mensajes
- Sistema de referidos con bonos

3. ROADMAP.md

Las fases de construcción con dependencias claras.

Ejemplo real:

# Roadmap — FreelanceLATAM

## Milestone 1: MVP

### Fase 1: Fundación
**Cobertura:** REQ-001, REQ-002, REQ-003
**Duración estimada:** 2-3 días
- Base de datos (Supabase schema)
- Modelos: User, FreelancerProfile, ClientProfile
- Auth con magic link
- Páginas de perfil (view-only en esta fase)

**Dependencias:** Ninguna (es la base)

---

### Fase 2: Catálogo de Servicios
**Cobertura:** REQ-004, REQ-005, REQ-006
**Duración estimada:** 2-3 días
- Modelo Service
- CRUD de servicios (solo para freelancers logueados)
- Galería de imágenes (Supabase Storage)
- Catálogo público (grid responsive, sin búsqueda/filtros aún)

**Dependencias:** Fase 1 (necesita auth y perfiles)

---

### Fase 3: Búsqueda y Filtros
**Cobertura:** REQ-007, REQ-008
**Duración estimada:** 1-2 días
- Búsqueda full-text (Postgres)
- Filtros laterales (categoría, precio, rating)
- URL params para compartir búsquedas

**Dependencias:** Fase 2 (necesita servicios existentes)

---

### Fase 4: Solicitudes
**Cobertura:** REQ-009, REQ-010, REQ-011, REQ-012
**Duración estimada:** 3-4 días
- Modelo ServiceRequest
- Flujo: solicitar → aceptar/rechazar → chat → completar
- Chat en tiempo real (Supabase Realtime)
- Auto-expire de solicitudes (cron job)
- Upload de archivos en chat

**Dependencias:** Fase 2 (necesita servicios)

---

### Fase 5: Pagos
**Cobertura:** REQ-013, REQ-014, REQ-015
**Duración estimada:** 4-5 días
- Stripe Connect onboarding para freelancers
- Checkout page con Stripe Elements
- Escrow: payment intent con capture manual
- Webhook handler para events de Stripe
- Payout automático cuando cliente confirma

**Dependencias:** Fase 4 (solicitud debe existir antes de pagar)

---

### Fase 6: Dashboard y Notificaciones
**Cobertura:** REQ-016, REQ-017, REQ-018
**Duración estimada:** 2-3 días
- Dashboard de freelancer (métricas, solicitudes, ganancias)
- Dashboard de cliente (solicitudes, historial)
- Sistema de notificaciones (email via Resend + in-app)
- Email templates (solicitud recibida, pago confirmado, etc.)

**Dependencias:** Fases 4 y 5 (necesita datos de solicitudes y pagos)

---

### Fase 7: Polish
**Cobertura:** UX general
**Duración estimada:** 2-3 días
- Loading states y skeletons
- Error handling consistente
- Empty states con CTAs claros
- Responsive final (mobile + tablet)
- SEO básico (metadata, sitemap)
- Lighthouse audit → score >90

**Dependencias:** Todas las fases anteriores (es el refinamiento final)

---

## Milestone 2: Post-MVP (futuro)
Fases para v2 se planifican después de completar Milestone 1.

4. STATE.md

La memoria persistente del proyecto — decisiones, blockers, posición actual.

Ejemplo real (inicial):

# State — FreelanceLATAM

## Posición actual
- Milestone: 1 (MVP)
- Fase activa: Ninguna (proyecto recién inicializado)
- Última actividad: 2026-03-03 — Roadmap aprobado

## Decisiones tomadas
- **Stack:** Next.js 14 + Supabase + Stripe + Vercel
- **Auth:** Magic link (sin passwords)
- **Pagos:** Stripe Connect con escrow
- **Comisión:** 10% flat
- **Diseño:** Tema oscuro, responsive-first

## Blockers actuales
- Ninguno

## Pendientes
- Crear cuenta de Stripe (modo test por ahora)
- Configurar Supabase project
- Configurar Resend para emails

## Notas para sesiones futuras
- El cliente quiere que sea rápido de usar — priorizar UX sobre features complejas
- Evitar over-engineering en v1 — shipping > perfección

Este archivo se actualiza conforme avanza el proyecto. Es la memoria entre sesiones.

Comando 2: /gsd:map-codebase — Entender lo que ya existe

En una frase: Si ya tienes código (porque ya empezaste el proyecto o estás trabajando sobre algo existente), este comando analiza todo y crea un "mapa" que la IA puede leer.

¿Cuándo usarlo?

• ANTES de /gsd:new-project si ya tienes código existente
• Después de completar varias fases, para actualizar el mapa
• Si alguien más contribuyó código y quieres que la IA entienda los cambios

¿Cómo se usa?

/gsd:map-codebase

No necesitas hacer nada más. GSD trabaja solo.

¿Qué pasa por debajo?

sequenceDiagram
    participant G as 🎯 GSD
    participant A1 as 🔍 Agente 1<br/>(Stack Analysis)
    participant A2 as 🔍 Agente 2<br/>(Architecture)
    participant A3 as 🔍 Agente 3<br/>(Conventions)
    participant A4 as 🔍 Agente 4<br/>(Concerns)
    
    G->>G: Escanea el codebase<br/>(archivos, carpetas, package.json, etc.)
    
    par Análisis en paralelo
        G->>A1: Analiza stack y dependencias
        G->>A2: Analiza estructura y patrones arquitectónicos
        G->>A3: Analiza convenciones de código
        G->>A4: Busca code smells, deuda técnica, riesgos
    end
    
    Note over A1: 200K tokens frescos<br/>Lee package.json, lockfiles,<br/>configs, READMEs
    Note over A2: 200K tokens frescos<br/>Mapea carpetas, archivos,<br/>relaciones, imports
    Note over A3: 200K tokens frescos<br/>Analiza naming, patterns,<br/>comentarios, estilo
    Note over A4: 200K tokens frescos<br/>Busca TODO, FIXME, duplicación,<br/>complejidad ciclomática
    
    A1->>G: stack-analysis.md
    A2->>G: architecture.md
    A3->>G: conventions.md
    A4->>G: concerns.md
    
    G->>G: Guarda todo en .planning/research/

¿Qué archivos genera?

Cuatro archivos en .planning/research/:

1. stack-analysis.md

Ejemplo real (proyecto Next.js existente):

# Stack Analysis — FreelanceLATAM

## Framework principal
- **Next.js 14.1.0** (App Router)
- **React 18.2.0**
- **TypeScript 5.3.3**

## Librerías principales
- **@supabase/supabase-js 2.39.7** — Cliente de Supabase
- **@stripe/stripe-js 3.0.6** — Stripe checkout
- **@tanstack/react-query 5.28.0** — Data fetching y cache
- **tailwindcss 3.4.1** — CSS utility-first
- **zod 3.22.4** — Validación de schemas
- **react-hook-form 7.51.0** — Form handling
- **lucide-react 0.344.0** — Iconos

## Dev dependencies
- **eslint 8.57.0** + plugins (typescript, react, next)
- **prettier 3.2.5**
- **typescript 5.3.3**

## Scripts disponibles
- `npm run dev` — Dev server (localhost:3000)
- `npm run build` — Production build
- `npm run start` — Production server
- `npm run lint` — ESLint check
- `npm run format` — Prettier format

## Compatibilidad
- Node.js: >=18.17.0 (según engines en package.json)
- Package manager: npm (lockfile: package-lock.json)

## Notas
- Usa App Router de Next.js 14 (no Pages Router)
- TypeScript estricto habilitado
- Tailwind con configuración custom (ver tailwind.config.ts)

2. architecture.md

Ejemplo real:

# Architecture — FreelanceLATAM

## Estructura general

\`\`\`
freelance-latam/
├── app/                    # Next.js 14 App Router
│   ├── (auth)/             # Layout group — rutas que requieren auth
│   │   ├── dashboard/
│   │   ├── services/
│   │   └── requests/
│   ├── (public)/           # Layout group — rutas públicas
│   │   ├── browse/
│   │   ├── service/[id]/
│   │   └── freelancer/[id]/
│   ├── api/                # API routes (server-side)
│   │   ├── auth/
│   │   ├── services/
│   │   ├── requests/
│   │   └── webhooks/
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Home page
│
├── components/             # React components
│   ├── ui/                 # Base UI (buttons, inputs, cards)
│   ├── forms/              # Form-specific components
│   ├── layouts/            # Layout components (header, footer, sidebar)
│   └── features/           # Feature-specific components
│       ├── services/
│       ├── requests/
│       └── chat/
│
├── lib/                    # Utilidades y lógica de negocio
│   ├── supabase/
│   │   ├── client.ts       # Cliente de Supabase (browser)
│   │   ├── server.ts       # Cliente de Supabase (server)
│   │   └── schema.ts       # Types generados de DB
│   ├── stripe/
│   │   ├── client.ts
│   │   └── server.ts
│   ├── validations/        # Zod schemas
│   └── utils.ts            # Helpers generales
│
├── types/                  # Type definitions globales
├── hooks/                  # Custom React hooks
├── public/                 # Assets estáticos
└── supabase/               # Migrations y seed data
    ├── migrations/
    └── seed.sql
\`\`\`

## Patrones arquitectónicos identificados

### 1. **Server Components first**
La mayoría de componentes en `/app` son Server Components (default en Next.js 14). Solo los que necesitan interactividad son Client Components (marcados con `'use client'`).

**Beneficio:** Menos JavaScript enviado al browser, mejor performance.

### 2. **API routes como thin layer**
Los API routes (`/app/api/*`) son mayormente wrappers sobre Supabase. La lógica de negocio compleja (ej. calcular comisiones, validar permisos) vive en `/lib`.

### 3. **React Query para data fetching**
Todas las llamadas a APIs desde el cliente usan React Query. Esto da:
- Cache automático
- Revalidación en background
- Loading/error states consistentes

### 4. **Zod para validación end-to-end**
Los schemas de validación (en `/lib/validations`) se usan:
- En el cliente (react-hook-form)
- En el servidor (API routes)
- Como source of truth para types de TypeScript

### 5. **Layout groups para auth**
Next.js 14 permite carpetas con `(nombre)` que no afectan la URL. Esto se usa para separar:
- `(auth)` — Rutas que requieren login
- `(public)` — Rutas accesibles sin login

Cada group tiene su propio `layout.tsx` con lógica de autenticación.

## Flujo de datos típico

\`\`\`mermaid
sequenceDiagram
    participant U as 👤 Usuario
    participant C as Client Component
    participant RQ as React Query
    participant API as API Route
    participant S as Supabase
    
    U->>C: Acción (ej. "Crear servicio")
    C->>RQ: useMutation()
    RQ->>API: POST /api/services
    API->>API: Valida con Zod schema
    API->>S: supabase.from('services').insert()
    S->>API: { data, error }
    API->>RQ: Response JSON
    RQ->>C: Actualiza cache + UI
    C->>U: Feedback visual
\`\`\`

## Decisiones de arquitectura heredadas

- **Sin Redux/Zustand:** Estado global se maneja con React Query + URL params
- **Sin tRPC:** Next.js API routes son suficientes para este scope
- **Supabase Edge Functions deshabilitadas:** Toda la lógica custom está en Next.js API routes por ahora

3. conventions.md

Ejemplo real:

# Conventions — FreelanceLATAM

## Naming conventions

### Archivos
- Componentes: PascalCase (`ServiceCard.tsx`)
- Hooks: camelCase con prefijo `use` (`useServiceForm.ts`)
- Utils: camelCase (`formatCurrency.ts`)
- API routes: lowercase con guiones (`create-service.ts`)

### Variables y funciones
- camelCase para todo
- Funciones que devuelven JSX: PascalCase (se tratan como componentes)
- Constantes globales: UPPER_SNAKE_CASE (`MAX_UPLOAD_SIZE`)

### Types y interfaces
- PascalCase
- Interfaces que describen props: sufijo `Props` (`ServiceCardProps`)
- Types que describen data models: sin sufijo (`Service`, `User`)

## Code style

### Imports organizados
\`\`\`typescript
// 1. React y Next.js
import { useState } from 'react'
import { redirect } from 'next/navigation'

// 2. Third-party libraries
import { useQuery } from '@tanstack/react-query'
import { z } from 'zod'

// 3. Absolute imports (alias @/)
import { createClient } from '@/lib/supabase/server'
import { ServiceCard } from '@/components/features/services'

// 4. Relative imports
import { formatCurrency } from './utils'
\`\`\`

### Componentes funcionales siempre
No hay componentes de clase. Todo es funcional con hooks.

### Props destructuring
\`\`\`typescript
// ✅ Sí
function ServiceCard({ title, price, freelancer }: ServiceCardProps) {
  return <div>...</div>
}

// ❌ No
function ServiceCard(props: ServiceCardProps) {
  return <div>{props.title}</div>
}
\`\`\`

### Early returns
\`\`\`typescript
function ServiceCard({ service }: Props) {
  if (!service) return null
  if (service.status !== 'active') return <InactiveCard />
  
  // Happy path sin indentación extra
  return <div>...</div>
}
\`\`\`

## Comentarios

### JSDoc para funciones exportadas
\`\`\`typescript
/**
 * Formatea un número como moneda USD
 * @param amount - Cantidad en centavos
 * @returns String formateado (ej. "$1,234.56")
 */
export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(amount / 100)
}
\`\`\`

### Inline comments solo para "why", no para "what"
\`\`\`typescript
// ✅ Explica decisión no obvia
// Usamos setTimeout porque Supabase Realtime tiene un delay
// de ~500ms antes de que el mensaje aparezca en la subscription
setTimeout(() => refetch(), 600)

// ❌ Describe lo que el código ya dice
// Incrementa el contador
setCount(count + 1)
\`\`\`

## Error handling

### Try-catch con errores tipados
\`\`\`typescript
try {
  const result = await someAsyncOperation()
  return { success: true, data: result }
} catch (error) {
  if (error instanceof ZodError) {
    return { success: false, error: 'Validation failed', details: error.errors }
  }
  if (error instanceof StripeError) {
    return { success: false, error: 'Payment failed', message: error.message }
  }
  // Catch-all
  return { success: false, error: 'Unknown error' }
}
\`\`\`

### API routes siempre devuelven status correcto
\`\`\`typescript
// ✅ Sí
return NextResponse.json({ error: 'Not found' }, { status: 404 })

// ❌ No
return NextResponse.json({ error: 'Not found' }) // Status 200 por default
\`\`\`

## Testing (cuando exista)

- Unit tests: `*.test.ts` o `*.test.tsx`
- Integration tests: `*.integration.test.ts`
- E2E tests: carpeta `/e2e`
- Coverage mínimo esperado: 70% (aún no implementado)

4. concerns.md

Ejemplo real:

# Concerns — FreelanceLATAM

## ⚠️ Problemas actuales

### 1. **Falta manejo de rate limiting**
**Riesgo:** Alto
**Impacto:** Una persona puede spamear solicitudes a freelancers o crear cientos de servicios falsos

**Ubicación:** `/app/api/*`

**Recomendación:** Implementar rate limiting con Upstash Redis o Vercel Edge Config. Limitar:
- Creación de servicios: 10/día por freelancer
- Solicitudes: 20/día por cliente
- Mensajes en chat: 100/hora por usuario

---

### 2. **Webhooks de Stripe sin validación de firma**
**Riesgo:** Crítico
**Impacto:** Alguien podría enviar webhooks falsos y marcar pagos como completados sin haber pagado realmente

**Ubicación:** `/app/api/webhooks/stripe/route.ts`

**Código problemático:**
\`\`\`typescript
// ❌ Acepta cualquier POST sin verificar
export async function POST(req: Request) {
  const event = await req.json()
  // Procesa el event sin verificar que vino de Stripe
}
\`\`\`

**Solución:**
\`\`\`typescript
import { headers } from 'next/headers'
import Stripe from 'stripe'

export async function POST(req: Request) {
  const body = await req.text()
  const signature = headers().get('stripe-signature')!
  
  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }
  
  // Ahora sí procesar
}
\`\`\`

---

### 3. **Queries N+1 en el catálogo**
**Riesgo:** Medio
**Impacto:** Performance pobre cuando hay 100+ servicios. Cada servicio hace query separado para traer el perfil del freelancer

**Ubicación:** `/app/(public)/browse/page.tsx`

**Código problemático:**
\`\`\`typescript
const services = await supabase.from('services').select('*')
// Después, por cada servicio:
services.map(s => {
  const freelancer = await supabase.from('users').select('*').eq('id', s.freelancer_id)
  // N+1 queries!
})
\`\`\`

**Solución:** Usar Supabase joins:
\`\`\`typescript
const services = await supabase
  .from('services')
  .select(`
    *,
    freelancer:users!inner(id, name, avatar_url, rating)
  `)
// Una sola query con join
\`\`\`

---

### 4. **Sin logs estructurados**
**Riesgo:** Bajo (pero crece con el tiempo)
**Impacto:** Debugging en producción es un dolor. No hay forma de rastrear qué usuario hizo qué

**Recomendación:** Integrar un logger estructurado (ej. Pino, Winston) o usar Vercel Logs con context:
\`\`\`typescript
console.log(JSON.stringify({
  level: 'info',
  message: 'Service created',
  userId: user.id,
  serviceId: service.id,
  timestamp: new Date().toISOString()
}))
\`\`\`

---

### 5. **Imágenes sin optimización**
**Riesgo:** Bajo
**Impacto:** Las imágenes de servicios se suben sin resize ni compresión. Un freelancer puede subir un PNG de 10MB y arruinar la performance de la página

**Ubicación:** Upload handler en `/app/api/services/upload`

**Solución:** Usar Sharp para resize antes de subir a Supabase Storage:
\`\`\`typescript
import sharp from 'sharp'

const buffer = await file.arrayBuffer()
const optimized = await sharp(Buffer.from(buffer))
  .resize(1200, 900, { fit: 'cover' })
  .jpeg({ quality: 85 })
  .toBuffer()

await supabase.storage.from('service-images').upload(path, optimized)
\`\`\`

---

## ✅ Cosas que están bien

- TypeScript estricto habilitado — menos bugs en runtime
- Supabase Row Level Security (RLS) activado — seguridad en DB level
- Environment variables bien separadas (`.env.local` en `.gitignore`)
- ESLint + Prettier configurados — código consistente
- Next.js 14 App Router — la mejor performance posible para React

💡 Si empiezas de cero, salta este comando. No tienes código que analizar. Ve directo a /gsd:new-project.

Comando 3: /gsd:discuss-phase 1 — Resolver dudas antes de construir

En una frase: Antes de planificar cómo construir una fase, GSD identifica las "zonas grises" — decisiones que no están claras — y te pregunta.

¿Cuándo usarlo? Siempre. Antes de cada fase. Sin excepción. Aunque creas que todo está claro. Siempre hay algo que no pensaste.

¿Por qué es tan importante?

Piensa en esto: tu ROADMAP dice "Fase 2: Catálogo de servicios". Suena claro. Pero en realidad hay 20 decisiones implícitas que no tomaste:

• ¿Las tarjetas muestran precio o rango de precio?
• ¿El grid es de 2, 3, o 4 columnas?
• ¿La búsqueda es instantánea (mientras escribes) o con botón?
• ¿Qué pasa cuando no hay resultados?
• ¿Los filtros son laterales o desplegables?
• ¿Hay paginación o scroll infinito?
• ¿Se pueden guardar búsquedas?

Si no tomas estas decisiones, la IA las toma por ti. Y cuando la IA toma decisiones de diseño sin preguntarte, el resultado es "razonable" pero no es lo que querías. Vas a pasar horas ajustando algo que podrías haber definido en 5 minutos.

¿Cómo se usa?

/gsd:discuss-phase 1

(Cambia el número por la fase que vas a trabajar.)

¿Qué preguntas hace?

GSD analiza el tipo de feature y adapta las preguntas:

Ejemplo de conversación real:

GSD: "Para la Fase 2 (Catálogo de Servicios), necesito 
      aclarar algunas cosas:"

GSD: "¿Diseño tipo grid (tarjetas) o tipo lista?"
Tú:  "Grid con tarjetas, 3 por fila en desktop, 1 en mobile"

GSD: "¿Qué info se ve en cada tarjeta antes de hacer clic?"
Tú:  "Foto del freelancer, nombre del servicio, precio, 
      rating en estrellas, y una etiqueta de categoría"

GSD: "¿Cómo funciona la búsqueda?"
Tú:  "Barra arriba, busca mientras escribes (sin botón), 
      con un delay de medio segundo"

GSD: "¿Filtros?"
Tú:  "Desplegables en una barra debajo de la búsqueda. 
      Categoría, rango de precio, rating mínimo"

GSD: "¿Qué pasa cuando no hay resultados?"
Tú:  "Ilustración simpática + mensaje: 'No encontramos 
      servicios con esos filtros. ¿Probamos sin filtros?' 
      con un botón para limpiar filtros"

GSD: "¿Scroll infinito o paginación?"
Tú:  "Paginación. 12 servicios por página. Botones de 
      Anterior/Siguiente abajo"

GSD: "¿Los servicios se pueden compartir por URL?"
Tú:  "Sí, cada servicio tiene su propia URL con 
      el slug del título"

¿Qué genera?

Un archivo CONTEXT.md dentro de la carpeta de la fase:

# Context — Fase 2: Catálogo de Servicios

## Decisiones de diseño

### Layout
- Grid de tarjetas: 3 columnas en desktop, 2 en tablet, 1 en mobile
- Cards con: imagen del freelancer, nombre del servicio, precio, rating (⭐), categoría badge

### Búsqueda
- Barra superior, full width
- Search-as-you-type con debounce de 500ms
- Placeholder: "Buscar servicios..."
- Icono de lupa a la izquierda

### Filtros
- Debajo de la búsqueda, en línea horizontal
- 3 filtros tipo dropdown: Categoría, Precio (rango), Rating mínimo
- Botón "Limpiar filtros" visible cuando hay filtros activos
- Los filtros se reflejan en la URL (shareable)

### Empty state
- Ilustración simpática (robot o lupa triste)
- Texto: "No encontramos servicios con esos filtros"
- CTA: "Limpiar filtros" → resetea todos los filtros

### Paginación
- 12 servicios por página
- Botones Previous/Next en la parte inferior
- Indicador "Página X de Y"
- URL incluye ?page=N

### URLs
- Cada servicio tiene URL propia: /service/{slug}
- Slug generado del título (ej: "diseño-de-logos-profesional")

## Decisiones de no hacer (explícito)
- NO hay favoritos en esta fase (es Fase posterior)
- NO hay ordenamiento (relevancia por default)
- NO hay mapa/vista de ubicación
- NO hay comparación de servicios lado a lado

Regla de oro: Cuanto más profundo vayas en el discuss, más exacto será el resultado. 5 minutos acá te ahorran 2 horas después.

Comando 4: /gsd:plan-phase 1 — Los planos de construcción

En una frase: Toma todo lo que sabe (requirements + roadmap + tus decisiones del discuss) y genera planos detallados y atómicos para cada pieza de la fase.

¿Cuándo usarlo? Después del discuss. Siempre.

¿Cómo se usa?

/gsd:plan-phase 1

GSD trabaja solo. No necesitas hacer nada. Se toma entre 5-15 minutos dependiendo de la complejidad de la fase.

¿Qué pasa por debajo?

graph TD
    A["📖 Lee CONTEXT.md + REQUIREMENTS.md"] --> B["🔍 Researcher investiga cómo implementar"]
    B --> C["📋 Planner crea 2-3 planes atómicos"]
    C --> D["✅ Checker valida contra requirements"]
    D -->|"Planes completos"| E["✅ Listo para ejecutar"]
    D -->|"Falta algo"| F["Planner ajusta"]
    F --> D

Tres agentes trabajan en secuencia:

1. Researcher — Investiga cómo implementar lo que pide la fase, guiado por tus decisiones del discuss. Si decidiste "search-as-you-type con debounce", el researcher investiga qué librerías y patrones usar para eso.

2. Planner — Con el research en mano, crea planes atómicos: instrucciones detalladas y específicas para cada pieza. Cada plan es lo suficientemente pequeño como para ejecutarse en un context window fresco.

3. Checker — Compara los planes contra los requirements de la fase. ¿Cubren todo? ¿Falta algo? Si falta, le devuelve al planner para que ajuste. Loop hasta que todo esté cubierto.

El concepto clave: planes atómicos

Un plan atómico es como una instrucción en una hoja de papel. No el plano completo de la casa — solo "construye esta pared" con todas las medidas, materiales, y criterios de aceptación.

Ejemplo: Una fase de "Catálogo" puede generar 3 planes:

Plan 2-1: Modelo de datos y API de servicios
  → Crea la tabla, el schema, y los endpoints

Plan 2-2: Componente de tarjeta y grid
  → Crea la UI de la tarjeta y el grid responsive

Plan 2-3: Búsqueda, filtros y paginación
  → Crea toda la lógica de búsqueda y navegación

Cada plan puede ejecutarse por separado. Cada uno cabe en 200K tokens con espacio de sobra. Cero degradación.

¿Qué genera?

Ejemplo real de un PLAN.md (formato XML que Claude optimiza):

<task type="auto">
  <name>Búsqueda, filtros y paginación</name>
  
  <files>
    app/(public)/browse/page.tsx
    components/features/services/SearchBar.tsx
    components/features/services/FilterBar.tsx
    components/features/services/Pagination.tsx
    lib/services/search.ts
  </files>
  
  <context>
    Search-as-you-type con debounce 500ms.
    3 filtros dropdown: categoría, precio (rango), rating mínimo.
    12 resultados por página con Previous/Next.
    Filtros y página reflejados en URL params.
    Empty state con ilustración y CTA "Limpiar filtros".
  </context>
  
  <action>
    1. Crear SearchBar component:
       - Input con ícono de lupa
       - useDebounce hook (500ms)
       - Actualiza URL param ?q=... en cada cambio
    
    2. Crear FilterBar component:
       - 3 Select dropdowns (usar Radix UI Select)
       - Categorías: fetch de /api/categories
       - Precio: rangos predefinidos ($0-50, $50-100, etc)
       - Rating: 1-5 estrellas
       - Botón "Limpiar filtros" (visible solo cuando hay filtros activos)
       - Actualiza URL params en cada cambio
    
    3. Crear función search() en lib:
       - Lee URL params (q, category, minPrice, maxPrice, minRating, page)
       - Construye Supabase query con filtros
       - Full-text search con ts_vector en título y descripción
       - Retorna { data, count, page, totalPages }
    
    4. Crear Pagination component:
       - Botones Previous / Next
       - "Página X de Y"
       - Actualiza URL param ?page=N
    
    5. Actualizar browse/page.tsx:
       - Server component que lee searchParams
       - Llama a search() con params
       - Renderiza SearchBar + FilterBar + Grid + Pagination
       - Si count === 0: renderiza EmptyState component
  </action>
  
  <verify>
    - Escribir "diseño" en búsqueda → resultados se actualizan sin recargar
    - Seleccionar categoría "Marketing" → solo servicios de marketing
    - Filtrar rating >= 4 → solo servicios con 4+ estrellas
    - Combinar filtros → resultados se cruzan correctamente
    - URL refleja todos los filtros (?q=diseño&category=marketing&minRating=4)
    - Copiar URL y abrirla en otra pestaña → mismos resultados
    - Sin resultados → ilustración + "Limpiar filtros" visible
    - Clic en "Limpiar filtros" → resetea todo, muestra todos los servicios
    - Página 2 → muestra servicios 13-24
  </verify>
  
  <done>
    Búsqueda instantánea, filtros funcionales, paginación correcta.
    URL shareable con todos los params.
    Empty state amigable.
  </done>
  
  <depends_on>2-1, 2-2</depends_on>
</task>

¿Ves el nivel de detalle? La IA no tiene que adivinar nada. Cada archivo que debe crear está listado. Cada paso está descrito. Los criterios de verificación son específicos y medibles. Las dependencias están explícitas.

Comando 5: /gsd:execute-phase 1 — Construir

En una frase: Lee los planes y los construye. Lanza sub-agentes frescos para cada plan, en paralelo cuando es posible. Cada plan genera un commit atómico en Git.

¿Cuándo usarlo? Cuando los planes están listos y validados.

¿Cómo se usa?

/gsd:execute-phase 1

Y te sientas a ver. O vas por un café. O haces otra cosa. GSD trabaja solo.

¿Qué pasa por debajo?

GSD organiza los planes en olas (waves) según dependencias. Piénsalo como fases dentro de la fase:

graph LR
    W1["⚡ Ola 1"] --> W2["⚡ Ola 2"] --> W3["⚡ Ola 3"]

⚡ Ola 1 (en paralelo):
  → Plan 2-1: Modelo de datos + API     [🤖 Agente fresco, 200K tokens]
  → Plan 2-2: Tarjeta + Grid            [🤖 Agente fresco, 200K tokens]

⚡ Ola 2 (espera a que Ola 1 termine):
  → Plan 2-3: Búsqueda + Filtros        [🤖 Agente fresco, 200K tokens]
    (necesita que el modelo de datos y el grid existan)

¿Por qué olas?

Los planes que no dependen de otros se ejecutan al mismo tiempo (paralelo). Los que sí dependen esperan. Esto optimiza el tiempo total sin romper nada.

Cada plan = un commit de Git

Cuando un plan termina, GSD hace un commit automático:

abc123f feat(fase-2): modelo de datos y API de servicios
def456g feat(fase-2): componente de tarjeta y grid responsive  
hij789k feat(fase-2): búsqueda, filtros y paginación

Cada commit es atómico y quirúrgico. Si mañana el Plan 2-3 (búsqueda) tiene un bug, puedes revertir exactamente ese commit sin afectar los demás. Es como tener un "deshacer" preciso para cada pieza.

Lo que ves en la terminal mientras ejecuta:

📋 Phase 2: Catálogo de Servicios
   3 plans, 2 waves

⚡ Wave 1 (2 plans in parallel)
   [Plan 2-1] Modelo de datos y API... ⏳ spawning fresh agent
   [Plan 2-2] Tarjeta y Grid...        ⏳ spawning fresh agent
   
   [Plan 2-1] Writing src/lib/supabase/schema.ts... ✅
   [Plan 2-1] Writing src/app/api/services/route.ts... ✅  
   [Plan 2-1] Running verification... ✅ All checks pass
   [Plan 2-1] ✅ Complete → git commit abc123f
   
   [Plan 2-2] Writing components/ServiceCard.tsx... ✅
   [Plan 2-2] Writing components/ServiceGrid.tsx... ✅
   [Plan 2-2] Running verification... ✅ All checks pass
   [Plan 2-2] ✅ Complete → git commit def456g

⚡ Wave 2 (1 plan, depends on wave 1)
   [Plan 2-3] Búsqueda y filtros...     ⏳ spawning fresh agent
   
   [Plan 2-3] Writing components/SearchBar.tsx... ✅
   [Plan 2-3] Writing components/FilterBar.tsx... ✅
   [Plan 2-3] Writing lib/services/search.ts... ✅
   [Plan 2-3] Writing app/(public)/browse/page.tsx... ✅
   [Plan 2-3] Running verification... ✅ All checks pass
   [Plan 2-3] ✅ Complete → git commit hij789k

✅ Phase 2 complete! 3/3 plans executed.

¿Qué genera?

Ejemplo de un SUMMARY.md:

# Summary — Plan 2-3: Búsqueda, filtros y paginación

## Archivos creados
- `components/features/services/SearchBar.tsx` — Input con debounce 500ms
- `components/features/services/FilterBar.tsx` — 3 dropdowns + clear button
- `components/features/services/Pagination.tsx` — Previous/Next + page indicator
- `components/features/services/EmptyState.tsx` — Ilustración + CTA
- `lib/services/search.ts` — Query builder con full-text search
- `hooks/useDebounce.ts` — Custom hook para debounce

## Archivos modificados
- `app/(public)/browse/page.tsx` — Integró SearchBar, FilterBar, Grid, Pagination
- `lib/supabase/schema.ts` — Agregó ts_vector column para full-text search

## Decisiones de implementación
- Usé Radix UI Select para los dropdowns (consistente con el design system)
- El debounce hook es genérico (reutilizable en otros componentes)
- La búsqueda usa `to_tsvector('spanish', ...)` para soportar búsqueda en español
- Empty state usa un SVG inline en vez de imagen externa (mejor performance)

## Commit
`hij789k feat(fase-2): búsqueda, filtros y paginación`

Comando 6: /gsd:verify-work 1 — Verificar que funcione

En una frase: Revisa que lo construido realmente funcione como esperabas, te guía por cada funcionalidad, y si algo falla, genera planes de corrección automáticamente.

¿Cuándo usarlo? Después de ejecutar. Siempre. Es tu red de seguridad.

¿Cómo se usa?

/gsd:verify-work 1

¿Qué pasa?

GSD extrae los "deliverables testeables" de la fase (de los criterios de verificación de cada plan) y te guía uno por uno:

GSD: "Vamos a verificar la Fase 2. Necesito que 
      pruebes lo siguiente en tu browser:"

GSD: "1. ¿Se ve el catálogo con tarjetas de servicios?"
Tú:  "Sí, se ve perfecto. Grid de 3 columnas."

GSD: "2. ¿Funciona la búsqueda mientras escribes?"
Tú:  "Sí, busco 'diseño' y se filtra automáticamente"

GSD: "3. ¿Los filtros funcionan?"
Tú:  "Categoría y rating sí, pero el filtro de precio 
      no está funcionando — no filtra nada"

GSD: "4. ¿La URL refleja los filtros?"
Tú:  "Sí, veo ?q=diseño&category=marketing en la URL"

GSD: "5. ¿Funciona el empty state?"
Tú:  "Sí, lindo. Aparece la ilustración y el botón 
      de limpiar filtros"

GSD: "6. ¿Funciona la paginación?"
Tú:  "No probé, solo hay 5 servicios de prueba"

Si algo falla:

graph TD
    A["❌ Filtro de precio no funciona"] --> B["🐛 GSD spawna Debug Agent"]
    B --> C["Encuentra causa: query falta WHERE clause para precio"]
    C --> D["Genera Fix Plan automático"]
    D --> E["/gsd:execute-phase 2 ejecuta solo el fix"]
    E --> F["/gsd:verify-work 2 verifica de nuevo"]
    F --> G["✅ Todo funciona"]

No tienes que debuggear manualmente. GSD lanza agentes de debugging que:

1. Leen el código generado
2. Leen el plan original (qué debería hacer)
3. Comparan y encuentran la causa raíz
4. Generan un fix plan — un plan atómico con la corrección

Solo tienes que correr /gsd:execute-phase de nuevo — ejecuta solo los fix plans, no repite todo.

¿Qué genera?

Ejemplo de UAT.md:

# UAT — Fase 2: Catálogo de Servicios

## Resultados

| # | Test | Resultado | Notas |
|---|------|-----------|-------|
| 1 | Catálogo visible con tarjetas | ✅ PASS | Grid responsive funciona en desktop y mobile |
| 2 | Búsqueda search-as-you-type | ✅ PASS | Debounce 500ms correcto |
| 3 | Filtro de categoría | ✅ PASS | — |
| 4 | Filtro de rating | ✅ PASS | — |
| 5 | Filtro de precio | ❌ FAIL | No filtra. Query no incluye WHERE para min/maxPrice |
| 6 | URL con params | ✅ PASS | Filtros se reflejan y son shareables |
| 7 | Empty state | ✅ PASS | Ilustración + CTA "Limpiar filtros" |
| 8 | Paginación | ⚠️ SKIP | Solo 5 servicios de prueba, no se puede verificar |

## Diagnóstico de fallos

### Test 5: Filtro de precio
**Causa raíz:** En `lib/services/search.ts`, línea 34, los params `minPrice` y `maxPrice` se leen de URL params pero nunca se incluyen en la query de Supabase.

**Código actual (buggy):**
```typescript
// minPrice y maxPrice se leen pero no se usan
const minPrice = params.get('minPrice')
const maxPrice = params.get('maxPrice')
// ... query se construye sin ellos

Fix plan generado: 2-FIX-1-PLAN.md

Resumen

• 6/8 tests passed
• 1 failure (fix plan generado)
• 1 skipped (insuficientes datos de prueba)

---

### Comandos de gestión: Milestones y Quick

#### `/gsd:complete-milestone` — Cerrar una versión

Cuando todas las fases de tu milestone están completas y verificadas:

/gsd:complete-milestone

GSD:
- Archiva todos los archivos de planning del milestone
- Crea un **Git tag** (ej. `v1.0.0`) 
- Actualiza STATE.md con "Milestone 1: Complete"

Es como decir "v1.0 está lista. Ship it."

#### `/gsd:new-milestone` — Siguiente versión

Cuando quieres construir más features sobre lo existente:

/gsd:new-milestone

Mismo flujo que `new-project` pero para tu codebase existente. GSD ya conoce tu código. Describes qué quieres agregar → nuevo roadmap → nuevas fases.

#### `/gsd:quick` — Para cosas rápidas

No todo necesita el proceso completo. Para bug fixes, cambios de config, features chiquitas:

/gsd:quick

¿Qué quieres hacer? "Cambiar el color del botón de
login de azul a verde"

Misma calidad (planner + executor) pero salta research, checker, y verifier. Vive en `.planning/quick/`, separado de las fases principales.

---

## Parte 6: La anatomía de un proyecto GSD

Uno de los aspectos más valiosos de GSD es que te obliga a trabajar como trabaja un equipo de desarrollo profesional — sin que te des cuenta. La estructura de archivos que genera **es** el proceso de desarrollo documentado.

### Estructura completa

mi-proyecto/
│
├── PROJECT.md ← 🎯 La visión (siempre cargado)
├── REQUIREMENTS.md ← 📋 Qué se construye
├── ROADMAP.md ← 🗺️ En qué orden
├── STATE.md ← 🧠 Memoria entre sesiones
│
└── .planning/ ← 📁 El proceso documentado
│
├── research/ ← 🔍 Investigación del dominio
│ ├── stack-analysis.md Qué tecnologías usar
│ ├── architecture.md Cómo organizar el código
│ ├── conventions.md Estilo y patrones
│ └── concerns.md Riesgos y deuda técnica
│
├── phases/
│ │
│ ├── 1-CONTEXT.md ← 💬 Decisiones (discuss)
│ ├── 1-RESEARCH.md ← 🔍 Research técnico
│ ├── 1-1-PLAN.md ← 📐 Plan atómico #1
│ ├── 1-2-PLAN.md ← 📐 Plan atómico #2
│ ├── 1-1-SUMMARY.md ← 📝 Qué se hizo
│ ├── 1-2-SUMMARY.md ← 📝 Qué se hizo
│ ├── 1-VERIFICATION.md ← ✅ Verificación auto
│ ├── 1-UAT.md ← 🧪 User Acceptance
│ │
│ ├── 2-CONTEXT.md ← (se repite por fase)
│ ├── 2-RESEARCH.md
│ ├── 2-1-PLAN.md
│ ├── 2-2-PLAN.md
│ ├── 2-3-PLAN.md
│ ├── 2-FIX-1-PLAN.md ← 🔧 Fix plan (si falló algo)
│ └── ...
│
├── quick/ ← ⚡ Tareas rápidas
│ ├── 001-cambio-color/
│ │ ├── PLAN.md
│ │ └── SUMMARY.md
│ └── 002-fix-typo/
│ ├── PLAN.md
│ └── SUMMARY.md
│
└── todos/ ← 💡 Ideas para después
└── ideas.md

### Cómo replica un equipo profesional

```mermaid
graph LR
    subgraph HUMANO["Equipo de 10 personas"]
        PM["Product Manager"] --> ARCH["Arquitecto"]
        ARCH --> DEV["Developers x5"]
        DEV --> QA["QA x2"]
        QA --> RELEASE["Release Manager"]
    end

graph LR
    subgraph GSD_EQ["GSD (tú solo)"]
        NP["new-project = PM"] --> PLAN["plan-phase = Arquitecto"]
        PLAN --> EXEC["execute-phase = Developers"]
        EXEC --> VER["verify-work = QA"]
        VER --> MILE["complete-milestone = Release"]
    end

No necesitas un equipo de 10 personas. GSD te da la estructura y la disciplina de uno — con agentes de IA haciendo cada rol.

Parte 7: Ejemplo completo — De idea a producto terminado

Vamos a caminar juntos por un ejemplo real, paso a paso. El proyecto: RecetApp — una app para organizar recetas de cocina.

Paso 1: Definir (/gsd:new-project)

> /gsd:new-project

GSD: "¿Qué quieres construir?"
Tú:  "Una app web donde guardar mis recetas de cocina, 
      organizarlas por categoría, y buscarlas rápido. 
      Quiero poder marcar favoritas y compartir recetas 
      con un link."

GSD: "¿Quién la va a usar?"
Tú:  "Solo yo por ahora, pero quiero que eventualmente 
      cualquiera pueda crear su cuenta"

GSD: "¿Preferencias de diseño?"
Tú:  "Limpio, minimalista, fotos grandes de las recetas. 
      Tema claro con acentos naranjas."

GSD: "¿Qué datos tiene una receta?"
Tú:  "Título, foto, ingredientes (lista), pasos (lista 
      ordenada), tiempo de prep, porciones, categoría"

GSD: "¿Categorías predefinidas o libres?"
Tú:  "Predefinidas: Desayuno, Almuerzo, Cena, Postre, 
      Snack, Bebidas"

GSD investiga (4 agentes en paralelo, ~5 min) y presenta el roadmap:

📋 ROADMAP — RecetApp

Fase 1: Core
  Modelo de receta + CRUD básico + lista simple

Fase 2: Organización  
  Categorías, favoritos, búsqueda

Fase 3: Media
  Upload de fotos, galería, optimización

Fase 4: Sharing
  URLs públicas, Open Graph, compartir en redes

Fase 5: Auth
  Multi-usuario, registro, login, datos por usuario

Fase 6: Polish
  Responsive, loading states, error handling, PWA

¿Apruebas este roadmap? (sí/no)
> sí

Archivos creados: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md

Paso 2: Discutir Fase 1 (/gsd:discuss-phase 1)

> /gsd:discuss-phase 1

GSD: "Fase 1 es el core: modelo + CRUD + lista. 
      Unas preguntas:"

GSD: "¿La lista muestra tarjetas con foto o solo texto?"
Tú:  "Solo texto por ahora (las fotos son Fase 3). 
      Título + tiempo de prep + categoría"

GSD: "¿Los ingredientes son texto libre o estructurados?"
Tú:  "Estructurados: cantidad + unidad + ingrediente. 
      Ej: '2 tazas de harina'"

GSD: "¿Los pasos tienen fotos o solo texto?"
Tú:  "Solo texto en esta fase"

GSD: "¿Se puede borrar una receta?"
Tú:  "Sí, con confirmación (modal 'Estás seguro?')"

Archivo creado: 1-CONTEXT.md

Paso 3: Planificar Fase 1 (/gsd:plan-phase 1)

> /gsd:plan-phase 1

📋 Investigando...
📐 Creando planes...
✅ Validando planes contra requirements...

3 planes atómicos creados:
  1-1: Schema de base de datos y modelos
  1-2: Formulario de crear/editar receta
  1-3: Lista de recetas + ver detalle + borrar

Archivos creados: 1-RESEARCH.md, 1-1-PLAN.md, 1-2-PLAN.md, 1-3-PLAN.md

Paso 4: Ejecutar Fase 1 (/gsd:execute-phase 1)

> /gsd:execute-phase 1

⚡ Wave 1 (1 plan)
  [1-1] Schema y modelos... 🤖 fresh agent
  [1-1] ✅ → commit: feat(fase-1): schema de recetas

⚡ Wave 2 (2 plans en paralelo)
  [1-2] Formulario CRUD... 🤖 fresh agent
  [1-3] Lista y detalle...  🤖 fresh agent
  [1-2] ✅ → commit: feat(fase-1): formulario de recetas
  [1-3] ✅ → commit: feat(fase-1): lista y detalle

✅ Phase 1 complete! 3/3 plans executed.

Paso 5: Verificar Fase 1 (/gsd:verify-work 1)

> /gsd:verify-work 1

GSD: "¿Puedes crear una receta nueva?"
Tú:  "Sí ✅"

GSD: "¿La ves en la lista?"
Tú:  "Sí ✅"

GSD: "¿Puedes editarla?"
Tú:  "Sí ✅"

GSD: "¿Puedes borrarla?"
Tú:  "Sí, pero no pide confirmación ⚠️"

GSD: "Entendido. Generando fix plan..."

Fix plan generado → ejecutas → verificas de nuevo → todo OK ✅

Paso 6: Repetir para cada fase

/gsd:discuss-phase 2 → /gsd:plan-phase 2 → /gsd:execute-phase 2 → /gsd:verify-work 2
/gsd:discuss-phase 3 → /gsd:plan-phase 3 → /gsd:execute-phase 3 → /gsd:verify-work 3
/gsd:discuss-phase 4 → /gsd:plan-phase 4 → /gsd:execute-phase 4 → /gsd:verify-work 4
/gsd:discuss-phase 5 → /gsd:plan-phase 5 → /gsd:execute-phase 5 → /gsd:verify-work 5
/gsd:discuss-phase 6 → /gsd:plan-phase 6 → /gsd:execute-phase 6 → /gsd:verify-work 6

Paso 7: Cerrar milestone

> /gsd:complete-milestone

🏁 Milestone 1 complete!
   6 phases, 18 plans, 47 files created
   Git tag: v1.0.0
   
¿Quieres iniciar un nuevo milestone? (/gsd:new-milestone)

🎉 RecetApp v1.0 está lista. Con commits limpios, código organizado, y toda la documentación generada automáticamente.

Parte 8: Casos de uso reales

¿Quién está usando GSD?

GSD no es solo teoría. Gente real está construyendo productos reales:

Admin Dashboard completo (auth + créditos + audit logs)
Un developer construyó un panel de administración con login, sistema de créditos, y logs de auditoría. Todo con GSD. El proceso fue:

• new-project → 15 min de preguntas
• 4 fases: auth → CRUD de usuarios → sistema de créditos → audit logs
• 3 días de trabajo total (incluyendo debugging)
• Resultado: código limpio, documentado, desplegado

Security overhaul de una app existente
Un equipo usó map-codebase para analizar su app, identificó vulnerabilidades con el reporte de concerns.md, y ejecutó 3 fases de correcciones de seguridad. Cross-phase integration checks aseguraron que las correcciones no rompieran funcionalidad existente.

Proyectos de solo developers
Múltiples testimonios en Reddit de personas que trabajan solas y reportan "shipping consistente sin degradación de calidad" — exactamente lo que promete GSD.

Las críticas honestas

No todo es perfecto. Estas son las críticas más comunes y mi perspectiva:

Parte 9: Troubleshooting — Qué hacer cuando algo no funciona

"GSD no reconoce los comandos"

> /gsd:help
Claude: No entiendo ese comando

Solución: GSD no está instalado o se instaló en el scope incorrecto.

# Reinstalar
npx get-shit-done-cc@latest

# Elegir: runtime = Claude Code, scope = Global
# Después reiniciar Claude Code

"El execute-phase falla a mitad de camino"

A veces un subagente falla (error de red, rate limit, etc.).

Solución: Correr /gsd:execute-phase de nuevo. GSD revisa qué planes ya se ejecutaron (por los SUMMARY.md) y solo ejecuta los que faltan.

"Los planes son demasiado grandes"

Si un plan tiene más de 5-6 archivos, puede que sea demasiado para un solo subagente.

Solución: En el próximo ciclo, sé más específico en el discuss. Cuantas más decisiones tomes, más granulares (y más pequeños) serán los planes.

"La verificación falla pero no genera fix plan"

A veces el error es de configuración, no de código (ej. falta una variable de entorno).

Solución: Describe el error directamente a Claude: "El error es que falta la variable STRIPE_KEY en .env.local. Agrégala con el valor test_xxx". No necesitas GSD para todo — a veces un comando directo es más rápido.

"Me quedé sin tokens (rate limit)"

El plan Pro de Anthropic tiene un límite diario de tokens. Una sesión intensiva de GSD puede consumirlo.

Solución:

• Planifica tus fases para que no ejecutes más de 2-3 por día
• Usa /gsd:quick para tareas pequeñas (consume menos)
• Las fases de discuss y plan consumen poco — ejecución y verificación consumen más

"Quiero cambiar algo de una fase ya completada"

No puedes re-ejecutar una fase completada directamente.

Solución: Usa /gsd:quick para hacer cambios puntuales a fases anteriores. O, si es un cambio grande, crea un nuevo milestone con la corrección como fase.

Parte 10: El cambio mental

Vibe coding vs Spec-Driven Development — la comparación real

graph LR
    subgraph VC["Vibe Coding"]
        V1["Min 0-30 🚀 Rápido"] --> V2["Min 30-60 🐌 Frena"]
        V2 --> V3["Hora 1-3 🔄 Bugs"]
        V3 --> V4["Hora 3+ 💀 Reset"]
    end

graph LR
    subgraph SDD_T["Spec-Driven Development"]
        S1["Min 0-30 📋 Specs"] --> S2["Min 30-90 ⚡ Fase 1+2"]
        S2 --> S3["Hora 1-3 ⚡ Fases 3-5"]
        S3 --> S4["Hora 3 ✅ Completo"]
    end

La verdad incómoda

Vibe coding se siente productivo. Spec-Driven Development es productivo. Y hay una diferencia enorme entre sentirse productivo y serlo.

La IA es una herramienta increíblemente poderosa. Pero como cualquier herramienta poderosa, necesita dirección. Un taladro en manos de alguien con planos hace un agujero perfecto. Un taladro en manos de alguien que improvisa hace un hueco en la pared del vecino.

Tus specs son los planos. GSD es el proceso. La IA es el taladro. Tú decides dónde va el agujero.

Empieza hoy

# 1. Instala
npm install -g @anthropic-ai/claude-code
npx get-shit-done-cc@latest

# 2. Crea un proyecto nuevo
cd ~/mi-proyecto
claude --dangerously-skip-permissions

# 3. Define
/gsd:new-project

# 4. Construye fase por fase
/gsd:discuss-phase 1
/gsd:plan-phase 1
/gsd:execute-phase 1
/gsd:verify-work 1

# 5. Repite para cada fase
# 6. Cierra: /gsd:complete-milestone

Eso es todo. Tu primer proyecto con Spec-Driven Development.

Sin adivinar. Sin rezar. Sin vibe coding a ciegas.

Tu proyecto — y tu cordura — te lo van a agradecer.

¿Usaste GSD o Spec-Driven Development? Me encantaría saber tu experiencia. Escríbeme en @bottico.