specsfy-specialist-astro

Astro

Quando usar

• Acionar quando o projeto tem astro.config ou dependência astro e a tarefa envolve página, layout, componente .astro, content collection, endpoint ou ilha de interatividade.
• Acionar também para decidir output mode (static/server), escolher a diretiva client:* certa, ou diagnosticar JS enviado ao cliente maior que o esperado.
• Não acionar para a lógica interna de um componente React/Vue/Svelte hidratado dentro de uma ilha; usar $specsfy-specialist-react (ou equivalente) para o comportamento do componente em si, mantendo este especialista para a decisão de quando e como hidratá-lo.
• Combinar com $specsfy-specialist-web-accessibility para landmarks, headings e navegação por teclado do site, e com $specsfy-specialist-performance-engineering quando o sintoma for Core Web Vitals fora do SLO.

Fluxo

1. Descobrir versão do Astro, output mode (static/server), adapter, integrações ativas e fontes de conteúdo (Markdown, MDX, CMS remoto) antes de recomendar.
2. Classificar cada rota alterada como estática (conhecida no build), sob demanda (server-rendered por requisição) ou endpoint (contrato HTTP com GET/POST explícitos).
3. Manter HTML estático e zero-JS por padrão; hidratar apenas o componente que precisa de interação, com a diretiva client:* mais restritiva possível para o caso.
4. Modelar conteúdo com content collections e schema (Zod) explícito; tratar frontmatter inválido como erro de build, não como dado tolerado.
5. Definir caching, headers, assets e imagens (astro:assets) por rota, coerente com o output mode escolhido.
6. Testar astro check, build de produção, conteúdo inválido no schema e o comportamento hidratado de cada ilha isoladamente.
7. Medir payload de JS enviado ao cliente e Core Web Vitals no adapter alvo real, não apenas no dev server.

Padrões

• Usar a menor diretiva de hidratação compatível com a interação: client:visible para algo abaixo da dobra, client:idle para algo de baixa prioridade, client:load só quando a interação precisa estar pronta imediatamente; nunca client:load por padrão em tudo.
• Não transportar para uma ilha mais dado do que ela usa para renderizar — cada prop de uma ilha vira JSON serializado no HTML e conta no payload.
• Manter layouts e componentes .astro server-first; um componente .astro nunca precisa de diretiva client:* porque ele não hidrata — apenas os componentes de framework (React/Vue/Svelte) embutidos hidratam.
• Validar todo conteúdo (frontmatter, parâmetros de rota, body de endpoint) na fronteira com schema explícito; tratar slug duplicado ou rota colidente como erro de build, não como comportamento silencioso.
• Escolher server output (SSR) apenas quando personalização por requisição, sessão ou frescor de dado realmente justificar — do contrário, static é mais rápido, mais barato e mais simples de cachear.
• Preservar canonical, sitemap e dados estruturados (JSON-LD) coerentes com a URL final de cada página, inclusive em conteúdo gerado dinamicamente.
• Não assumir APIs completas do Node (fs, process) dentro de adapters edge; confirmar o runtime do adapter alvo antes de usar uma dependência server-only.

Antipadrões

• client:load aplicado "por garantia" em toda ilha da página — infla o JS enviado mesmo quando client:visible ou client:idle bastariam.
• Passar o objeto de dado completo (ex.: registro inteiro do banco) como prop para uma ilha que só exibe dois campos — cada byte extra é serializado e enviado ao navegador.
• Content collection sem schema Zod, "confiando" que o frontmatter está correto — um campo ausente só aparece como bug em produção, não em build.
• Usar server output para o site inteiro quando só uma rota (ex.: um dashboard autenticado) precisa de SSR — perde cache estático nas páginas que não precisavam disso.
• Confundir a responsabilidade desta skill com a do framework hidratado: um bug de estado dentro de uma ilha React é problema de $specsfy-specialist-react, não de configuração de ilha.

Validação

• Rodar astro check, a suíte de testes do projeto e o build de produção completo antes de considerar a mudança pronta.
• Inspecionar o HTML servido com JavaScript desabilitado (deve continuar navegável e legível) e então validar a hidratação de cada ilha isoladamente.
• Percorrer links internos, páginas de erro (404/500), imagens otimizadas e a presença de RSS/sitemap/metadados quando o site os expõe.
• Fazer preview no runtime real do adapter (não só astro dev), medindo payload de JS por rota e Core Web Vitals antes/depois da mudança.
• Não declarar uma página "estática" ou "zero-JS" sem inspecionar o HTML gerado; linguagem absoluta sem essa evidência é proibida.

Skills relacionadas

• $specsfy-specialist-react-ui-components fornece referências TSX para ilhas React; esta skill decide onde a ilha existe e como ela hidrata no Astro.
• $specsfy-specialist-react (ou o framework de UI equivalente) para a lógica interna do componente hidratado dentro de uma ilha.
• $specsfy-specialist-web-accessibility para landmarks, headings e ordem de foco do site publicado.
• $specsfy-specialist-performance-engineering para investigar Core Web Vitals com metodologia de medição própria.
• $specsfy-specialist-web-api-design quando um endpoint Astro expõe um contrato HTTP consumido por outro cliente além do próprio site.
• $specsfy-specialist-typescript para o schema de content collections, props de componente e tipos de endpoint.
• $specsfy-specialist-tailwind-css e $specsfy-specialist-shadcn-ui para a camada de estilo e os componentes visuais usados em layouts e ilhas.
• Não use $specsfy-specialist-nextjs para decisões deste projeto: são frameworks distintos com fronteiras server/client e cache diferentes; migrar um padrão de um para o outro sem checar a skill correspondente costuma quebrar a semântica de cache.

Leia references/standards.md para modos de renderização, ilhas, content collections, actions, imagens e deploy, com fontes oficiais.