specsfy-specialist-astro

Astro

使用する場合

• プロジェクトに astro.config または astro 依存関係があり、タスクがページ、レイアウト、.astro コンポーネント、コンテンツコレクション、エンドポイント、またはインタラクティブなアイランドに関わる場合に使用します。
• output mode（static/server）の決定、適切な client:* ディレクティブの選択、またはクライアントに送信される JS が想定より多い場合の診断にも使用します。
• アイランド内でハイドレーションされた React/Vue/Svelte コンポーネントの内部ロジックには使用しません。コンポーネント自体の動作には $specsfy-specialist-react（または同等のもの）を使用し、このスペシャリストはハイドレーションのタイミングと方法の判断を担当します。
• サイトのランドマーク、見出し、キーボードナビゲーションには $specsfy-specialist-web-accessibility と組み合わせます。症状が Core Web Vitals の SLO 未達である場合は、$specsfy-specialist-performance-engineering と組み合わせます。

ワークフロー

1. 推奨を行う前に、Astro のバージョン、output mode（static/server）、アダプター、有効なインテグレーション、コンテンツソース（Markdown、MDX、リモート CMS）を確認します。
2. 変更する各ルートを、静的（ビルド時に確定）、オンデマンド（リクエストごとにサーバーでレンダリング）、エンドポイント（明示的な GET/POST を持つ HTTP コントラクト）に分類します。
3. デフォルトでは静的 HTML とゼロ JS を維持し、インタラクションが必要なコンポーネントのみを、そのケースで可能な限り制約の強い client:* ディレクティブでハイドレーションします。
4. コンテンツはコンテンツコレクションと明示的なスキーマ（Zod）でモデル化し、無効な frontmatter は許容されるデータではなくビルドエラーとして扱います。
5. 選択した output mode と整合するように、ルートごとにキャッシュ、ヘッダー、アセット、画像（astro:assets）を定義します。
6. astro check、本番ビルド、スキーマに対して無効なコンテンツ、各アイランドのハイドレーション後の動作を個別にテストします。
7. 開発サーバーだけでなく、実際の対象アダプターでクライアントに送信される JS のペイロードと Core Web Vitals を測定します。

パターン

• インタラクションに対応できる最小限のハイドレーションディレクティブを使用します。画面下部のコンテンツには client:visible、優先度の低いものには client:idle、インタラクションを直ちに利用可能にする必要がある場合に限り client:load を使用します。すべてにデフォルトで client:load を使うことは避けます。
• レンダリングに使用する以上のデータをアイランドに渡さないでください。アイランドの各 prop は HTML 内で JSON にシリアライズされ、ペイロードに加算されます。
• レイアウトと .astro コンポーネントはサーバー優先で維持します。.astro コンポーネントはハイドレーションされないため、client:* ディレクティブは必要ありません。ハイドレーションされるのは、埋め込まれたフレームワークのコンポーネント（React/Vue/Svelte）のみです。
• すべてのコンテンツ（frontmatter、ルートパラメーター、エンドポイントの body）を、境界で明示的なスキーマにより検証します。重複した slug や競合するルートは、暗黙の動作ではなくビルドエラーとして扱います。
• リクエストごとのパーソナライズ、セッション、またはデータの鮮度が本当に必要な場合に限り、server output（SSR）を選択します。それ以外の場合は、static のほうが高速で、低コストで、キャッシュも容易です。
• 動的に生成されるコンテンツも含め、各ページの最終 URL と canonical、サイトマップ、構造化データ（JSON-LD）との整合性を保ちます。
• edge アダプター内で Node の API（fs、process）がすべて利用できると想定しないでください。サーバー専用の依存関係を使用する前に、対象アダプターのランタイムを確認します。

アンチパターン

• ページ内のすべてのアイランドに「念のため」client:load を適用する — client:visible または client:idle で十分な場合でも、送信される JS が増えます。
• 2 つのフィールドを表示するだけのアイランドに、データオブジェクト全体（例：データベースのレコード全体）を props として渡す — 余分なバイトがすべてシリアライズされ、ブラウザーに送信されます。
• Zod スキーマなしでコンテンツコレクションを使い、フロントマターが正しいと「信頼する」 — 欠落したフィールドはビルド時ではなく、本番環境でバグとして初めて現れます。
• SSR が必要なのが 1 つのルート（例：認証が必要なダッシュボード）だけなのに、サイト全体で server 出力を使う — その必要がないページでも静的キャッシュが失われます。
• このスキルの責任範囲と、ハイドレーション対象のフレームワークの責任範囲を混同する — React アイランド内の状態に関するバグは、アイランド設定ではなく $specsfy-specialist-react の問題です。

検証

• 変更を完了と見なす前に、astro check、プロジェクトのテストスイート、プロダクションビルド全体を実行します。
• JavaScript を無効にした状態で配信される HTML を確認します（引き続きナビゲーション可能で、読みやすい必要があります）。その後、各アイランドのハイドレーションを個別に検証します。
• 内部リンク、エラーページ（404/500）、最適化された画像、サイトが公開している場合は RSS／サイトマップ／メタデータの有無を確認します。
• astro dev だけでなく、アダプターの実際のランタイムでプレビューし、変更前後のルートごとの JS ペイロードと Core Web Vitals を測定します。
• 生成された HTML を確認せずに、ページを「静的」または「ゼロ JS」と断言してはいけません。この証拠がない絶対的な表現は禁止されています。

関連スキル

• $specsfy-specialist-react-ui-components は React アイランド向けの TSX 参考資料を提供します。このスキルでは、アイランドをどこに配置するか、Astro でどのようにハイドレーションするかを判断します。
• アイランド内のハイドレーション対象コンポーネントの内部ロジックには、$specsfy-specialist-react（または同等の UI フレームワーク）を使用します。
• 公開サイトのランドマーク、見出し、フォーカス順序には $specsfy-specialist-web-accessibility を使用します。
• 独自の測定方法で Core Web Vitals を調査するには $specsfy-specialist-performance-engineering を使用します。
• Astro のエンドポイントが、サイト自体以外のクライアントにも利用される HTTP コントラクトを公開する場合は $specsfy-specialist-web-api-design を使用します。
• コンテンツコレクションのスキーマ、コンポーネントの props、エンドポイントの型には $specsfy-specialist-typescript を使用します。
• レイアウトやアイランドで使用するスタイルレイヤーと視覚コンポーネントには $specsfy-specialist-tailwind-css と $specsfy-specialist-shadcn-ui を使用します。
• このプロジェクトの判断に $specsfy-specialist-nextjs を使用しないでください。これらは、サーバー／クライアントの境界とキャッシュの仕組みが異なる別のフレームワークです。対応するスキルを確認せずに一方のパターンを他方へ移行すると、キャッシュのセマンティクスが損なわれることがよくあります。

レンダリングモード、アイランド、コンテンツコレクション、アクション、画像、デプロイについて、公式ソースとともに解説している references/standards.md を参照してください。