Diseñar el trabajo para los sistemas de IA en lugar de luchar contra ellos

‍

Introducción: por qué empecé a explorar el desarrollo basado en especificaciones

Durante las últimas semanas he estado trabajando en un proyecto centrado en generación automática de código. Ni demostraciones, ni ejemplos de juguetes, flujos de trabajo reales, restricciones reales, iteración real.

En las primeras etapas, mientras se realizaban experimentos aislados, todo parecía funcionar bien. Los modelos modernos son realmente muy buenos para escribir código, por lo que los resultados iniciales parecían prometedores y el progreso parecía rápido.

Pero muy rápidamente, apareció un patrón: el problema no era la calidad de los modelos, era cómo estaba estructurando el trabajo, con una excesiva dependencia de las correcciones manuales y una estructura inicial insuficiente.

Eso es lo que me empujó a profundizar Desarrollo basado en especificaciones (SDD). No como una teoría, sino como una respuesta práctica a la fricción de crear software con la participación de un LLM en cada paso.

El flujo de trabajo anterior al SDD: las indicaciones funcionan... hasta que dejan de funcionar

Mi flujo de trabajo inicial me resultaba familiar:

• Tenía una idea o un requerimiento
• Escribí un mensaje
• Tengo un código
• Lo modifiqué
• Repetí el bucle

Esto funciona sorprendentemente bien... al principio.

Los problemas aparecen cuando:

• cambios en los requisitos
• el sistema crece en tamaño y complejidad
• o necesita reproducir los resultados de forma fiable

Lo que no dejaba de romperse no era el código. Lo era intención.

El «por qué» detrás de las decisiones vivía en mi cabeza, no en el sistema. Cada nuevo mensaje intentaba reconstruir un contexto que nunca se capturaba de forma explícita.

El contexto es lo primero, antes de iniciar SDD

Un logro clave al adoptar el desarrollo basado en especificaciones es que la calidad de generación de código depende de la calidad del contexto.

Cuando el contexto solo vive en las instrucciones o en la cabeza de alguien, los resultados tienden a desviarse, la iteración se vuelve costosa y las correcciones manuales se acumulan. El SDD funciona mejor cuando la intención se hace explícita antes de generar cualquier plan o código.

Para ver la diferencia en tiempo real, compare estos dos niveles de «profundidad contextual»:

• Contexto bajo: > «Importar un PDF».
  
  • El problema: La IA tiene que adivinar todo: el idioma, los límites de tamaño, la arquitectura y la gestión de errores. Es probable que recibas un fragmento que no se ajuste a tu proyecto.
• Contexto superior (el punto de partida del SDD):
  «Importe un PDF de forma asincrónica, validando que el tamaño sea inferior a 5 MB, utilizando una clase 'FileManager' separada para gestionar la lógica».
  
  • La victoria: Has definido el comportamiento (asincrónico), el restricción (5 MB) y el arquitectura (clase extra). No solo estás solicitando un código; estás proporcionando un modelo.

Hay varias herramientas que abordan este problema desde diferentes ángulos, pero todas tienen el mismo objetivo: establecer un contexto duradero fuera de lo inmediato.

Tres formas complementarias de definir el contexto

En el flujo de trabajo tradicional, el «contexto» es cualquier cosa que puedas incluir en un solo mensaje antes de que la IA comience a alucinar. En el desarrollo basado en especificaciones, el contexto es un entorno estructurado. Es el «sistema operativo» en el que viven los agentes de IA.

Para construir este entorno, necesitamos descomponer el contexto en tres elementos fundamentales:

1. La capa conductual (dirección): Estas son las cosas no negociables. Es la «personalidad» de tu código base. ¿Su equipo prefiere la programación funcional? ¿Usas convenciones de nomenclatura específicas para tus archivos? La dirección garantiza que todos los agentes, independientemente de cuándo se les llame, sigan la misma dirección filosófica.
2. La capa situacional (memoria): Este es el «conocimiento tribal» de su proyecto. Es el registro de por qué elegiste la biblioteca A en lugar de la biblioteca B, o el caso extremo específico que encontraste en el último sprint. La memoria evita el efecto del «Día de la marmota», en el que tienes que explicar la misma restricción a la IA todas las mañanas.
3. La capa operativa (reglas): Estas son las «barandillas» para la tarea inmediata. Se trata de la sintaxis, la estructura de carpetas y las restricciones específicas de la API. Las reglas actúan como indicadores en tiempo real del proceso de pensamiento de la IA, deteniendo los errores incluso antes de que se conviertan en código.

Al separar estos tres, deja de ser un «ingeniero rápido» y comienza a ser un arquitecto de sistemas. No solo está dando órdenes, sino que está diseñando los límites dentro de los cuales opera la inteligencia.

Esto es exactamente lo que las herramientas modernas están empezando a resolver a través de diferentes lentes:

• Kiro — Archivos de dirección: Define la dirección a largo plazo y la intención arquitectónica para garantizar la alineación y evitar la improvisación.
• Claude — Memoria: Permite la continuidad al conservar las decisiones y preferencias importantes en todas las sesiones.‍
• Cursor — Reglas: Proporciona control mediante restricciones locales explícitas que evitan errores de bajo nivel durante la ejecución.

Adopción en equipo: compartir el contexto para lograr la coherencia

Para implementar de manera efectiva el desarrollo basado en especificaciones (SDD) en un equipo, las capas de contexto principales, específicamente las Capa situacional (memoria) y el Capa operativa (reglas), debe estar compartida, visible y controlada por versiones.

El enfoque más sencillo es guardar estos archivos contextuales directamente en el repositorio del proyecto, lo que permite a todos los miembros del equipo y a todos los agentes de IA operar desde una única fuente de información fiable.

El directorio rules/ contiene restricciones inmediatas de bajo nivel que rigen la calidad, la estructura y la ejecución del código para la tarea inmediata.

El directorio memory/ captura las decisiones de alto nivel, el contexto histórico y el conocimiento específico del proyecto para evitar la instrucción repetitiva o los escenarios del «Día de la Marmota».

Un ejemplo de estructura simple

En la práctica, esto suele asignarse a una estructura pequeña e intencional:

project-root/
├─ specs/
│  ├─ system.md
│
├─ steering/
│  ├─ principles.md
│
├─ rules/
│  ├─ coding.md
│
├─ memory/
│  ├─ decisions.md

Las herramientas exactas pueden variar, pero el patrón sigue siendo el mismo:

separar la dirección, las restricciones y el contexto persistente para que los sistemas de IA puedan funcionar con menos intervención manual y menos correcciones posteriores a la generación.

Para obtener detalles más detallados, la documentación oficial es el mejor lugar para comenzar:

• https://code.claude.com/docs/en/memory
• https://cursor.com/en-US/docs/context/rules
• https://kiro.dev/docs/steering/

Esta capa de contexto explícita no es independiente del desarrollo basado en especificaciones, sino que es la base que hace posible el SDD en la práctica.

La integración en el flujo de trabajo del equipo es sencilla y está impulsada por la disciplina:

1. Lea el contexto: Antes de iniciar una tarea, un desarrollador (o el agente de IA especializado que actúe en su nombre) primero ingiere los archivos de dirección/, rules/ y memoria/ relevantes.
2. Defina la especificación: El desarrollador escribe una nueva especificación (specs/new-feature.md) que hace referencia a las restricciones y al historial.
3. Actualice el contexto: Si se toma una nueva decisión arquitectónica durante la ejecución de la especificación, el desarrollador mosto actualice el archivo memory/decisions.md e inserte el cambio junto con el código resultante.
4. Revise los cambios de contexto: En las solicitudes de cambios, el proceso de revisión debe incluir el análisis de cualquier cambio propuesto en los archivos de memoria, reglas y reglas para garantizar que reflejen con precisión el consenso del equipo.

Qué significa el desarrollo basado en especificaciones (en la práctica)

Con el contexto establecido, Spec-Driven Development cambia el centro de gravedad.

En lugar de:

• indicaciones → código → correcciones

Te mudas a:

• especificaciones → planes → ejecución → revisión

En la práctica, SDD significa:

• Las especificaciones son la entrada principal
• El código es un artefacto derivado
• La intención es explícita e inspeccionable

Esto no es:

• escribir más documentación
• cascada disfrazada
• sobreingeniería

Se trata de:

• restricciones de diseño
• definir el alcance
• hacer que las decisiones sean visibles tanto para los humanos como para los modelos

Las especificaciones como capa de control para el desarrollo asistido por IA

Los LLM son excelentes ejecutores.

No son buenos para adivinar los límites.

Las especificaciones actúan como:

• contratos
• mecanismos de alineación
• reguladores de ámbito

Esta idea se refleja en varias herramientas y enfoques:

• Kit de especificaciones de GitHub
• Archivos de dirección Kiro
• Las habilidades, los documentos y las reglas de Tessl
• La obra de Martin Fowler sobre el SDD

El nuevo flujo de trabajo: SDD en acción

Herramientas y referencias que dieron forma a mi enfoque

• GitHub Kit de especificaciones
• Kiro archivos de dirección
• Tessl — habilidades, documentos, reglas como primitivas
• Martín Fowler — Explorando GenAI y SDD

Claude se utiliza principalmente como albacea dentro de esta estructura.

Creación de mi propio flujo de trabajo de SDD

Bifurqué un repositorio existente y lo convertí en mi propio flujo de trabajo:

https://github.com/perzequiel/perze-claude-code

Incluye:

• agentes de aduana
• especificación → plan → bucles de ejecución
• una estructura intencionalmente extensible

Desde escribir código hasta coordinar agentes

Paso menos tiempo en el IDE y más tiempo:

• definición de especificaciones
• revisar los planes
• evaluación de las compensaciones

El valor pasa de la implementación a estructuración de problemas.

Compensaciones y limitaciones actuales

Costos:

• diseño más directo
• más ciclos de revisión
• disciplina requerida

Ventajas:

• menos caos
• mejor razonamiento
• sistemas más claros

Qué sigue (spoiler corto)

• MCP
• habilidades más especializadas
• colaboración más estrecha entre los agentes

Detalles para otro post.

Una nota sobre Warp

Estoy usando Warp como sistema operativo de trabajo con flujos de trabajo de varios agentes, lo que me abstrae aún más del IDE.

Charla:

https://www.youtube.com/watch?v=w0bJFC0u0pE

Cierre

En el panorama del desarrollo moderno, la mera accesibilidad de herramientas y marcos potentes ha cambiado drásticamente el enfoque del esfuerzo de ingeniería. Cuando el código se vuelve barato, el diseño se convierte en el trabajo. Esto no quiere decir que escribir código sea trivial, sino que el costo, en términos de tiempo, complejidad y experiencia, de producir código funcional ha disminuido en relación con el costo de producir sistemas bien diseñados, sostenibles y correctos. El valor reside en una arquitectura bien pensada, interfaces claras y una comprensión compartida de la intención.

El desarrollo basado en especificaciones es una forma práctica de hacer que ese diseño sea explícito, revisable y ejecutable. El SDD exige que la definición del comportamiento de un sistema, su especificación o «especificación», se cree antes de la implementación o simultáneamente con ella. Esta especificación es la única fuente de información veraz, ya que aparta el proceso de diseño de la cabeza del desarrollador y lo convierte en un artefacto accesible y formalizado. Al formalizar el diseño mediante especificaciones ejecutables, SDD transforma los conceptos arquitectónicos abstractos en contratos concretos y comprobables. Este enfoque facilita la retroalimentación temprana, las pruebas de cumplimiento automatizadas y un mayor grado de confianza en la capacidad del sistema para cumplir con sus requisitos.