Introducción

El sueño de separar el “qué” del “cómo” en el desarrollo de software es casi tan antiguo como la propia ingeniería del software. Ya en los años 70, Winston Royce formalizó el modelo en cascada con la misma premisa: si escribes los requisitos con suficiente precisión antes de tocar el código, la implementación es casi mecánica. Esa idea nunca ha muerto del todo. Entre otros escenarios: reapareció en el modelado UML de los 90, en los documentos de requisitos funcionales de los 2000 y en las especificaciones formales de BDD con Cucumber. Es comprensible y obedece a la intención razonable de domesticar el caos del software con la claridad del lenguaje. Sin embargo, a principios de siglo XXI, las metodologías ágiles llegaron con una idea incómoda pero difícil de rebatir: ningún documento sobrevive al contacto con la realidad. Scrum, XP y sus derivados demostraron en la práctica que iterar rápido con feedback continuo era mucho más efectivo que cualquier especificación previa, por detallada que fuera. Y así ha sido hasta la irrupción de la IA.

Desde la llegada de los agentes de IA en 2024 se están probando distintas técnicas para desarrollar código de forma asistida. La más disparatada, al menos hasta ahora, ha sido el vibe coding, un término que acuñó Andrej Karpathy, una gran referencia en el sector, para describir personas sin conocimientos técnicos que construyen software a base de describir lo que quieren en lenguaje natural en prompts random, sin entender ni revisar el código que el modelo genera.

Como reacción -o cuanto menos como alternativa- nació la Spec-Driven Development con IA, conocida como SDD. La idea central es simple: en lugar de darle instrucciones sueltas a un agente, primero escribes una especificación estructurada en lenguaje natural -normalmente en Markdown- que el agente usa como fuente de verdad para generar el código. Una especie de prompts ordenados y jerarquizados que buscan darle a la IA el contexto más preciso posible antes de que toque una sola línea.

En torno al SDD están surgiendo distintas herramientas como SpecKit, Tessl o Kiro, de las que quizás la más interesante sea SpecKit, en tanto que también es una propuesta metodológica, aunque me faltan horas de análisis para afirmarlo con más seguridad. Vamos a ver cómo funciona, pero antes es importante reseñar que el SDD también es objeto de fuertes críticas.

¿Vuelta al pasado?

Entre otros problemas, se ha dicho que el SDD repite el error clásico del modelo en cascada (waterfall): asumir que se puede recopilar toda la información relevante antes de construir. La información más importante surge durante la construcción, no antes. O al menos eso se argumentaba desde el agilismo cuando propusieron todos sus cambios metodológicos a principios del XXI.

A partir de esa idea central, se derivan distintas críticas similares, de las que resumo tres que van en la línea:

• En desarrollo tradicional, una spec desactualizada es un inconveniente. En desarrollo agéntico, es peligrosa, ya que el agente ejecutará con confianza contra requisitos que ya no reflejan la realidad.
• El trabajo real requiere la alineación de diseño, producto, DevOps y negocio. Ningún Markdown, por detallado que sea, reemplaza esas conversaciones.
• Un agente ejecuta literalmente lo que dice el documento. No detecta que el alcance cambió en una reunión de Teams, no pregunta si diseño aprobó algo, no cuestiona contradicciones con lo que dijo DevOps. Ejecuta palabras, no intenciones.

Aunque el SDD - IA, podría parecer un poco pretencioso y alejado de la realidad de un proyecto de software con un mínimo de complejidad, sí que apunta propuestas metodológicas que se pueden reconvertir o servir de inspiración para incorporar la IA al desarrollo. Por ejemplo, en lugar de una spec previa interminable e ilegible, se pueden grabar las reuniones donde se definen las especificaciones, para procesarlas después con un LLM para extraer decisiones, restricciones y criterios de aceptación. Ese output estructurado no va a una carpeta .specify que nadie abrirá (vd. infra), sino directamente a los tickets del equipo, que es donde realmente mira el equipo de desarrollo o a unas skills reutilizables, etcétera.

Para aterrizar un poco más cómo va esto y coger ideas, podemos probar la Spec-Kit, la herramienta que catalizó el movimiento SDD.

Spec Kit

Lanzada por GitHub en septiembre de 2025, es esencialmente un framework de código abierto que estructura el trabajo con agentes de IA en 4 fases secuenciales y controladas: primero especificas, luego planificas, luego defines tareas y finalmente implementas. Para ello crea una carpeta .specify en el repositorio del proyecto que actúa como cerebro del agente. Es compatible con más de 20 plataformas de agentes distintas y alcanzó 77.000 estrellas en GitHub en cuestión de meses, lo que da una idea de la expectativa que generó. Su promesa era acabar con el vibe coding dándole al agente un marco de trabajo tan claro que los resultados fueran predecibles y auditables.

Aunque tenga los problemas que hemos visto, vale la pena conocer cómo funciona con más detalle. Para eso podemos preparar un programilla que haga cualquier chorrada, como escribir recetas en markdown o cartas de amor o una calculadora o cualquier cosa pequeña, para no perder el tiempo con eso. Para este ejemplo, prepararé un programa que escriba Koans sobre un tema indicado, como el café o las tostadoras.

Importante: si no tenéis intención de suscribiros a ningun api IA, ni siquiera a las gratuitas, es mejor preparar un programa que no necesite el trabajo de un llm, como una calculadora.

Yo voy a trabajar con python, así que en el directorio de mi proyecto creo un entorno virtual.

python -m venv .venv

Y lo activo

source .venv/Scripts/activate

Y ya lanzo el speck kit. Cambia koans por el nombre de tu proyecto

uvx --from git+https://github.com/github/spec-kit.git specify init koans

También se puede hacer así:

git clone https://github.com/github/spec-kit.git
cd spec-kit
pip install -e .
specify init <PROJECT_NAME>

A continuación te pregunta con qué agente quieres trabajar: opencode, copilot, claude, gemini…

Escogemos el tipo de consola. En mi caso (POSIX Shell (bash/zsh)), que estoy con el bash del visual, y ya estaría apañado.

Pasos

Con todo instalado, hay que ejecutar una serie de pasos obligatorios, en orden, y otros opcionales.

Pasos obligatorios

1. /speckit-constitution: Define los principios del proyecto (stack, restricciones, convenciones)
2. /speckit-specify: Genera la especificación funcional
3. /speckit-plan: Crea el plan técnico de implementación
4. /speckit-tasks: Desglosa todo en tareas concretas
5. /speckit-implement: Ejecuta la implementación

Pasos opcionales (para mejorar calidad):

• /speckit-clarify: Útil si el proyecto tiene áreas ambiguas, se usa antes del plan
• /speckit-checklist: Valida que los requisitos estén completos, después del plan
• /speckit-analyze: Revisa consistencia entre todos los artefactos, después de las tasks y antes de implementar

Vamos al lío.

Entramos en el directorio del proyecto que se ha creado.

cd koans

Levantamos el agente. Por ejemplo, claude.

claude

speckit-constitution

Con todo preparado vamos ya con el primer comando del kit, speckit-constitution, con la base del proyecto. En mi caso, algo así:

/speckit-constitution This is a Python 3.11+ project. Use the following conventions: package management with pip and a requirements.txt file, pytest for testing with tests in a tests/ folder, argparse for CLI interfaces, code style following PEP8, project structured as an installable package with pyproject.toml, version control with Git and GitHub including a .gitignore for Python, and a README.md with usage instructions.

Y en specify/memory/constitution.md. genera las indicaciones globales, que podemos retocar si no nos convencen.

## Core Principles

### I. Python Standards & Runtime

This project MUST target Python 3.11 or higher. All source code MUST conform to
PEP 8 style guidelines. The project MUST be structured as an installable package
with a valid `pyproject.toml` at the repository root, enabling installation via
`pip install .` or `pip install -e .` for development.

[PATATAS]

speckit-specify

El siguiente es /speckit-specify con la descripción del proyecto. Por ejemplo para koans:

/speckit-specify A Python command-line application that generates Zen koans about any topic provided by the user. The user runs the program from the terminal, passes a topic as an argument (e.g. "toasters"), and the app generates a koan about that topic and prints it to the console. The koan should follow the traditional Zen koan style: paradoxical, thought-provoking, and short. The output is always saved as a .md file inside an "output" directory, which is created automatically if it doesn't exist. The filename should be based on the topic (e.g. toasters.md).

Esta acción genera nuevos archivos dentro de ./specs, las especificaciones funcionales de nuestro programa: actores, user stories, criterios de aceptación, comportamiento esperado

koans\specs\001-koan-generator\spec.md

Feature Specification: Zen Koan Generator CLI

Feature Branch: 001-koan-generator Created: 2026-04-14 Status: Draft Input: User description: “A Python command-line application that generates Zen koans about any topic provided by the user. The user runs the program from the terminal, passes a topic as an argument (e.g. “toasters”), and the app generates a koan about that topic and prints it to the console. The koan should follow the traditional Zen koan style: paradoxical, thought-provoking, and short. The output is always saved as a .md file inside an “output” directory, which is created automatically if it doesn’t exist. The filename should be based on the topic (e.g. toasters.md).”

User Scenarios & Testing (mandatory)

User Story 1 - Generate and View a Koan (Priority: P1)

A user opens their terminal, runs the program with a topic of their choice, and immediately sees a short Zen koan about that topic printed to the console.

Why this priority: This is the core value of the application — without koan generation and display, nothing else matters.

Independent Test: Can be fully tested by running the program with any topic argument and verifying that a koan appears in the terminal output. Delivers the full read-only experience without requiring any file-system side effects.

Acceptance Scenarios:

1. Given a terminal with the application installed, When the user runs koans toasters, Then a short Zen-style koan ab

[PATATAS]

## speckit-plan

El tercer comando por orden es speckit-plan, que toma el spec.md y genera el plan técnico: arquitectura, estructura de archivos, módulos, dependencias. 

En la feature que estamos desarrollando nos habrá generado algo así:

- plan.md: Arquitectura, estructura de módulos, decisiones técnicas
- data-model.md: Modelos de datos (qué datos maneja el programa y cómo)
- research.md: Decisiones técnicas antes de implementar el desarrollo
- contracts/cli-contract.md: Contrato de la interfaz CLI (argumentos, salidas, códigos de error)

Todos estos archivos sirven como contexto acumulativo para el agente. Cada documento que se genera en una fase alimenta a la siguiente: el spec.md le dice qué construir, el plan.md le dice cómo, el data-model.md le dice con qué datos, el research.md le dice qué decisiones técnicas tomar, y el contracts/cli-contract.md le dice cómo debe comportarse la interfaz. Cuando llegue a /speckit-implement, el agente tendrá en teoría todo el contexto necesario para escribir código correcto sin tener que adivinar nada, lo que reducirá errores y producirá código más coherente y testeable.

## speckit-tasks

Nuestro siguiente comando es speckit-tasks, que genera el archivo tasks.md con una lista de tareas concretas e implementables, ordenadas por fases. Cada tarea es algo pequeño y verificable, por ejemplo:

---

Phase 1: Setup (Project Initialization)

Purpose: Create the repository skeleton — config files, package layout, and dev tooling.

• T001 Create pyproject.toml at repo root with package metadata (name = "koans", requires-python = ">=3.11"), and CLI entry point [project.scripts] koans = "koans.cli:main"
• T002 Create requirements.txt at repo root declaring anthropic (runtime) and flake8 or ruff (dev lint)
• T003 [P] Create .gitignore at repo root for Python projects (__pycache__/, *.pyc, .venv/, dist/, build/, *.egg-info/, .pytest_cache/, output/)
• T004 Create koans/ package directory with empty koans/__init__.py (add __version__ = "0.1.0")
• T005 [P] Create koans/__main__.py to enable python -m koans (import and call koans.cli.main)
• T006 [P] Create tests/ directory with empty tests/__init__.py

Checkpoint: pip install -e . succeeds; koans --help exits 0.

[PATATAS]

## speckit-implement

Con todas las especificaciones, ya es momento de generar el código mediante el comando

```bash
/speckit-implement

Nos pregunta si queremos proceder, le decimos que sí y ya se pone a hacer cosas…

En este caso, si ejecutamos por consola

koans speckit

Genera un koan:

# Koan: python

A programmer seeks to build a bridge with many stones called Python.
After years of labor, he discovers the bridge was already walking across him.

---
*Generated by Zen Koan Generator*

conclusión

Hay otro tipo de herramientas similares, como OpenSpec, pero la idea esencial es siempre la misma: proporcionar especificaciones estructuradas y estandarizas a los agentes que les sirvan de contexto para trabajar de forma más atinada.

¿Es mejor esta estrategia que tirar de prompts, mcps y skills a medida que se van necesitando?

No lo sé y creo que la respuesta depende mucho del tipo de proyecto, pero sí me gusta la idea de tener un framework que aporte estructura y reproducibilidad. Cualquier desarrollador del equipo puede entrar al proyecto, leer los docs de .specify/ y entender qué se está construyendo, por qué, y cómo. Con prompts ad hoc ese contexto se pierde.

También me parece interesante que el framework no te quite control. En cada fase puedes intervenir, editar los docs generados, y redirigir al agente antes de que escriba una sola línea de código. Eso es lo que lo diferencia del vibe-coding: el humano sigue siendo el director de orquesta, al menos de momento.