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.

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.