Spec-Driven Development: cómo GSD resuelve el mayor problema del AI coding

Llevas 45 minutos en una sesión de Claude Code. El feature empezó bien — modelos limpios, API endpoints correctos, tests pasando. Pero ahora estás en el controller número 8 y algo cambió. Claude empieza a devolver funciones con // TODO: implement donde antes escribía lógica completa. Los nombres de variables se vuelven genéricos. Las respuestas son más cortas. Le pides que implemente el webhook handler y te devuelve un stub de 4 líneas cuando hace 20 minutos te habría dado 60 líneas con error handling, retry logic y logging.

Felicidades: acabas de experimentar context rot.

No es un bug. No es que Claude se haya "cansado". Es matemática pura: el context window tiene un límite (200K tokens en Claude), y conforme se llena con el historial de tu conversación, la calidad del output se degrada de forma predecible. Anthropic lo sabe. Tú lo sabes. Y sin embargo, cada vez que arrancas un feature complejo, terminas en el mismo lugar.

Este artículo no es sobre quejarse del problema. Es sobre resolverlo. Vamos a hablar de Spec-Driven Development — un paradigma que cambia la forma en que interactúas con AI para escribir código — y de GSD (Get Shit Done), la herramienta open source que lo implementa y que en 2 meses acumuló más de 18,000 estrellas en GitHub.

¿Qué es Spec-Driven Development?

Si vienes del mundo de software, conoces TDD (Test-Driven Development): escribes el test primero, después el código. Conoces BDD (Behavior-Driven Development): describes el comportamiento esperado en lenguaje natural, después implementas. Ambos parten de la misma idea: define qué quieres antes de escribir cómo lo haces.

Spec-Driven Development (SDD) lleva esta idea a su conclusión lógica para la era del AI coding. La diferencia fundamental es una:

En TDD y BDD, el consumidor de las specs es un humano. En SDD, el consumidor es un LLM.

Y eso cambia todo.

Cuando un humano lee un spec, llena gaps con experiencia, intuición y conocimiento implícito del proyecto. Cuando un LLM lee un spec, toma lo que está escrito de forma literal. Si el spec dice "implementar autenticación", un dev senior sabe que eso incluye hashing de passwords, rate limiting, refresh tokens y session management. Un LLM podría darte un if password == stored_password y técnicamente cumplió el spec.

SDD propone que las especificaciones deben ser:

• Completas: todo lo que el LLM necesita saber, explícito. Nada implícito.
• Atómicas: cada spec debe caber dentro de un context window sin degradar.
• Jerárquicas: del proyecto completo → a la fase → al plan individual → a la tarea.
• Machine-readable: estructuradas para que el LLM las consuma eficientemente (no prosa libre).

En la práctica, SDD se ve así: antes de que el LLM escriba una sola línea de código, ya existen archivos que describen los requirements, el roadmap de fases, los planes atómicos de cada fase, y el contexto técnico del codebase. El LLM no necesita "recordar" lo que hiciste hace 40 minutos — lo lee del filesystem.

Por qué el problema es especialmente grave en microservicios

Si trabajas en un monolito, el context rot es molesto pero manejable. Tu codebase tiene una estructura, un framework, un set de convenciones. Claude puede inferir bastante del código existente.

Pero si trabajas con microservicios — y si estás leyendo este blog, es probable que sí — el problema se multiplica exponencialmente.

Piensa en un escenario típico de una fintech LATAM:

├── auth-service/          (Node.js + Express)
├── payments-service/      (Go)
├── notifications-service/ (Python + FastAPI)
├── risk-service/          (Python + ML models)
├── gateway/               (Kong/Nginx)
└── shared-protos/         (gRPC definitions)

Cada servicio tiene su propio repo, su propio stack, sus propias convenciones. El dev que trabaja en payments-service no tiene el contexto de cómo auth-service valida tokens. El dev que implementa notifications-service no sabe que payments-service ya tiene un retry mechanism que podría reusar.

Y cuando le pides a Claude Code que trabaje en un servicio, solo ve ese servicio. No tiene contexto de:

• Las interfaces entre servicios (gRPC contracts, event schemas)
• Las decisiones arquitecturales que afectan a todos (por qué usamos eventual consistency acá)
• Las convenciones del equipo (cómo nombramos endpoints, cómo manejamos errores)
• El estado actual de features que cruzan servicios

Cada sesión de Claude es una isla. Y el "context rot" no es solo dentro de una sesión — es entre sesiones, entre devs, entre servicios. Es context fragmentation a nivel de equipo.

GSD: la herramienta que resuelve esto

GSD (Get Shit Done) es una herramienta open source que implementa Spec-Driven Development como un flujo concreto de comandos. Los números hablan solos:

• 18,345 ⭐ en GitHub en ~2 meses
• 1,646 forks, 165 issues abiertos
• Creado el 14 de diciembre de 2025
• MIT License
• Funciona con Claude Code, OpenCode, Gemini CLI y Codex
• npm: get-shit-done-cc

No es un wrapper cosmético. Es un sistema de orquestación que cambia fundamentalmente cómo un LLM interactúa con tu codebase.

Qué genera GSD

Cuando usas GSD, tu proyecto termina con esta estructura:

proyecto/
├── PROJECT.md          # Nombre, descripción, stack
├── REQUIREMENTS.md     # Specs completas del proyecto
├── ROADMAP.md          # Fases ordenadas con dependencias
└── .planning/
    ├── STACK.md        # Stack técnico detectado
    ├── ARCHITECTURE.md # Arquitectura del codebase
    ├── CONVENTIONS.md  # Convenciones de código
    ├── CONCERNS.md     # Problemas detectados
    ├── phase-1/
    │   ├── CONTEXT.md      # Decisiones de la discusión
    │   ├── plans/
    │   │   ├── 01-user-model.md
    │   │   ├── 02-auth-endpoints.md
    │   │   └── 03-middleware.md
    │   ├── VALIDATION.md   # Resultado del plan checker
    │   └── UAT.md          # Resultado de verificación
    └── phase-2/
        └── ...

Cada archivo tiene un propósito. Cada archivo cabe en un context window. Cada archivo es la fuente de verdad para una pieza específica del proyecto.

Los 6 comandos

La arquitectura de subagentes frescos

Acá está la magia. Cuando GSD ejecuta una fase, no lo hace en tu sesión actual de Claude. Lanza subagentes frescos, cada uno con 200K tokens limpios.

Cada executor recibe solo los archivos relevantes para su plan:

• El plan atómico que le toca (ej: 01-user-model.md)
• Los archivos de contexto necesarios (STACK.md, CONVENTIONS.md)
• El código fuente directamente relacionado

No recibe el historial de tu conversación. No recibe los planes de otros executors. No recibe el README del proyecto ni los tests de otro módulo. Context loading selectivo.

Ejecución en waves

GSD construye un DAG (Directed Acyclic Graph) de dependencias entre los planes y los agrupa en waves:

Los planes sin dependencias entre sí se ejecutan en paralelo. Cada wave espera a que la anterior termine. El resultado: un feature que tomaría una sesión larga y degradada se ejecuta como múltiples sesiones cortas y óptimas.

XML prompt formatting

Un detalle que pasa desapercibido pero es crucial: GSD usa XML structured prompts para comunicarse con los LLMs. No es prosa libre ni markdown — es XML con tags semánticos que el LLM parsea con mucha mayor precisión:

<plan>
  <context>
    <file path="src/models/user.ts" relevance="primary"/>
    <file path="src/config/database.ts" relevance="secondary"/>
    <convention name="orm">Prisma with PostgreSQL</convention>
  </context>
  <tasks>
    <task id="1" type="create" path="src/models/payment.ts">
      Create Payment model following User model conventions
    </task>
    <task id="2" type="modify" path="src/config/database.ts">
      Add Payment model to Prisma schema
    </task>
  </tasks>
  <verification>
    <check type="typecheck">npx tsc --noEmit</check>
    <check type="test">npm test -- --grep "Payment"</check>
  </verification>
</plan>

Esto no es decorativo. Los LLMs procesan XML de forma más estructurada que markdown o texto libre. Cada task tiene un tipo, un path y una instrucción clara. Cada verificación es ejecutable. No hay ambigüedad.

Caso de uso real: feature nueva en microservicio existente

Vamos al terreno práctico. Escenario: tienes payments-service corriendo en producción, y necesitas agregar webhook notifications para que los merchants sepan cuando un pago cambia de estado.

Paso 1: Mapear el codebase existente

# En la terminal, dentro de payments-service/
claude

> /gsd:map-codebase

GSD lanza agentes de análisis que recorren tu código. En 2-3 minutos genera:

<!-- .planning/STACK.md -->
## Stack
- Runtime: Node.js 20 + TypeScript 5.3
- Framework: Express 4.18
- ORM: Prisma 5.8 + PostgreSQL 15
- Queue: BullMQ + Redis
- Auth: JWT validation via gateway
- Testing: Vitest + Supertest

## Key Dependencies
- @prisma/client: 5.8.1
- bullmq: 5.1.0
- zod: 3.22 (validation)

<!-- .planning/ARCHITECTURE.md -->
## Structure
src/
├── controllers/    # Express route handlers
├── services/       # Business logic layer
├── models/         # Prisma schema + types
├── queues/         # BullMQ job definitions
├── middleware/      # Auth, error handling, logging
└── utils/          # Shared helpers

## Patterns
- Controller → Service → Model (strict layering)
- All async errors caught by middleware
- Queue jobs for anything that takes >200ms

<!-- .planning/CONCERNS.md -->
## ⚠️ Concerns Detected
1. No retry mechanism on queue failures (fire-and-forget)
2. Missing index on payments.merchant_id (used in 4 queries)
3. Error responses inconsistent between controllers

Ese CONCERNS.md vale oro. GSD acaba de encontrar un missing index que probablemente lleva meses en producción.

Paso 2: Discutir la fase

> /gsd:discuss-phase 1

Claude te hace preguntas:

GSD identified the following gray areas for Phase 1 (Webhook Notifications):

1. DELIVERY GUARANTEE: Should webhooks be at-least-once or exactly-once?
   → At-least-once is simpler but merchants need idempotency keys
   
2. RETRY STRATEGY: How many retries? What backoff?
   → Common patterns: 3 retries, exponential backoff (1m, 5m, 30m)
   
3. SIGNATURE: How should we sign webhook payloads?
   → HMAC-SHA256 with per-merchant secret is industry standard
   
4. EVENTS: Which payment state transitions trigger webhooks?
   → Suggest: payment.created, payment.completed, payment.failed, payment.refunded

Please provide your decisions for each.

Tú respondes con tus decisiones. GSD las persiste en CONTEXT.md. Esas decisiones nunca se pierden — están en el filesystem, no en el context window.

Paso 3: Planificar

> /clear
> /gsd:plan-phase 1

GSD genera planes atómicos:

<!-- .planning/phase-1/plans/01-webhook-model.md -->
# Plan 01: Webhook Subscription Model

## Context Files
- .planning/STACK.md
- .planning/CONVENTIONS.md
- prisma/schema.prisma

## Tasks
1. Add WebhookSubscription model to Prisma schema
   - Fields: id, merchantId, url, secret, events[], active, createdAt
   - Index on merchantId + active
2. Add WebhookDelivery model for delivery tracking
   - Fields: id, subscriptionId, event, payload, status, attempts, lastAttemptAt
3. Generate and run migration
4. Create TypeScript types in src/models/webhook.types.ts

## Verification
- [ ] `npx prisma validate` passes
- [ ] `npx prisma migrate dev` succeeds
- [ ] Types compile: `npx tsc --noEmit`

## Size: 4 tasks | Estimated: ~15 min

Hay quizás 4-5 planes similares: el modelo, el servicio de firma y envío, el queue job con retries, los endpoints de suscripción, y los tests.

Después, un plan checker agent valida que los planes sean coherentes entre sí, que no haya dependencias circulares, y que cada plan sea lo suficientemente atómico.

Paso 4: Ejecutar

> /clear
> /gsd:execute-phase 1

GSD construye el DAG, determina las waves, y lanza los executors. Los commits llegan atómicos:

✅ Wave 1 complete:
  - feat(webhook): add WebhookSubscription and WebhookDelivery models
  - feat(webhook): add webhook signing and delivery service

✅ Wave 2 complete:
  - feat(webhook): add BullMQ job for webhook delivery with retries
  - feat(webhook): add subscription management endpoints

✅ Wave 3 complete:
  - test(webhook): add integration tests for webhook delivery flow

Paso 5: Verificar

> /clear
> /gsd:verify-work 1

GSD corre los tests, verifica que el typecheck pase, y genera un UAT.md con el resultado. Si algo falla, lanza debug agents que intentan fixearlo automáticamente.

Resultado final: un feature completo con 5 commits atómicos, tests, y documentación — sin context rot en ningún momento.

Caso de uso real: microservicio nuevo desde cero

Escenario más ambicioso: necesitas crear un risk-assessment-service para tu fintech. Este servicio evalúa transacciones en tiempo real y asigna un risk score.

El Q&A con Claude

mkdir risk-assessment-service && cd risk-assessment-service
git init
claude

> /gsd:new-project

Claude empieza un Q&A:

Let's define your project. I'll ask questions to understand scope:

1. What does this service do in one sentence?
→ Real-time transaction risk scoring for a payments platform

2. What's the tech stack preference?
→ Python 3.12, FastAPI, PostgreSQL, Redis for caching

3. Who consumes this service?
→ payments-service calls it synchronously before processing payments

4. What are the key features?
→ Rule engine, ML model scoring, velocity checks, manual review queue

5. What's the scale expectation?
→ ~1000 transactions/minute, p99 latency <200ms

6. Any compliance requirements?
→ PCI DSS logging requirements, audit trail for all decisions

Con tus respuestas, GSD lanza 4 agentes de research en paralelo:

1. Architecture researcher: evalúa patterns para real-time scoring
2. Stack researcher: valida que FastAPI + PostgreSQL sea la mejor opción para el use case
3. Security researcher: analiza requerimientos PCI DSS
4. Integration researcher: define cómo se comunica con payments-service

Los 4 reportan al orchestrator, que genera:

<!-- REQUIREMENTS.md (extracto) -->
## Core Requirements

### R1: Synchronous Risk Scoring API
- POST /assess endpoint
- Input: transaction details (amount, merchant, payer, metadata)
- Output: risk_score (0-100), decision (approve/review/decline), reasons[]
- SLA: p99 < 200ms

### R2: Rule Engine
- Configurable rules in database (not hardcoded)
- Rules: velocity (5+ txns in 1 min), amount thresholds, blocked merchants
- Rules evaluated in parallel, scores aggregated

### R3: ML Model Integration  
- Pluggable model interface (start with rules-only, add ML later)
- Model versioning with A/B testing support
- Fallback to rules-only if model timeout

### R4: Manual Review Queue
- Transactions scoring 40-70 go to review queue
- Reviewer dashboard API (list, approve, decline)
- SLA: reviewed within 30 minutes
...

<!-- ROADMAP.md -->
## Phase 1: Core API + Rule Engine
- Risk scoring endpoint
- Basic rule engine (velocity, amount, blocklist)
- Redis caching for velocity checks
- ~3-4 plans

## Phase 2: ML Model Integration
- Model interface + registry
- Scoring pipeline with model + rules aggregation
- A/B testing framework
- ~3 plans

## Phase 3: Review Queue + Dashboard API
- Review queue with SLA tracking
- Dashboard endpoints
- Notification when SLA approaching
- ~3 plans

## Phase 4: Observability + Compliance
- PCI DSS compliant logging
- Audit trail
- Metrics + alerting
- ~2 plans

Después sigues la filosofía discuss → plan → execute para cada fase:

> /gsd:discuss-phase 1    # Resolver gray areas
> /clear
> /gsd:plan-phase 1       # Generar planes atómicos
> /clear
> /gsd:execute-phase 1    # Ejecutar con subagentes frescos
> /clear
> /gsd:verify-work 1      # UAT

De cero a un microservicio funcional con API, rule engine, tests y documentación. Cada fase construye sobre la anterior sin perder contexto.

Caso de uso real: feature multi-servicio

El caso más complejo y honestamente donde GSD todavía tiene limitaciones. Escenario: implementar una "Digital Wallet" que toca 4 servicios:

auth-service       → Wallet identity + permissions
payments-service   → Fund wallet, withdraw from wallet
ledger-service     → Double-entry bookkeeping
notifications-service → Transaction alerts

Cómo se hace hoy (sin multi-repo nativo)

GSD actualmente trabaja dentro de un repo. No tiene soporte nativo para orquestar entre múltiples repos. Pero se puede hacer manualmente:

Paso 1: Definir contratos primero

# En shared-protos/ o un repo de contracts
claude
> /gsd:new-project
# Define los event schemas y API contracts que los 4 servicios compartirán

Esto genera los contratos: gRPC protos, event schemas (JSON Schema), API specs. Esta es tu fuente de verdad compartida.

Paso 2: Ejecutar en cada servicio con el contrato como contexto

# En auth-service/
claude
> /gsd:map-codebase
> /gsd:discuss-phase 1
# Copia el contrato relevante a .planning/CONTEXT.md
> /gsd:plan-phase 1
> /gsd:execute-phase 1

# En payments-service/
claude
> /gsd:map-codebase
# Misma danza: discuss → plan → execute

Paso 3: Integration testing manual

La verificación cross-service la haces tú. GSD verifica dentro del servicio, pero la integración entre servicios requiere tu criterio.

El workflow multi-servicio se ve así:

1. Contracts repo: define interfaces con GSD
2. Servicio por servicio: map → discuss → plan → execute → verify
3. Integration: docker-compose up + manual testing
4. Iterate: si la integración falla, vuelves al servicio específico

No es mágico. Pero es infinitamente mejor que tener a Claude tratando de entender 4 servicios en una sola sesión de 200K tokens.

Mejores prácticas y anti-patterns

Después de usar GSD en proyectos reales, estos son los errores que todos cometemos al principio (y cómo evitarlos):

❌ Los 5 errores más comunes

✅ Cómo escribir buen REQUIREMENTS.md

<!-- ❌ MAL: vago, implícito, no-actionable -->
## Requirements
- User authentication
- Payment processing
- Notifications

<!-- ✅ BIEN: específico, explícito, verificable -->
## R1: JWT Authentication
- Validate RS256 JWT tokens from auth-service
- Extract merchant_id from token claims
- Return 401 with error body: { "error": "unauthorized", "detail": "..." }
- Rate limit: 100 req/min per merchant_id

## R2: Payment Processing
- POST /payments accepts: { amount, currency, merchant_id, metadata }
- Validate amount > 0, currency in [USD, COP, MXN, BRL]
- Idempotency key via X-Idempotency-Key header (UUID v4)
- Response includes payment_id, status, created_at

La diferencia es que el REQUIREMENTS.md bueno se puede convertir directamente en un plan atómico. El malo requiere que el LLM asuma — y ya sabemos cómo termina eso.

Comparativa rápida

Porque todo el mundo quiere saber: "¿y qué tiene de diferente a X?"

¿Cuándo usar cada una?

• Bug fix rápido o exploración: Claude Code vanilla o Plan Mode. No necesitas GSD para cambiar un color.
• Feature compleja en un servicio: GSD. El discuss → plan → execute vale la pena.
• Proyecto nuevo desde cero: GSD con new-project. Te ahorra horas de setup y diseño.
• Ya estás en GitHub Copilot: Workspace es más natural para tu workflow.
• Quieres fire-and-forget: Devin, si puedes justificar los $500/mes.

Los red flags que debes conocer

No sería un artículo honesto si no mencionara las cosas que me hacen levantar una ceja. La transparencia es más útil que el hype.

🚩 El token $GSD en Solana

Sí, hay un token de criptomoneda $GSD en Solana. El link a Dexscreener estaba en el README del proyecto. Para una herramienta de desarrollo open source, esto es... inusual. No digo que invalide la herramienta, pero es un data point que debes tener.

🚩 --dangerously-skip-permissions

GSD requiere que corras Claude Code con --dangerously-skip-permissions para que los subagentes puedan ejecutar sin confirmación manual. El nombre del flag existe por una razón — le estás dando al LLM permiso para ejecutar comandos sin tu aprobación en cada paso. Para un proyecto personal está bien. Para un repo con acceso a producción, piénsalo dos veces.

🚩 Single maintainer

El proyecto es mantenido primordialmente por una persona (glittercowboy/TÂCHES). 18K stars con un solo maintainer es impresionante pero también es un riesgo: bus factor de 1. Si esa persona deja el proyecto, ¿quién lo mantiene?

✅ Lo que contrarresta

• MIT License: puedes forkearlo mañana si es necesario
• La herramienta funciona: no es vaporware. La usan ingenieros de Amazon, Google, Shopify y Webflow
• La comunidad es activa: 1,646 forks, 165 issues abiertos con discusión real
• El código es auditable: puedes leer exactamente qué hace cada prompt

Mi postura: úsalo con los ojos abiertos. Lee los prompts que genera. Entiende qué permisos le estás dando. No corras con skip-permissions en repos de producción sin un sandbox. Pero si haces eso, es una herramienta genuinamente útil.

Cómo empezar hoy

La instalación toma literalmente 10 segundos:

# Instalar (requiere Node.js 18+)
npx get-shit-done-cc@latest

# O global para usarlo en cualquier proyecto
npx get-shit-done-cc@latest --global

Tu primer proyecto con GSD

# 1. Crea un directorio y abre Claude Code
mkdir mi-proyecto && cd mi-proyecto
git init
claude --dangerously-skip-permissions

# 2. Define el proyecto
> /gsd:new-project

# 3. Responde el Q&A (5-10 preguntas)

# 4. Sigue el flujo para la fase 1
> /clear
> /gsd:discuss-phase 1
> /clear
> /gsd:plan-phase 1
> /clear
> /gsd:execute-phase 1
> /clear
> /gsd:verify-work 1

Para un codebase existente

cd mi-codebase-existente
claude --dangerously-skip-permissions

# Mapea primero
> /gsd:map-codebase

# Lee CONCERNS.md — en serio, léelo
> cat .planning/CONCERNS.md

# Después el flujo normal
> /gsd:discuss-phase 1
# ...

Conclusión

El context rot no es un problema que se va a resolver con context windows más grandes. Ya pasamos de 8K a 200K tokens y el problema persiste — solo se movió. La solución no es más memoria, es mejor arquitectura de cómo usamos la memoria que tenemos.

Spec-Driven Development es esa arquitectura. Y GSD es la implementación más pragmática que he visto hasta ahora. No es perfecta — el token de Solana es raro, el skip-permissions me pone nervioso, y la falta de multi-repo nativo duele si trabajas con microservicios grandes. Pero funciona. Y funciona notablemente bien para algo que tiene 2 meses de vida.

18,345 estrellas en 2 meses no mienten. Algo está resonando con la comunidad de devs que usan AI para codear. Y creo que lo que resuena es simple: por fin alguien resolvió el problema que todos teníamos y nadie estaba atacando de forma sistemática.

Si ya usas Claude Code, Gemini CLI o cualquier AI coding tool, dale una oportunidad a GSD. El peor caso es que pierdes 10 minutos instalándolo. El mejor caso es que cambias fundamentalmente cómo construyes software.

Y si lo usas y descubres algo interesante — mejores prácticas, anti-patterns, workarounds para multi-repo — comparte. La comunidad está creciendo rápido y el conocimiento colectivo es lo que va a llevar esta herramienta al siguiente nivel.

npx get-shit-done-cc@latest — y a mover la aguja.