Skill de Planificación de Proyectos Next.js (nextjs-plan)
Un skill de orquestación estructurada para planificar aplicaciones Next.js con App Router. Cuando se invoca, extrae especificaciones técnicas de archivos existentes en el espacio de trabajo, realiza una entrevista dirigida al usuario sobre sus requisitos y genera especificaciones canónicas del proyecto (docs/project.json), registros de código tipados en lib/, informes de diseño en docs/design/ y una hoja de ruta de implementación modular de 7 fases en docs/plan/.
Resumen del Flujo de Trabajo
flowchart TD
Invoke["Invocar /nextjs-plan"] --> Step1["1. Inspección Automática del Espacio de Trabajo<br/>(Extraer dependencias, estructura de directorios, estilos, configuraciones, rutas)"]
Step1 --> Step2["2. Entrevista sobre Páginas y Necesidades<br/>(Páginas ➔ Secciones ➔ Componentes)"]
Step2 --> Step3["3. Generar Especificaciones Canónicas<br/>(docs/project.json y registros en lib/)"]
Step3 --> Step4["4. Documentar Estrategia y Sistemas de Diseño<br/>(docs/design/ 01-estrategia, 02-mapa-del-sitio, 03-tokens)"]
Step4 --> Step5["5. Generar Plan de Implementación Modular de 7 Fases<br/>(docs/plan/ README.md y archivos de fase 01-07)"]
Step5 --> Step6["6. Finalización y Cierre<br/>(Presentar panel de resumen; NO invocar skills posteriores)"]
Arquitectura de Directorios Estándar del Proyecto
├── lib/ # Fuente de verdad de código Next.js tipado
│ ├── routes.ts # Registro centralizado de rutas y constructores de rutas
│ ├── site-config.ts # Metadatos del sitio, biografía del autor, enlaces sociales
│ └── utils.ts # Helper de Tailwind cn
├── docs/ # Arquitectura, planificación y justificación de diseño
│ ├── project.json # Especificaciones canónicas legibles por máquina
│ ├── plan/ # Hoja de ruta de implementación modular de 7 fases
│ │ ├── README.md # Panel maestro: Seguimiento del progreso e índice de fases
│ │ ├── 01-descubrimiento-y-arquitectura.md
│ │ ├── 02-entorno-y-cicd.md
│ │ ├── 03-sonda-de-salud-del-sistema.md
│ │ ├── 04-fundamentos-nucleares.md
│ │ ├── 05-paginas-y-componentes.md
│ │ ├── 06-funciones-del-servidor-y-metadatos.md
│ │ └── 07-integraciones-y-lanzamiento.md
│ ├── design/ # Especificaciones de UX, UI y pantallas
│ │ ├── 01-informe-de-estrategia.md # Propósito, personas, objetivos, KPIs, benchmarks
│ │ ├── 02-mapa-del-sitio-y-rutas.md # Inventario de páginas, jerarquía de secciones, matriz de renderizado
│ │ ├── 03-tokens-de-diseno-ui.md # Tokens CSS semánticos, tipografía, primitivas de componentes
│ │ └── components/ # Especificaciones de diseño de componentes y capturas de Stitch
│ └── adr/ # Registros de Decisiones de Arquitectura
Manual de Ejecución Paso a Paso
1. Inspección Automática del Espacio de Trabajo (Sin Interrupción)
[!IMPORTANT] Inspeccionar primero, preguntar después. Nunca le pidas al usuario información que se pueda deducir directamente de los archivos del espacio de trabajo.
- Escanear el Contexto del Espacio de Trabajo: Inspeccionar
package.json, archivos de bloqueo (pnpm-lock.yaml,bun.lockb), estructura de enrutamiento (app/vssrc/app/), directorio de componentes,app/globals.css, librerías UI (shadcn/ui,lucide-react, animaciones), configuración denext-intl(carpeta raízmessages/), rutas existentes (page.tsx,route.ts) y configuraciones de testing/Docker. - Para la lista de verificación completa de inspección, consulta workspace-inspection.md.
2. Entrevista al Usuario (Páginas ➔ Secciones ➔ Componentes)
- Realizar Entrevista Adaptativa: Involucrar al usuario en rondas estructuradas utilizando la metodología de frontera de entrevista. Numerar cada pregunta y proporcionar respuestas recomendadas.
- Secuencia Obligatoria de la Entrevista:
- Entrevista de Páginas: Enumerar todas las páginas web requeridas y las rutas URL de destino.
- Entrevista de Secciones: Para cada página, identificar todas las secciones de contenido de arriba a abajo.
- Entrevista de Componentes: Para cada sección, definir todos los componentes UI requeridos.
- Preguntas Clave: Declaración del problema, personas objetivo, autenticación, capa de datos/ORM, locales de i18n y RTL, tono estético visual y destino de despliegue.
- Para plantillas de entrevista y reglas del árbol de decisiones, consulta grilling-interview.md.
3. Generar Especificaciones Canónicas y Código Tipado
- Crear
docs/project.json: Rellenar metadatos técnicos (gestor de paquetes, directorios de componentes, estilos, librerías UI/animación/testing, idiomas compatibles, rutas de diccionarios). Consultar project-schema.md y desplegar project.json.template. - Crear
lib/routes.ts: Generar registro de rutas tipado a partir de routes.ts.template. - Crear
lib/site-config.ts: Generar perfil y metadatos centralizados del sitio a partir de site-config.ts.template.
4. Documentar la Estrategia de Diseño en docs/design/
- Crear
docs/design/01-informe-de-estrategia.md: Desplegar 01-informe-de-estrategia.md.template. - Crear
docs/design/02-mapa-del-sitio-y-rutas.md: Desplegar 02-mapa-del-sitio-y-rutas.md.template. - Crear
docs/design/03-tokens-de-diseno-ui.md: Desplegar 03-tokens-de-diseno-ui.md.template.
5. Generar la Hoja de Ruta de Implementación Modular de 7 Fases (docs/plan/)
- Crear la Estructura del Directorio
docs/plan/: Desplegar los archivos del plan modular utilizando las plantillas en resources/templates/plan/:docs/plan/README.md(Panel maestro de progreso)docs/plan/01-descubrimiento-y-arquitectura.md(Fase 1)docs/plan/02-entorno-y-cicd.md(Fase 2)docs/plan/03-sonda-de-salud-del-sistema.md(Fase 3: Sonda de vitalidad/api/health)docs/plan/04-fundamentos-nucleares.md(Fase 4: Variables de entorno, i18n, tokens de tema, layouts, OTel)docs/plan/05-paginas-y-componentes.md(Fase 5: Listas de verificación canónicas de páginas y componentes con SEO y archivos de soporte)docs/plan/06-funciones-del-servidor-y-metadatos.md(Fase 6: Acciones del servidor, rutas API, SEO global)docs/plan/07-integraciones-y-lanzamiento.md(Fase 7: Integraciones y lanzamiento a producción)
- Fuente Única de Verdad con Archivos Obligatorios a Nivel de Página: La Fase 5 (
05-paginas-y-componentes.md) es la lista de verificación canónica exclusiva para páginas y componentes. Para cada página, imponer tareas de sublista de verificación parapage.tsx,loading.tsx,error.tsx,generateMetadata,JSON-LD SchemaygenerateStaticParams()(para rutas dinámicas). - Regla de Finalización de Página: En la Fase 5, marcar un elemento de página como
- [x]solo si y solo cuando todas las tareas de su sublista de verificación de componentes y las tareas de SEO/soporte a nivel de página estén completadas. - Consultar plan-checklist-structure.md para las pautas completas de las fases.
6. Cierre y Puerta de Finalización
- Presentar al usuario un informe de resumen conciso que detalle los hallazgos del espacio de trabajo, las especificaciones en
docs/project.jsony la hoja de ruta endocs/plan/README.md. - NO invocar automáticamente skills posteriores de Next.js. Concluir la ejecución y permitir que el usuario revise el plan.
Casos Extremos y Errores Conocidos de la IA
[!WARNING]
- Encadenar Comandos: Nunca ejecutar comandos compuestos usando
&&,||o;en una sola línea. Ejecutar siempre los comandos de terminal de forma individual.- Preguntar Antes de Inspeccionar: No preguntar al usuario por datos básicos que se puedan leer directamente de
package.jsono de los listados de directorios.- Secuencia Invertida de Hitos: La sonda de salud (
/api/health) pertenece a la Fase 3, seguida de los Fundamentos Nucleares (i18n, Tema, Layouts, OTel) en la Fase 4 antes de la implementación de páginas/componentes.- Omitir Archivos a Nivel de Página: Al redactar las listas de verificación de la Fase 5, nunca omitir las tareas de
loading.tsx,error.tsx,generateMetadatao JSON-LD schema para ninguna página.- Duplicación de Lista de Páginas: Mantener todo el seguimiento de páginas y componentes estrictamente en
docs/plan/05-paginas-y-componentes.md.- Marcado Prematuro de Página: Una página en la Fase 5 debe permanecer como
- [ ]hasta que cada componente hijo y archivo de soporte a nivel de página esté completado.- Ubicación Incorrecta del Diccionario: En configuraciones de i18n de Next.js, los diccionarios se ubican en la carpeta raíz
messages/(ej.,messages/en.json), nunca enapp/dictionaries.- Invocar Skills Posteriores: No activar automáticamente skills de implementación o estilizado al completar el plan; detenerse y esperar la dirección del usuario.
Esquema del Resumen de Salida
Al concluir la fase de planificación, presentar el resumen en este formato:
### Plan de Proyecto Next.js Completado
- **Especificaciones Canónicas**: `[docs/project.json](file:///...)`
- **Registros Tipados**: `[lib/routes.ts](file:///...)` | `[lib/site-config.ts](file:///...)`
- **Especificaciones de Diseño y Estrategia**: `[docs/design/01-informe-de-estrategia.md](file:///...)`, `[docs/design/02-mapa-del-sitio-y-rutas.md](file:///...)`, `[docs/design/03-tokens-de-diseno-ui.md](file:///...)`
- **Panel de la Hoja de Ruta Modular**: `[docs/plan/README.md](file:///...)`
- **Páginas Identificadas**: X rutas totales mapeadas
- **Componentes Identificados**: Y componentes totales catalogados en Z secciones
- **Fases Completadas**: N / 7 fases verificadas
_Planificación completa. Revisar `docs/plan/README.md` para proceder con el diseño de componentes o la implementación._
Guías de Referencia y Plantillas
- Guía de Inspección del Espacio de Trabajo — Lista de verificación de descubrimiento del código fuente previa a la entrevista.
- Guía de Entrevista — Protocolo de preguntas en múltiples rondas y áreas de indagación.
- Referencia del Esquema del Proyecto — Campos de especificación y criterios de validación para
docs/project.json. - Referencia de la Arquitectura del Plan — Estructura de la hoja de ruta modular de 7 fases y reglas de páginas y componentes.
- Plantilla JSON del Proyecto — Esquema de inicio para
docs/project.json. - Plantillas del Plan Modular — Plantillas de inicio para
docs/plan/. - Plantilla TypeScript de Rutas — Definiciones de rutas tipadas para
lib/routes.ts. - Plantilla de Configuración del Sitio — Perfil centralizado del sitio para
lib/site-config.ts. - Plantilla del Informe de Estrategia — Plantilla para
docs/design/01-informe-de-estrategia.md. - Plantilla del Mapa del Sitio y Rutas — Plantilla para
docs/design/02-mapa-del-sitio-y-rutas.md. - Plantilla de Tokens de Diseño UI — Plantilla para
docs/design/03-tokens-de-diseno-ui.md. - Plantilla de Ejemplo de Variables de Entorno — Plantilla de fuente única de verdad para
.env.example(renombrado a.envpara despliegues de producción). - Plantilla de Entorno de Desarrollo — Variables de desarrollo predeterminadas para
.env.development(desarrollo local, en gitignore).