Mejores Practicas y Patrones Brownfield
Mejores Practicas y Patrones Brownfield
Cuando usar OpenSpec
OpenSpec no es la herramienta correcta para todo. Estos son los escenarios donde aporta mas valor:
Features iterativas sobre codigo existente
Tienes un proyecto funcional y necesitas agregar, modificar o extender funcionalidad. Exactamente lo que hicimos con el Kanban: partimos de un modelo de datos y fuimos agregando drag and drop, autenticacion y filtros. Cada cambio se construyo sobre las specs anteriores.
Codebases con historia
Proyectos que llevan meses o anos en produccion. El equipo rota, la documentacion esta desactualizada, y nadie recuerda por que se tomo cierta decision. Los specs de OpenSpec se convierten en la documentacion viva que siempre falta.
Equipos que necesitan auditabilidad
Cada cambio tiene su propuesta, sus specs, su implementacion y su verificacion. Todo queda registrado en el archivo. Si alguien pregunta “por que el sistema funciona asi”, la respuesta esta en los specs archivados.
Mantenimiento continuo
Correccion de bugs, migraciones, actualizaciones de dependencias. Incluso cambios “pequenos” se benefician de tener specs que documenten la intencion.
Cuando NO usar OpenSpec
Proyectos greenfield muy complejos
Si estas disenando un sistema desde cero con multiples microservicios, dominios complejos y un equipo grande, considera BMAD primero. BMAD tiene fases de discovery, analisis de mercado y diagramas de arquitectura que OpenSpec no ofrece. Puedes migrar a OpenSpec despues del setup inicial.
Prototipos desechables
Si vas a tirar el codigo en una semana, las specs no aportan valor. Usa la IA directamente, genera el prototipo y avanza. Si el prototipo sobrevive y se convierte en producto, entonces activa OpenSpec.
Cambios triviales de una linea
Corregir un typo, actualizar una constante o cambiar un color no justifica el flujo completo de propuesta, especificacion y verificacion. Hazlo directamente y sigue adelante.
Patron: retroingenieria de specs
Uno de los escenarios mas potentes es generar specs desde codigo legacy que no tiene especificaciones. OpenSpec permite esto con:
/opsx:exploreEste comando analiza el codigo existente y genera specs que describen el comportamiento actual. No es perfecto (la IA infiere comportamiento del codigo), pero te da una base sobre la cual iterar.
El flujo es:
- Ejecutar
/opsx:exploresobre el codebase - Revisar los specs generados y corregir imprecisiones
- Guardar los specs en
openspec/specs/ - A partir de aqui, usar el flujo normal de
/opsx:proposepara cambios
Esto transforma un proyecto sin documentacion en un proyecto especificado, y cada cambio futuro mantiene esas specs actualizadas.
Patron: un cambio = un PR
Mantener correspondencia 1:1 entre cambios de OpenSpec y Pull Requests:
| Cambio OpenSpec | Branch Git | Pull Request |
|---|---|---|
| add-drag-drop | feat/drag-drop | PR #12 |
| add-auth | feat/auth | PR #13 |
| add-filters | feat/filters | PR #14 |
Esta correspondencia facilita:
- Code review: El reviewer lee las specs del cambio para entender la intencion
- Rollback: Revertir un PR es revertir un cambio especifico con specs claras
- CI/CD: Los tests generados desde las specs se asocian al PR correcto
- Trazabilidad: Del requisito al codigo, pasando por la spec
Patron: specs como documentacion viva
Las especificaciones tradicionales se pudren. Alguien escribe un documento de arquitectura, el codigo evoluciona, y en seis meses el documento no refleja la realidad.
Con OpenSpec, los specs no se pudren porque son parte del flujo de trabajo:
- Cada cambio genera delta specs
- Al archivar, las delta specs se fusionan con los specs principales
- Los specs siempre reflejan el estado actual del sistema
- Si el codigo cambia sin pasar por OpenSpec, la discrepancia se detecta en el proximo ciclo de verificacion
Los specs no son documentacion que escribes una vez. Son artefactos que evolucionan con cada cambio.
Patron: explore antes de propose
Antes de formalizar un cambio, usa /opsx:explore para pensar:
/opsx:explore
Quiero agregar notificaciones en tiempo real al Kanban.
Que partes del sistema se verian afectadas?Explore analiza el codebase y los specs existentes para darte una respuesta informada sin crear artefactos formales. Es el equivalente a pensar en la pizarra antes de comprometerte con una propuesta.
Esto evita crear cambios que luego descartas porque no consideraste alguna dependencia o complejidad.
Anti-patrones
No archivar cambios completados
Dejar cambios en estado applied sin archivar acumula deuda. Las delta specs no se fusionan con los specs principales, el historial queda incompleto y los proximos cambios no tienen contexto actualizado.
Specs demasiado granulares
No necesitas un escenario Gherkin para cada caso borde. Las specs deben capturar el comportamiento significativo, no reemplazar los unit tests. Si un spec tiene 30 escenarios para una sola feature, probablemente necesitas dividir la feature en cambios mas pequenos.
Ignorar el contexto del proyecto
El archivo CLAUDE.md y las instrucciones de openspec instructions son la brujula del proyecto. Si no actualizas CLAUDE.md cuando cambia la arquitectura o las convenciones, la IA genera propuestas basadas en informacion desactualizada. Dedica 2 minutos despues de cada cambio importante a verificar que el contexto sigue siendo preciso.
Cambios demasiado grandes
Un cambio que toca 30 archivos y tiene 15 delta specs es dificil de revisar, verificar y archivar. Prefiere cambios enfocados que resuelvan una cosa bien.
Saltarse la validacion
Archivar sin revisar que la implementacion cumple las specs es como hacer merge sin correr tests. En perfil Expanded, /opsx:verify ofrece validacion formal. En perfil Core, /opsx:archive incluye validaciones internas. En cualquier caso, asegurate de que la implementacion cumple lo acordado.
Resumen del proyecto Kanban
A lo largo del tutorial construimos un Kanban completo usando OpenSpec. Esta tabla resume cada cambio:
| Cambio | Artefactos generados | Resultado |
|---|---|---|
| Modelo de datos | proposal + design + tasks + 2 specs | Backend con API CRUD para tableros, columnas y tarjetas |
| Drag and drop | proposal + design + tasks + 1 modified + 1 added | Tarjetas arrastrables entre columnas con persistencia |
| Autenticacion | proposal + design + tasks + 3 specs | Login, sesiones y tableros por usuario |
| Filtros | proposal + design + tasks + 1 modified + 1 added | Busqueda por etiqueta, fecha y asignado |
Cada cambio siguio el mismo flujo de 3 acciones: Propose, Apply, Archive. Los specs crecieron de 2 archivos iniciales a 7 archivos que documentan todo el comportamiento del sistema.
Comparacion de eficiencia
Fission AI publico un benchmark usando un proyecto de CRM Dashboard (CRUD, graficas, filtros, autenticacion). Los resultados comparan el tiempo desde la idea hasta la implementacion verificada:
| Framework | Tiempo total | Artefactos | Ideal para |
|---|---|---|---|
| OpenSpec | ~12 min | ~250 lineas/cambio | Brownfield, iteracion rapida |
| Spec-Kit | ~90 min | Variable | Specs formales y rigurosas |
| BMAD | ~5.5 horas | ~800+ lineas | Greenfield complejo |
Estos numeros no significan que uno sea “mejor” que otro. Significan que cada herramienta esta optimizada para un escenario diferente:
- OpenSpec sacrifica completitud por velocidad. Ideal para cambios frecuentes sobre codigo existente.
- Spec-Kit prioriza rigurosidad formal. Ideal para sistemas donde las specs son contrato legal.
- BMAD prioriza exhaustividad. Ideal para proyectos nuevos con muchas incognitas.
Recursos
- Repositorio oficial: github.com/Fission-AI/OpenSpec
- Documentacion: openspec.pro
- Onboarding rapido: Ejecuta
/opsx:onboarden cualquier proyecto (requiere perfil Expanded) para un tutorial guiado con tu codebase
Resumen final
- Usa OpenSpec para features iterativas, codebases existentes y mantenimiento continuo
- No lo uses para prototipos desechables ni cambios triviales
- Un cambio = un PR mantiene trazabilidad completa
- Los specs son documentacion viva que no se pudre
- Explora antes de formalizar con
/opsx:explore - Evita no archivar, ignorar el contexto y crear specs demasiado granulares
- OpenSpec es la opcion optima para brownfield con ~12 minutos por cambio
Capitulo 9: Cambios Paralelos | Capitulo 11: Roadmap y Futuro