specsfy-specialist-astro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当项目包含
```
astro.config
```
或
```
astro
```
依赖，且任务涉及页面、布局、
```
.astro
```
组件、content collection、端点或交互式孤岛时触发。
也可用于确定输出模式（static/server）、选择正确的
```
client:*
```
指令，或诊断客户端JS体积超出预期的问题。
请勿用于孤岛内部已hydrated的React/Vue/Svelte组件逻辑；组件自身行为请使用
```
$specsfy-specialist-react
```
（或对应框架的技能），本技能仅用于决定何时及如何进行hydration。
若涉及网站的地标、标题及键盘导航，请结合
```
$specsfy-specialist-web-accessibility
```
技能；若症状为Core Web Vitals未达SLO标准，请结合
```
$specsfy-specialist-performance-engineering
```
技能。

Fluxo

流程

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.

在给出建议前，先了解Astro版本、输出模式（
```
static
```
/
```
server
```
）、适配器、已启用的集成及内容来源（Markdown、MDX、远程CMS）。
将每个变更的路由分类为静态（构建时已知）、按需（请求时服务端渲染）或端点（具有明确
```
GET
```
/
```
POST
```
的HTTP契约）。
默认保持静态HTML和零JS；仅对需要交互的组件进行hydration，并使用针对场景限制最严格的
```
client:*
```
指令。
使用content collections和明确的Zod schema建模内容；将无效的frontmatter视为构建错误，而非可容忍的数据。
根据所选输出模式，按路由定义缓存、头部、资源及图片（
```
astro:assets
```
）。
测试
```
astro check
```
、生产构建、schema无效内容，以及每个孤岛的独立hydration行为。
在实际目标适配器上测量客户端JS负载及Core Web Vitals，而非仅在开发服务器上测试。

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.

使用与交互需求兼容的最严格hydration指令：对于首屏下方的内容使用
```
client:visible
```
，低优先级内容使用
```
client:idle
```
，仅当交互需要立即就绪时使用
```
client:load
```
；切勿默认对所有内容使用
```
client:load
```
。
不要向孤岛传递超出其渲染所需的数据——孤岛的每个prop都会在HTML中序列化为JSON，并计入负载。
保持布局和
```
.astro
```
组件为服务端优先；
```
.astro
```
组件永远不需要
```
client:*
```
指令，因为它不会被hydrated——只有嵌入的框架组件（React/Vue/Svelte）才会被hydrated。
使用明确的schema在边界验证所有内容（frontmatter、路由参数、端点请求体）；将重复slug或路由冲突视为构建错误，而非静默行为。
仅当确实需要基于请求、会话的个性化或数据实时性时，才选择
```
server
```
输出（SSR）；否则，
```
static
```
模式更快、成本更低且更易于缓存。
确保每个页面的最终URL对应的
```
canonical
```
、站点地图和结构化数据（JSON-LD）保持一致，包括动态生成的内容。
不要在边缘适配器中假设完整的Node API（如
```
fs
```
、
```
process
```
）；在使用服务端专属依赖前，确认目标适配器的运行时环境。

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.

为页面所有孤岛“保险起见”应用
```
client:load
```
——即使
```
client:visible
```
或
```
client:idle
```
足够，也会增加客户端JS体积。
将完整数据对象（如数据库整条记录）作为prop传递给仅显示两个字段的孤岛——额外的每个字节都会被序列化并发送到浏览器。
不使用Zod schema的content collection，“信任”frontmatter是正确的——缺失字段只会在生产环境中表现为bug，而非构建时错误。
当仅一个路由（如认证后的仪表板）需要SSR时，为整个网站使用
```
server
```
输出——会失去无需SSR页面的静态缓存优势。
混淆本技能与hydrated框架的职责：React孤岛内的状态bug属于
```
$specsfy-specialist-react
```
的问题，而非孤岛配置问题。

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.

在确认变更完成前，运行
```
astro check
```
、项目测试套件及完整生产构建。
在禁用JavaScript的情况下检查提供的HTML（应仍可浏览和阅读），然后单独验证每个孤岛的hydration情况。
遍历内部链接、错误页面（404/500）、优化后的图片，以及网站提供的RSS/站点地图/元数据是否存在。
在适配器的真实运行时环境中预览（而非仅
```
astro dev
```
），测量变更前后每个路由的JS负载及Core Web Vitals。
未检查生成的HTML时，请勿宣称页面为“静态”或“零JS”；无此证据的绝对表述是禁止的。

specsfy-specialist-astro

Original

Translation

Astro

Astro

Quando usar

适用场景

Fluxo

流程

Padrões

规范

Antipadrões

反模式

Validação

验证

Skills relacionadas

相关技能