Convenções Frontend
Convenções para gerar "código bom e consistente" na arquitetura Next.js 16 + React 19 + TanStack Query v5 + FSD.
Quando Usar Este Skill
- Ao criar uma nova entity, feature ou widget
- Ao implementar formulários CRUD ou tabelas de dados
- Ao refatorar código existente
- Ao verificar se o projeto está em conformidade com as convenções
- Ao aplicar padrões de camada de API, gerenciamento de estado e tratamento de erros
Stack Tecnológica
- Next.js 16.1.6 (App Router) + React 19.2.3 + TypeScript 5.9.2
- @tanstack/react-query ^5 + @tanstack/react-table ^8.21.3
- react-hook-form ^7.71.2 + zod ^3.25.76
- nuqs ^2.8.9 (estado da URL)
- Tailwind CSS ^4 + shadcn/ui (radix-nova) + sonner ^2.0.7 (toast)
- Turborepo ^2.8.12 + pnpm 9.0+ (interno:
@workspace/ui,@workspace/api)
Categorias de Regras
11 categorias, 67 regras. Consulte os arquivos relevantes para sua tarefa:
| Área | Arquivo | Quando Consultar |
|---|---|---|
| Arquitetura | rules/architecture.md | Camadas FSD, direção de imports, entity slice, barrel export |
| Padrões Next.js | rules/nextjs-patterns.md | Page thin shell, Providers, 'use client', arquivos especiais |
| Qualidade de Código | rules/code-quality.md | Dynamic import, conditional render, early return, forwardRef |
| Consultas | rules/queries.md | Fábrica queryOptions, chaves de query, staleTime, prefetch, useQueries |
| Mutações | rules/mutations.md | invalidate, useApiMutation, optimistic |
| Camada de API | rules/api-layer.md | Objeto API, tipos de resposta, prefetch SSR |
| Formulários | rules/forms.md | Esquema zod, useForm, FormDialog, padrões de edição |
| Tabelas | rules/tables.md | DataTable, colunas, paginação no servidor |
| Gerenciamento de Estado | rules/state-management.md | nuqs, useState, proibição de estado global |
| Tratamento de Erros | rules/error-handling.md | ApiError, toast, Error Boundary |
| Nomenclatura | rules/naming.md | Nomenclatura de arquivos/hooks/tipos/constantes |
Consulte o índice completo em INDEX.md.
Níveis de Severidade
Cada regra possui um dos três níveis de rigor:
| Nível | Significado | Ação da IA |
|---|---|---|
| 🚫 OBRIGATÓRIO | Violação absoluta não permitida | Sempre seguir este padrão |
| ⚠️ RECOMENDADO | Seguir a menos que haja um motivo especial | Aplicar por padrão, justificar exceções com comentário |
| ✅ OPCIONAL | Recomendado, mas flexível | Julgar de acordo com a situação |
Fluxo de Validação
Ao solicitar "valide este projeto com base nas convenções", siga esta ordem:
- Verificar stack tecnológico — Confirmar versões de Next.js/React/TanStack Query no package.json
- Verificar estrutura FSD (PS-01~05) — Existência de apps/*/entities, features, widgets, shared
- Validar direção de imports (PS-02) — Pesquisar imports de entity para features/widgets
- Completude de Entity (PS-03) — Verificar se cada entity possui api.ts, queries.ts, hooks.ts, types.ts, index.ts
- Padrões de Mutação (DF-06, DF-07) — Taxa de uso de useApiMutation, procurar violações de raw useMutation
- Padrões de Formulário (FM-01~07) — Localização do esquema zod, uso de useForm+zodResolver, extração de hook de formulário
- Padrões de Tabela (TB-01~05) — Instância useReactTable, modo manual server-side
- Gerenciamento de Estado (SM-01) — Verificar uso de Context/zustand (proibido)
- Regras de Nomenclatura de Arquivos (NM-01) — Taxa de conformidade com kebab-case
Formato de saída:
- Lista de violações (ID da regra +
arquivo:linha+ sugestão de correção) - Resumo da taxa de conformidade (por categoria)
- Recomendações por prioridade (🚫 primeiro, ⚠️ depois)
Início Rápido por Tarefa
Adicionar nova entity: architecture → api-layer → queries → mutations → naming Implementar formulário CRUD: forms → mutations (DF-06, DF-07) → naming Implementar página de tabela: tables → state-management → queries Adicionar nova página/rota: nextjs-patterns → architecture (PS-02, PS-05) Tratamento de erros: error-handling Otimização de desempenho: code-quality → queries (DF-10~12) Refatoração de código existente: Arquivo completo de regras da área
Referências
- Melhores práticas de criação de skills da Anthropic: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Documentação do TanStack Query v5: https://tanstack.com/query/latest
- Feature-Sliced Design: https://feature-sliced.design