Filament Blueprint: La Nueva Herramienta de IA para Planificar Aplicaciones Filament

Compatibilidad: Filament v4+, Laravel Boost, PHP 8.2+

Filament Blueprint es una extensión premium de Laravel Boost diseñada para resolver uno de los problemas más comunes al trabajar con agentes de IA en proyectos Filament: la calidad de los planes de implementación.

Cuando pedimos a un agente de IA que construya una funcionalidad en Filament, la calidad del código generado depende directamente de la calidad del plan. Un plan vago produce código vago, y terminamos invirtiendo más tiempo corrigiendo al agente que el que ahorramos usándolo.

Blueprint actúa como un puente entre lo que queremos construir y lo que los agentes de IA realmente generan. En lugar de esperar que el agente comprenda las convenciones de Filament por intuición, Blueprint proporciona directrices de planificación estructuradas que producen documentos de especificación sin ambigüedades.

El Problema que Resuelve

Las directrices incluidas en Laravel Boost están diseñadas principalmente para agentes de implementación, es decir, ayudan a los agentes a escribir código Filament correcto una vez que saben qué construir.

Sin embargo, para funcionalidades complejas, los agentes suelen tener dificultades con la fase de planificación: elegir los componentes correctos, estructurar relaciones y anticipar casos extremos.

Blueprint aborda específicamente esta fase de planificación, reduciendo problemas comunes como el uso incorrecto de componentes, detalles de configuración faltantes o instrucciones de layout vagas.

Qué Incluye un Blueprint

Un Blueprint especifica todo lo que un agente de implementación necesita para generar código correcto a la primera:

• Modelos: Atributos, casts, relaciones y enums con sintaxis exacta

• Resources: Namespaces completos, comandos de scaffold y configuración

• Formularios: Componentes de campos, reglas de validación y estructura de layout

• Tablas: Columnas, filtros, acciones y comportamiento de ordenación

• Autorización: Reglas de políticas en lenguaje claro que se traducen directamente a código

• Testing: Qué probar y cómo verificar que funciona

• Funcionalidades avanzadas: Campos reactivos, wizards, imports/exports, acciones masivas, widgets y multi-tenancy

Las directrices cubren detalles que los agentes comúnmente fallan, como namespaces, nombres de métodos, selección de componentes y cálculos de layout anidado.

Cómo Funciona

Instalación

Blueprint requiere Laravel Boost instalado previamente.

1. Instalar Laravel Boost (si no lo tienes):

composer require laravel/boost --dev

2. Comprar la licencia de Blueprint:

Adquiere tu licencia en packages.filamentphp.com/p/blueprint/buy.

3. Configurar el repositorio privado de Filament:

composer config repositories.filament composer https://packages.filamentphp.com/composer

4. Configurar las credenciales de autenticación:

composer config --auth http-basic.packages.filamentphp.com "TU_EMAIL" "TU_LICENCIA"

Sustituye TU_EMAIL por el email con el que compraste la licencia y TU_LICENCIA por la clave de licencia que recibiste.

5. Instalar Blueprint:

composer require filament/blueprint --dev

6. Ejecutar el instalador de Boost:

php artisan boost:install

El instalador te preguntará por tu IDE (Cursor, PhpStorm, VS Code, Claude Code). Al tener Blueprint instalado, sus guidelines se incluirán automáticamente en el archivo generado (CLAUDE.md, AGENTS.md, etc.).

7. Verificar la instalación:

Revisa que tu archivo de guidelines contenga una sección de Filament Blueprint.

Si quieres profundizar en Filament 4, te recomiendo la Ruta de Laravel Filament 4 donde cubrimos desde los fundamentos hasta funcionalidades avanzadas.

Uso Básico

Una vez instalado, activas el modo de planificación en tu agente de IA y le pides que cree un Filament Blueprint:

Create a Filament Blueprint for an order management system.

Orders belong to customers and have many order items. Each order has a status
(pending, confirmed, shipped, delivered, cancelled), shipping address, and
optional notes. Order items reference products with quantity and unit price.

I need to search orders by customer name and filter by status and date range.
The order form should calculate line totals automatically as items are added.
Only admins can delete orders, and orders can only be cancelled if not yet shipped.

El agente producirá un documento de especificación detallado listo para implementación directa.

Comparativa: Sin Blueprint vs Con Blueprint

Para ilustrar la diferencia, el equipo de Filament proporciona un ejemplo comparativo usando el mismo prompt sobre un sistema de facturación SaaS.

Plan Sin Blueprint

Un plan típico generado sin Blueprint incluye información general pero carece de especificidad:

• Describe modelos y relaciones de forma genérica

• Lista componentes sin configuraciones exactas

• Menciona acciones sin detallar modals ni validaciones

• No especifica comandos CLI ni namespaces completos

Plan Con Blueprint

El mismo prompt con Blueprint genera especificaciones precisas que incluyen:

Resource: InvoiceResource
  Location: App\Filament\Resources\Invoices\InvoiceResource
  Docs: https://filamentphp.com/docs/4.x/panels/resources/overview
  RecordTitleAttribute: invoice_number
  GloballySearchableAttributes: [invoice_number, customer.name]

  Form:
    Field: customer_id
      Component: Filament\Forms\Components\Select
      Validation: required, exists:customers,id
      Config: ->relationship('customer', 'name')
              ->searchable()
              ->preload()
              ->createOptionForm([...])

La diferencia es notable: el plan con Blueprint incluye la ubicación exacta de archivos, URLs de documentación relevante, configuraciones específicas de componentes y validaciones completas.

Comandos CLI Generados

Blueprint también genera los comandos exactos para crear la estructura del proyecto:

# Crear modelos con migraciones y factories
php artisan make:model Customer -mf --no-interaction
php artisan make:model Product -mf --no-interaction
php artisan make:model Invoice -mf --no-interaction

# Crear resources de Filament
php artisan make:filament-resource Customer --view --soft-deletes --no-interaction
php artisan make:filament-resource Product --view --soft-deletes --no-interaction
php artisan make:filament-resource Invoice --view --soft-deletes --no-interaction

# Crear relation managers
php artisan make:filament-relation-manager InvoiceResource payments amount --no-interaction

Especificaciones de Campos Reactivos

Una de las áreas donde los agentes suelen fallar es en la configuración de campos reactivos. Blueprint especifica exactamente cómo deben funcionar:

Field: quantity
  Component: Filament\Forms\Components\TextInput
  Validation: required, integer, min:1
  Config: ->integer()
          ->default(1)
          ->live()
          ->afterStateUpdated(fn (Set $set, Get $get) => self::updateLineTotal($set, $get))

Esto elimina la ambigüedad sobre cuándo usar ->live(), cómo encadenar afterStateUpdated() y qué helpers importar.

Integración con Agentes de IA

Blueprint está diseñado para funcionar con los principales agentes de código:

• Claude Code: Integración nativa con el CLI

• Cursor: Compatible a través de Laravel Boost

• GitHub Copilot: Funciona con las directrices generadas

Las directrices de planificación están diseñadas solo para agentes de planificación y no consumen la ventana de contexto del agente de implementación. El agente de planificación copia todos los detalles necesarios en el blueprint, para que el agente de implementación tenga todo lo que necesita sin cargar las directrices.

Precios

Blueprint ofrece dos opciones de licencia:

Actualmente hay un código de descuento del 20% disponible: BPLAUNCH20.

Filament v5: Contexto del Lanzamiento

Blueprint se lanzó junto con Filament v5, que llegó apenas una semana después de la versión 4.5. La principal novedad de v5 es el soporte para Livewire v4, manteniendo compatibilidad total con v4.

El equipo de Filament optó por una nueva versión mayor para que los proyectos que no requieren directamente livewire/livewire no tengan código Livewire personalizado roto inesperadamente.

Aspectos clave de Filament v5:

• Soporte completo para Livewire v4

• Sin cambios adicionales respecto a v4 más allá del soporte de Livewire

• Las nuevas funcionalidades se seguirán publicando para ambas versiones (v4 y v5)

• Guía de actualización breve sin pasos manuales requeridos

• Script de actualización automático disponible

Conclusión

Blueprint tiene sentido si trabajas regularmente con Filament y agentes de IA. Los $49 se amortizan rápidamente si consideras el tiempo que ahorras en correcciones y revisiones.

Para desarrolladores que apenas están comenzando con Filament o que no usan agentes de IA en su flujo de trabajo, Laravel Boost gratuito con las directrices básicas de Filament puede ser suficiente.