Cómo construyo software con un equipo de agentes de IA

Mi flujo con Claude Code y el método BMAD, explicado sin rodeos. Es el mismo con el que construí la plataforma de estadísticas del Mundial.

Para ti si programas o estás aprendiendo. No necesitas ser experto: los términos raros los explico en el camino.

La jugada de BMAD Una cancha con seis agentes: analista, producto, arquitecto, scrum master, desarrollo y QA. El balón pasa de uno a otro llevando la investigación, el PRD, la arquitectura, las historias, el código y las pruebas, hasta el arco. Tú eres el técnico, desde la raya. Tú eres el técnico
La IA pone el equipo. Tú decides la jugada.

Primero, el problema: Claude olvida todo

Cada conversación con Claude Code empieza en blanco. No recuerda lo que hicieron ayer, las decisiones que tomaron ni los errores que ya resolvieron.

En un proyecto pequeño no importa. En uno grande es como trabajar con alguien brillante que cada mañana llega con amnesia: vuelve a preguntar lo mismo, vuelve a tomar decisiones que ya estaban tomadas y a veces repite errores viejos.

La solución: una libreta del proyecto

Mantengo un archivo en markdown que funciona como la enciclopedia del proyecto, y se lo paso a Claude al empezar una sesión que necesite conocerlo a fondo. Tiene cuatro cosas:

  • De qué se trata el proyecto y con qué está hecho.
  • Las decisiones importantes, y por qué se tomaron.
  • Lo que ya está hecho, incluidos los problemas que aparecieron y cómo se resolvieron.
  • Lo que no se debe tocar, para que la IA no se ponga a arreglar lo que nadie le pidió.
# Mundial Stats: libreta del proyecto

## Con qué está hecho
Extractor en Python que procesa PDF por lotes.
Frontend estático en Next.js.

## Decisiones
- Los mapas de tiros salen de las coordenadas
  vectoriales de los PDF de la FIFA. (validado)

## Hecho
- ...

## No tocar
- ...

Un ejemplo simplificado. La real crece con el proyecto.

La regla de oro: cada vez que aprendan algo nuevo, pídele a Claude que actualice la libreta. Así cada sesión arranca más inteligente que la anterior.

Esta libreta no está escrita para personas: está escrita para que la IA la lea. Y convive con la memoria propia de Claude Code, que guarda tus preferencias por proyecto. La memoria es para cómo te gusta trabajar; la libreta, para el conocimiento profundo.

Tu alineación: los agentes de BMAD

BMAD (BMad Method) es un método gratuito y de código abierto que organiza el trabajo con IA como si fuera un equipo de software. Cada agente tiene un rol, y tú los llamas con comandos dentro de Claude Code.

  • Analista (Mary)

    Investiga el problema y el contexto antes de que exista un plan.

    Entra cuando la idea todavía es difusa.

  • Product manager (John)

    Escribe el PRD: qué se va a construir, para quién y qué queda por fuera. Y divide el trabajo en épicas e historias.

    Entra en la planeación.

  • Diseñadora UX (Sally)

    Define cómo se va a usar: pantallas, flujos y patrones de diseño.

    Entra en la planeación, si hay interfaz.

  • Arquitecto (Winston)

    Decide cómo se construye: tecnologías, modelo de datos y cómo se conectan las piezas.

    Entra antes de escribir código.

  • Scrum master (Bob)

    Ordena las historias y prepara cada una con todo el contexto necesario para desarrollarla.

    Entra cuando empieza la construcción.

  • Desarrolladora (Amelia)

    Implementa cada historia siguiendo su especificación, y revisa el código.

    Entra en la construcción.

  • Ingeniero de QA (Quinn)

    Genera pruebas automáticas para verificar que todo funciona.

    Entra en la construcción.

  • El comodín (Barry)

    Un desarrollador solitario para cambios pequeños: especifica e implementa en un solo flujo, sin toda la planeación.

    Entra cuando haga falta.

Los nombres entre paréntesis vienen de BMAD: así se presenta cada agente cuando lo llamas.

Dos jugadas: una para lo grande, otra para lo pequeño

No todo cambio merece el mismo proceso. Planear un arreglo de una línea es perder el tiempo; improvisar una función grande es buscar problemas.

La jugada completa

Para funciones nuevas, cambios en varios archivos o decisiones de arquitectura.

  1. El PRD/bmad-create-prd
    Qué se construye y qué queda por fuera.
  2. La arquitectura/bmad-create-architecture
    Las decisiones técnicas, antes de escribir código.
  3. Épicas e historias/bmad-create-epics-and-stories
    El trabajo partido en piezas pequeñas.
  4. ¿Todo encaja?/bmad-check-implementation-readiness
    Revisa que el PRD, la arquitectura y las historias no se contradigan.
  5. El plan del sprint/bmad-sprint-planning
    En qué orden van las historias.
  6. Historia por historia /bmad-create-storyluego/bmad-dev-storyluego/bmad-code-review Prepararla, desarrollarla y revisarla. Y otra vez con la siguiente.

La jugada rápida

Para arreglos puntuales y cambios que siguen un patrón que ya existe.

  1. La spec rápida/bmad-quick-spec
    La causa del problema, la solución, los archivos a tocar y cómo probarlo.
  2. El desarrollo/bmad-quick-dev
    Implementa lo que dice la spec.
  3. La revisión/bmad-code-review
    Sí, también en los cambios pequeños.

¿Qué jugada te toca?

Marca lo que aplique a tu cambio.

Marca al menos una opción y te digo qué jugada va.

¿Y si no sabes? Escribe /bmad-help en Claude Code: lee lo que ya tienes en el proyecto y te dice qué sigue.

El partido real: la plataforma del Mundial

Así se vio este flujo en un proyecto de verdad.

  1. La idea

    Una plataforma con las estadísticas profundas de los 104 partidos: mapas de tiros, redes de pases, datos de los 1.248 jugadores. El problema: esos datos venían atrapados en los informes oficiales de la FIFA, en PDF.

  2. El spike

    Antes de planear nada, probé lo más riesgoso: ¿se podían sacar datos de los gráficos de esos PDF? Resultó que los mapas eran vectoriales, con coordenadas recuperables. Si esa prueba fallaba, todo el plan se caía. Por eso va primero.

  3. La arquitectura

    Con eso despejado, la arquitectura quedó definida: un extractor en Python que procesa los PDF por lotes, y un frontend estático en Next.js que muestra los datos.

  4. El PRD, las épicas y las historias

    La idea se volvió un PRD, y el PRD se partió en épicas e historias: piezas pequeñas que se pueden construir y probar una por una.

  5. Historia por historia

    Cada historia pasó por el mismo ciclo: prepararla, desarrollarla y revisarla. Y cada vez que aprendíamos algo, la libreta del proyecto se actualizaba.

  6. En la cancha

    El resultado: 104 partidos, 1.248 jugadores y 48 equipos, en español y en inglés. Puedes verla aquí.

El VAR: todo pasa por revisión

Después de cada historia corro /bmad-code-review, incluso en arreglos de una línea. Un cambio pequeño también puede romper algo. La revisión funciona como tres árbitros distintos:

El que no sabe qué querías hacer
Busca errores, fallas de lógica y huecos de seguridad sin conocer tu intención, así no se deja convencer.
El de los casos raros
Recorre cada camino posible y cada valor límite: el campo vacío, el número negativo, la fecha que no existe.
El que revisa contra lo pedido
Verifica que el código cumpla los criterios de aceptación de la historia.

Si alguno encuentra algo, la historia vuelve a desarrollo antes de pasar a la siguiente.

Tu primer partido

  1. Instala Claude Code Sigue la guía oficial de instalación.
  2. Instala BMAD en la carpeta de tu proyecto
    npx bmad-method install
    Necesitas Node.js 20.12 o superior. Cuando te pregunte por tu herramienta, elige Claude Code.
  3. Crea tu libreta del proyecto Un archivo en markdown con de qué va el proyecto y las decisiones que tomes. Pídele a Claude que la mantenga al día.
  4. Abre Claude Code y pregunta qué sigue
    /bmad-help
  5. Empieza con algo pequeño y tuyo Una app para tus gastos, una página para tu negocio, un script que te ahorre algo repetitivo. Aprender el flujo sin presión es la mejor forma.

BMAD cambia rápido. Los comandos de esta guía son los de la versión que uso; si alguno no te aparece igual, /bmad-help te dice cómo se llama ahora. La documentación oficial está en docs.bmad-method.org.

Glosario rápido

Agente

Una IA con un rol e instrucciones específicas. En vez de un asistente que hace de todo, varios especialistas.

Contexto

Lo que la IA tiene en la cabeza durante una conversación. Lo que no esté ahí, no lo sabe. Por eso existe la libreta.

PRD

Documento de requisitos del producto (en inglés, Product Requirements Document): qué se construye, para quién y qué queda por fuera.

Épica

Un bloque grande de trabajo, como "extraer los datos de los PDF". Se divide en historias.

Historia

Una pieza pequeña de trabajo que se puede construir y probar por separado, con condiciones claras de cuándo está terminada.

Criterios de aceptación

Las condiciones que tiene que cumplir una historia para darse por terminada.

Spike

Un experimento corto para despejar una duda técnica antes de comprometerse con un plan.

Sprint

Un ciclo de trabajo con un grupo de historias por completar.