Especialista Astro no Specsfy: documentação técnica

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.

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.
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).
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.
Modelar conteúdo com content collections e schema (Zod) explícito, tratar frontmatter inválido como erro de build, não como dado tolerado.
Definir caching, headers, assets e imagens (astro:assets) por rota, coerente com o output mode escolhido.
Testar astro check, build de produção, conteúdo inválido no schema e o comportamento hidratado de cada ilha isoladamente.
Medir payload de JS enviado ao cliente e Core Web Vitals no adapter alvo real, não apenas no dev server.

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.

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.

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.

$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.