Spec-driven development

En el capítulo anterior vimos el proceso de construir un producto digital con Claude Code. Pero el proceso es el esqueleto: te dice qué fases atraviesa un proyecto. Lo que separa una demo de un producto de verdad es otra cosa —el contexto que le das a la IA en cada fase—.

Hacer "vibe coding" a pelo funciona para un prototipo. Para producto real, en cliente, necesitas precisión: que la IA construya lo correcto a la primera, no a la quinta. Ahí es donde entra la spec-driven development, y donde hemos codificado nuestra forma de trabajar en skills propias para que cualquiera del equipo —y la IA— siga el mismo método.

Del prompt al contexto

La IA no construye lo que le pides; construye lo que entiende de tu contexto. Un prompt vago da un resultado genérico, aunque el modelo sea excelente. El problema casi nunca es el modelo: es que le llega poco contexto o contexto ambiguo.

Spec-driven development le da la vuelta a esto: en vez de improvisar mientras generas, el trabajo duro —decidir el producto, investigar el código, planear— ocurre antes y queda escrito. Menos reintentos, menos "no era esto", menos deuda técnica nacida de malentendidos.

Qué es una spec ejecutable

Una spec no es documentación para archivar: es un artefacto ejecutable. Lo bastante preciso como para que un implementador —humano o IA— sepa exactamente qué construir sin volver a preguntar por decisiones de producto.

El flujo tiene tres artefactos, y —esto es lo importante— una puerta de revisión humana entre cada par. No pasas de uno al siguiente sin mirar:

• El PRD — qué construimos y para quién.
• La spec — cómo, con precisión quirúrgica y anclada al código real.
• La implementación — el código, endurecido con revisión.

Cada puerta caza un tipo distinto de error antes de que salga caro:

Y las puertas mandan hacia atrás, no hacia los lados: la spec depende del PRD, el código depende de la spec. Si a mitad de implementación aparece una contradicción, se vuelve a la puerta anterior y se corrige ahí —nunca se parchea a ciegas—.

¿Cuándo merece la pena?

Spec-driven no es para todo. Aplicarlo a un cambio de una línea es burocracia. La heurística que usamos:

• Escribe spec cuando el cambio toca varios archivos o tiene blast radius real —tocar del orden de cuatro archivos ya es buena señal—, cuando el requisito admite varias interpretaciones, o cuando equivocarse sale caro.
• Sáltatela para un one-liner, un ajuste de copy o un cambio trivial sin riesgo. Para eso nch-dev tiene una ruta one-shot que no monta todo el aparato.

Y una honestidad que ahorra frustración: el retorno no es inmediato. Las primeras features parecen más lentas que lanzarte a codear. El beneficio se compone: hacia la cuarta o quinta, los errores de diseño que la spec cazó a tiempo te ahorran reescrituras que habrían costado días. Aplícalo donde el coste de equivocarse es alto, no donde da igual.

Nuestras skills: nch-product-kit

Hemos empaquetado nuestro flujo en un plugin de Claude Code, el nch-product-kit, con tres skills que van de idea de cliente a código:

El flujo completo: nch-prd → PRD → nch-spec (feature a feature) → spec ready-for-dev → nch-dev. Es autosuficiente (no depende de nada externo), habla español por defecto y se personaliza por proyecto sin tocar el plugin.

nch-prd — de la idea al PRD

Actúa como un product manager senior de agencia. Digiere lo que hay —notas de reunión, la propuesta, tu propia descripción— y hace las preguntas que aterrizan la idea. Lo más característico de trabajar en agencia: separa lo que podemos responder nosotros de lo que solo puede responder el cliente. Lo segundo queda registrado en un client-questions.md con un valor por defecto, para no bloquear el trabajo esperando una respuesta.

El resultado es un PRD con features, requisitos funcionales numerados (FR-1…FR-N) con consecuencias testeables, user journeys, glosario y un alcance de MVP explícito —lo que entra y lo que no—. Y una regla de honestidad: nada inferido se presenta como decidido; lleva su etiqueta [ASSUMPTION].

Antes de dar el PRD por bueno, lo pasamos por un red-team: un subagente lo lee en frío, sin el sesgo de quien lo escribió, y busca los huecos de asunción. Es la primera puerta de revisión, y caza problemas cuando aún son baratos.

nch-spec — de feature a spec lista para dev

Por cada feature del PRD, nch-spec hace dos cosas a la vez: te entrevista como product person e investiga el código en bucle hasta tener contexto suficiente. Y "suficiente" no es una sensación, es un estándar. La investigación no termina hasta poder responder, sin adivinar:

• Dónde cambia el código y qué lo rodea.
• Cómo funciona hoy esa zona, leído en el código, no inferido de los nombres.
• Por qué falla (en bugs), con la causa raíz trazada.
• Qué puede romperse —el blast radius: quién llama, quién consume, qué estado se comparte—.
• Qué necesita el producto —problema, valor, criterios de éxito— confirmado contigo.

La spec resultante cumple el estándar Ready for Development:

• Accionable — cada tarea con su archivo y su acción concreta.
• Lógica — tareas ordenadas por dependencia.
• Testable — criterios de aceptación en formato Given / When / Then.
• Completa — sin placeholders ni TBDs.
• Anclada — cada archivo del mapa de código se leyó de verdad durante la investigación; nunca se adivina.

Va acotada: un solo objetivo de usuario, en un tamaño pensado para que el implementador no pierda contexto por el camino. Y no muere al terminar la feature: la spec sigue viva. Cada corrección que aparece durante la implementación vuelve a ella, para que el documento y el código no diverjan. Una spec que arranca el proyecto y luego se olvida es una spec muerta.

nch-dev — de spec a código, con revisión adversarial

El pensamiento pesado ya ocurrió, así que nch-dev ejecuta con disciplina: toma una spec ready-for-dev, fija una baseline e implementa por tareas, siguiendo la arquitectura y las convenciones que ya existen en el proyecto (no las suyas).

Lo que marca la diferencia es cómo la endurece: separa el rol de quien construye del de quien revisa, con una revisión adversarial a tres bandas, ninguna complaciente.

• Blind hunter — busca fallos a ciegas, sin conocer la intención.
• Edge-case hunter — recorre límites y casos límite: vacíos, permisos, fallos parciales.
• Acceptance auditor — comprueba que se cumplen los criterios de aceptación de la spec.

Cuando un revisor encuentra algo que nace de la propia spec, hay loopback a la puerta anterior: se corrige en la spec y se vuelve, en vez de parchear. Para cambios triviales y sin riesgo existe la ruta one-shot que no monta todo el aparato. Todo se mueve sobre estados compartidos: draft → ready-for-dev → in-progress → in-review → done.

Por qué skills propias y no prompts sueltos

• Método codificado. Nuestra forma de hacer PRDs, specs y revisiones vive en el plugin, no en la cabeza de cada persona.
• Consistencia. Cualquiera del equipo —o la IA— sigue el mismo flujo y produce artefactos comparables.
• Contexto por proyecto. Se ajusta por repo (stack, comandos de test, políticas de alcance) sin tocar el plugin.
• Autosuficiente. No depende de nada externo, y los estados de spec son estándar, así que las piezas son intercambiables.

Cómo lo instalamos

En cualquier repo de cliente, dentro de Claude Code:

/plugin marketplace add nocodehackers-studio/nch-claude-plugins
/plugin install nch-product-kit@nocodehackers

Mejor aún: dejándolo en el .claude/settings.json del repo, Claude Code ofrece instalar el plugin a todo el que abra el proyecto —el método viaja con el código—.

{
  "extraKnownMarketplaces": {
    "nocodehackers": {
      "source": { "source": "github", "repo": "nocodehackers-studio/nch-claude-plugins" }
    }
  },
  "enabledPlugins": { "nch-product-kit@nocodehackers": true }
}

Un ejemplo de verdad

Este mismo handbook es un caso. El PRD de su vuelta de diseño lo escribimos con nch-prd: el mismo PM experto, las mismas preguntas, el mismo formato de features y requisitos numerados. El método no es teoría de manual — es lo que usamos a diario para construir producto.

Ingeniería de bucles: quédate siendo el ingeniero

Las skills y los tres artefactos no son pasos sueltos: son un bucle que puedes diseñar. Claude Code como motor, el MCP dándole manos y ojos, las skills poniendo tu método, los subagentes separando a quien construye de quien revisa, y los propios artefactos (PRD, spec, estados) haciendo de memoria externa entre sesiones. En vez de re-prompt a mano una y otra vez, diseñas el sistema que itera hacia el objetivo.

Pero automatizar el bucle no es delegar el criterio. Cuanto más rápido produce, más fácil es dormirse. Los principios que no negociamos:

• La verificación sigue siendo tuya. El bucle amplifica también los errores que no vigilas.
• Evita la rendición cognitiva. Aceptar todo lo que sale del bucle es cómodo y peligroso.
• Ojo con la deuda de comprensión. Cuanto más rápido lanzas, mayor el hueco entre el código que existe y lo que de verdad entiendes. Ese hueco se paga.

Construye el bucle — pero constrúyelo como quien quiere seguir siendo el ingeniero, no solo quien pulsa "go". Spec-driven development no consiste en escribir más documentación: consiste en poner el criterio delante del código, para que la IA construya lo correcto a la primera. Y con nuestras skills, ese criterio deja de vivir en la cabeza de cada uno y pasa a ser reproducible.

Lecturas

Ideas que dan forma a este capítulo, si quieres profundizar:

• Using Spec-Driven Development with Claude Code — heeki.
• Spec-Driven Development with Claude Code — DataCamp.
• Loop Engineering — Addy Osmani.