Skill de Planejamento de Projetos Next.js (nextjs-plan)
Uma skill de orquestração estruturada para planejar aplicações Next.js App Router. Quando invocada, extrai especificações técnicas de arquivos existentes do workspace, conduz uma entrevista direcionada sobre os requisitos do usuário e gera especificações canônicas (docs/project.json), registros de código type-safe em lib/, briefings de design em docs/design/ e um roadmap de implementação modular em 7 fases em docs/plan/.
Visão Geral do Fluxo de Trabalho
flowchart TD
Invoke["Invocar /nextjs-plan"] --> Step1["1. Inspeção Automatizada do Workspace<br/>(Extrair dependências, layout de diretórios, estilos, configurações, rotas)"]
Step1 --> Step2["2. Entrevista Detalhada sobre Páginas e Necessidades<br/>(Páginas ➔ Seções ➔ Componentes)"]
Step2 --> Step3["3. Gerar Especificações Canônicas<br/>(docs/project.json e lib/ registries)"]
Step3 --> Step4["4. Documentar Estratégia e Sistemas de Design<br/>(docs/design/ 01-strategy, 02-sitemap, 03-tokens)"]
Step4 --> Step5["5. Gerar Plano de Implementação Modular em 7 Fases<br/>(docs/plan/ README.md e arquivos 01-07)"]
Step5 --> Step6["6. Conclusão e Finalização<br/>(Apresentar painel resumo; NÃO invocar skills downstream)"]
Arquitetura Padronizada do Diretório do Projeto
├── lib/ # Fonte da verdade do código Next.js type-safe
│ ├── routes.ts # Registro centralizado de rotas e construtores de caminho
│ ├── site-config.ts # Metadados do site centralizados, biografia do autor, links sociais
│ └── utils.ts # Helper Tailwind cn
├── docs/ # Arquitetura, planejamento e rationale de design
│ ├── project.json # Especificações canônicas legíveis por máquina
│ ├── plan/ # Roadmap de Implementação Modular em 7 Fases
│ │ ├── README.md # Painel mestre: Acompanhamento de progresso e índice de fases
│ │ ├── 01-discovery-and-architecture.md
│ │ ├── 02-environment-and-cicd.md
│ │ ├── 03-system-health-probe.md
│ │ ├── 04-core-foundations.md
│ │ ├── 05-pages-and-components.md
│ │ ├── 06-server-functions-and-metadata.md
│ │ └── 07-integrations-and-release.md
│ ├── design/ # Especificações de UX, UI e Telas
│ │ ├── 01-strategy-brief.md # Propósito, personas, objetivos, KPIs, benchmarks
│ │ ├── 02-sitemap-and-routes.md # Inventário de páginas, hierarquia de seções, matriz de renderização
│ │ ├── 03-ui-design-tokens.md # Tokens CSS semânticos, tipografia, primitivos de componentes
│ │ └── components/ # Especificações de design de componentes e capturas de tela Stitch
│ └── adr/ # Registros de Decisões de Arquitetura
Manual de Execução Passo a Passo
1. Inspeção Automatizada do Workspace (Sem Interrupção)
[!IMPORTANT] Inspecione primeiro, pergunte depois. Nunca pergunte ao usuário por fatos que podem ser deduzidos diretamente dos arquivos do workspace.
- Escaneie o Contexto do Workspace: Inspecione
package.json, lockfiles (pnpm-lock.yaml,bun.lockb), estrutura de roteamento (app/vssrc/app/), diretório de componentes,app/globals.css, bibliotecas de UI (shadcn/ui,lucide-react, animações), configuraçãonext-intl(pasta raizmessages/), rotas existentes (page.tsx,route.ts) e configurações de teste/Docker. - Para a lista de verificação completa de inspeção, consulte workspace-inspection.md.
2. Entrevista Detalhada com o Usuário (Páginas ➔ Seções ➔ Componentes)
- Conduza Entrevista Detalhada Adaptativa: Envolva o usuário em rodadas estruturadas usando a metodologia de grilling frontier. Numere cada pergunta e forneça respostas recomendadas.
- Sequência Obrigatória da Entrevista:
- Perguntas sobre Páginas: Enumere todas as páginas web necessárias e as rotas de URL de destino.
- Perguntas sobre Seções: Para cada página, identifique todas as seções de conteúdo de cima para baixo.
- Perguntas sobre Componentes: Para cada seção, defina todos os componentes de UI necessários.
- Perguntas Principais: Declaração do problema, personas-alvo, autenticação, camada de dados/ORM, locales i18n e RTL, tom visual estético e destino de implantação.
- Para modelos de entrevista e regras de árvore de decisão, consulte grilling-interview.md.
3. Gerar Especificações Canônicas e Código Type-Safe
- Crie
docs/project.json: Preencha metadados técnicos (gerenciador de pacotes, diretórios de componentes, estilos, bibliotecas de UI/animação/teste, idiomas suportados, caminhos de dicionário). Consulte project-schema.md e implante project.json.template. - Crie
lib/routes.ts: Gere registro de rotas type-safe a partir de routes.ts.template. - Crie
lib/site-config.ts: Gere perfil e metadados centralizados do site a partir de site-config.ts.template.
4. Documentar Estratégia de Design em docs/design/
- Crie
docs/design/01-strategy-brief.md: Implante 01-strategy-brief.md.template. - Crie
docs/design/02-sitemap-and-routes.md: Implante 02-sitemap-and-routes.md.template. - Crie
docs/design/03-ui-design-tokens.md: Implante 03-ui-design-tokens.md.template.
5. Gerar Roadmap de Implementação Modular em 7 Fases (docs/plan/)
- Estruture o Diretório
docs/plan/: Implante os arquivos de plano modulares usando os templates em resources/templates/plan/:docs/plan/README.md(Painel Mestre de Progresso)docs/plan/01-discovery-and-architecture.md(Fase 1)docs/plan/02-environment-and-cicd.md(Fase 2)docs/plan/03-system-health-probe.md(Fase 3: Sonda de Vitalidade/api/health)docs/plan/04-core-foundations.md(Fase 4: Variáveis de ambiente, i18n, Tokens de Tema, Layouts, OTel)docs/plan/05-pages-and-components.md(Fase 5: Listas de Verificação Canônicas de Páginas e Componentes com SEO e arquivos de suporte)docs/plan/06-server-functions-and-metadata.md(Fase 6: Server Actions, Rotas de API, SEO Global)docs/plan/07-integrations-and-release.md(Fase 7: Integrações e Lançamento de Produção)
- Fonte Única da Verdade com Arquivos Obrigatórios no Nível da Página: A Fase 5 (
05-pages-and-components.md) é a lista de verificação canônica exclusiva para páginas e componentes. Para cada página, imponha tarefas de sub-lista de verificação parapage.tsx,loading.tsx,error.tsx,generateMetadata,JSON-LD Schema, egenerateStaticParams()(para rotas dinâmicas). - Regra de Conclusão de Página: Na Fase 5, marque um item de página como
- [x]se e somente se todos os itens de sua sub-lista de verificação de componentes e tarefas de SEO/suporte no nível da página estiverem concluídos. - Consulte plan-checklist-structure.md para diretrizes completas das fases.
6. Finalização e Portão de Conclusão
- Apresente um relatório resumo conciso ao usuário detalhando as descobertas do workspace, especificações em
docs/project.jsone roadmap emdocs/plan/README.md. - NÃO invoque automaticamente skills downstream do Next.js. Conclua a execução e permita que o usuário revise o plano.
Casos Extremos e Armadilhas Conhecidas de IA
[!WARNING]
- Encadeamento de Comandos: Nunca execute comandos compostos usando
&&,||, ou;em uma única linha. Sempre execute comandos de terminal individualmente.- Perguntar Antes de Inspecionar: Não pergunte ao usuário por fatos básicos que podem ser lidos diretamente de
package.jsonou listagens de diretórios.- Sequenciamento Invertido de Marcos: A sonda de vitalidade (
/api/health) pertence à Fase 3, seguida pelas Fundações Principais (i18n, Tema, Layouts, OTel) na Fase 4, antes da implementação de páginas/componentes.- Omissão de Arquivos no Nível da Página: Ao criar as listas de verificação da Fase 5, nunca omita
loading.tsx,error.tsx,generateMetadataou tarefas de esquema JSON-LD para qualquer página.- Duplicação de Lista de Páginas: Mantenha todo o rastreamento de páginas e componentes estritamente em
docs/plan/05-pages-and-components.md.- Marcação Prematura de Página: Uma página na Fase 5 deve permanecer
- [ ]até que todos os componentes filhos e arquivos de suporte no nível da página sejam concluídos.- Localização Incorreta de Dicionário: Em configurações i18n do Next.js, os dicionários estão localizados na pasta raiz
messages/(por exemplo,messages/en.json), nunca emapp/dictionaries.- Invocação de Skills Downstream: Não acione automaticamente skills de implementação ou estilo após concluir o plano; pare e aguarde a orientação do usuário.
Esquema de Resumo de Saída
Ao concluir a fase de planejamento, apresente o resumo neste formato:
### Plano do Projeto Next.js Concluído
- **Especificações Canônicas**: `[docs/project.json](file:///...)`
- **Registros Type-Safe**: `[lib/routes.ts](file:///...)` | `[lib/site-config.ts](file:///...)`
- **Especificações de Design e Estratégia**: `[docs/design/01-strategy-brief.md](file:///...)`, `[docs/design/02-sitemap-and-routes.md](file:///...)`, `[docs/design/03-ui-design-tokens.md](file:///...)`
- **Painel do Roadmap Modular**: `[docs/plan/README.md](file:///...)`
- **Páginas Identificadas**: X rotas totais mapeadas
- **Componentes Identificados**: Y componentes totais catalogados em Z seções
- **Fases Concluídas**: N / 7 fases verificadas
_Planejamento concluído. Revise `docs/plan/README.md` para prosseguir com o design de componentes ou implementação._
Guias de Referência e Templates
- Guia de Inspeção do Workspace — Lista de descoberta da base de código pré-entrevista.
- Guia de Entrevista Detalhada — Protocolo de questionamento em várias rodadas e áreas de investigação.
- Referência do Esquema do Projeto — Campos de especificação e critérios de validação para
docs/project.json. - Referência da Arquitetura do Plano — Estrutura do roadmap modular de 7 fases e regras de página-componente.
- Template JSON do Projeto — Esquema inicial para
docs/project.json. - Templates de Plano Modular — Templates iniciais para
docs/plan/. - Template TypeScript de Rotas — Definições de rotas type-safe para
lib/routes.ts. - Template de Configuração do Site — Perfil do site centralizado para
lib/site-config.ts. - Template de Briefing de Estratégia — Template para
docs/design/01-strategy-brief.md. - Template de Sitemap e Rotas — Template para
docs/design/02-sitemap-and-routes.md. - Template de Tokens de Design UI — Template para
docs/design/03-ui-design-tokens.md. - Template de Exemplo de Variáveis de Ambiente — Template fonte única da verdade para
.env.example(renomeado para.envem implantações de produção). - Template de Ambiente de Desenvolvimento — Variáveis de desenvolvimento padrão para
.env.development(desenvolvimento local, gitignored).