BMAD: planificar antes de escribir código

Si escribo código sin pensar, me pierdo a la tercera semana. Si planifico demasiado, me pierdo antes. Tuve que aprender a planificar sin ahogarme planificando.

El contexto

Este repo no es un proyecto de una tarde: hay 9 epics y unas cuarenta stories. Lo he llevado solo — sin equipo, sin roadmap de empresa, sin presión externa. Esa libertad es, también, la trampa más fácil para un proyecto personal: que la próxima cosa “interesante” desbanque la actual cada viernes por la noche.

Lo único que conocía que funcionara contra eso era una disciplina ligera de planificación. BMAD es la que adopté — un método con fases cortas y artefactos versionados al lado del código.

La decisión

BMAD no es más que nueve fases en orden estricto, cada una con un artefacto versionado:

analyze → plan → architect → stories → validate
       → sprint → dev → review → qa → retro

• analyze produce un brief (_bmad/briefs/*.md): qué queremos, por qué, qué queda fuera.
• plan produce el PRD (_bmad/planning/prd.md): requisitos concretos, métricas, gates.
• architect produce el architecture.md: layering, protocolos, modelos de threading.
• stories parte la arquitectura en epics y stories pequeñas (_bmad/epics/, _bmad/stories/). Cada story cabe en un PR.
• validate es el paso de PO: ninguna story huérfana, ningún requisito sin story.
• sprint agrupa stories en un sprint.
• dev, review, qa son las tres fases de implementación de una story.
• retro cierra el sprint con qué se hace distinto en el próximo.

Cada fase tiene un slash-command (/bmad-analyze, /bmad-plan, …). Lo más importante: los artefactos viven en el repo (_bmad/). No en Notion, no en Linear. Si la planificación no vive al lado del código, se desactualiza sin que nadie lo note.

Ramas: una por historia

Tres tipos de rama y basta:

Rama	Rol
main	Releases estables. Nunca push directo.
staging	Integración. Aquí aterrizan los artefactos BMAD.
feature/story-XX-XX-...	Una por story de implementación.

Merges siempre --no-ff (en GitHub: “Create a merge commit”). Nunca squash, nunca rebase. El grafo de Git conserva la burbuja por historia — puedes ver cuándo empezó una story, cuándo acabó, qué revirtió. Squash perdería eso; rebase también.

¿Es más ruido en el grafo? Sí. Es el precio de tener traza visual. Cuando, dos meses después, buscas cuándo cambiaste el transport.serial y por qué, el grafo te lo enseña; el squash no.

Por qué el ruff.extend-exclude está anclado a stories concretas. Cada path legacy excluido en pyproject.toml tiene un comentario con la story que lo retira. Cuando la story se completa, el exclude se va con ella. Sin ese acoplamiento, los legacy paths se vuelven permanentes: nadie se atreve a tocarlos porque “igual los necesitamos”. Con el acoplamiento, la deuda tiene fecha de caducidad desde el día en que se contrae.

El coste real es más alto del que admitiría antes. Cada funcionalidad lleva un brief mini, dos iteraciones de review (código + QA) y una retro al sprint. Si fuera solo código puro, iría más rápido los primeros días.

La recompensa: el epic 09 (alinear vocabulario a Lumware) se planificó, ejecutó y mergeó en horas. Toda la rename python2arduino → lumware, los docs, los imports, los tests. No porque el trabajo fuera pequeño, sino porque la estructura para hacerlo ya existía. Sin BMAD, habría sido una semana de bugs.

Lo que viene

Hemos hablado de todo el sistema. Falta decir por qué tiene el nombre que tiene y por qué la paleta de colores es R/G/B/W y no otra. Próximo post: identidad spectrum.