astro-developer

Astro Developer Skill

Astro モノレポで作業する AI エージェントや開発者向けのコンテキスト読み込みスキルです。タスクに応じた関連ドキュメントを読み込みます。

クイック判断マトリックス

何をしていますか？ → 以下のファイルを読んでください：

タスク	主なドキュメント	参考ドキュメント
コア機能の追加	architecture.md, constraints.md	testing.md
バグの修正	debugging.md	architecture.md
テストの作成・修正	testing.md	constraints.md
インテグレーションの作成	packages/integrations/ で例を探します	testing.md
アーキテクチャの理解	architecture.md	-
エラーへの対処	debugging.md, constraints.md	testing.md
制約の理解	constraints.md	architecture.md

重要な警告

作業を始める前に、よくある落とし穴を確認してください：

1. ユニットテストを優先する：原則として、ユニットテスト可能なコードを書いてください。必要な場合にのみインテグレーションテストを使用します → testing.md
2. Node.js API の制限：runtime/ のコードでは Node.js API を使用できません → constraints.md
3. テストの分離：インテグレーションテストごとに一意の outDir を設定する必要があります → testing.md
4. ランタイムの境界：Core、Vite、ブラウザーの実行コンテキスト → architecture.md
5. プレリリースモード：Changesets の対象は origin/next ブランチです（.changeset/config.json を確認してください）

クイックコマンドリファレンス

# Development
pnpm install                                    # Install (root only)
pnpm run build                                  # Build all packages
pnpm run dev                                    # Watch mode
pnpm run lint                                   # Lint codebase

# Testing
pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js"  # All tests
pnpm -C packages/astro exec astro-scripts test -m "pattern"         # Filter tests
pnpm run test:e2e                               # E2E tests
node --test test/file.test.js                   # Single test

# Examples
pnpm --filter @example/minimal run dev          # Run example

# Changesets
pnpm exec changeset --empty                     # Create changeset, no interactive mode

主なファイルパス

packages/astro/src/
├── core/              # Node.js execution context (build/dev commands)
├── runtime/
│   ├── server/        # Vite SSR execution context
│   └── client/        # Browser execution context
├── virtual-modules/   # Virtual module entry points
├── content/           # Content layer system
├── vite-plugin-*/     # Vite plugins
└── types/             # Centralized TypeScript types

packages/integrations/  # Official integrations
examples/              # Test your changes here
test/fixtures/         # Test fixtures

注：node_modules/ 内のエラースタックトレースは、packages/ 内のソースに対応しています。詳細は architecture.md を参照してください。

使い方

このスキルは関連するコンテキストを読み込みます。ワークフローを実行するものではありません。適切なドキュメントを読み込んだ後は、次の手順に従ってください。

1. タスクに推奨されるファイルを読む
2. 説明されているパターンと制約を適用する
3. 提供されているコマンドとファイルパスを使用する
4. 問題が発生した場合は、エラーメッセージをドキュメント内で検索する

アーキテクチャの概要

3 つの実行コンテキスト：

• core/ → Node.js、ビルド／開発コマンド。Vite プラグイン以外では Node.js API を避けてください
• runtime/server/ → Vite SSR。Node.js API は使用できません
• runtime/client/ → ブラウザー。Node.js API は一切使用できません

5 種類のパイプライン：

• RunnablePipeline → Vite ローダーシステムを使用する astro dev
• NonRunnablePipeline → ランタイムモジュールの読み込みを行わない astro dev（Cloudflare アダプター）
• BuildPipeline → astro build + プリレンダリング
• AppPipeline → 本番環境のサーバーレス／SSR
• ContainerPipeline → コンテナー API

詳細は architecture.md を参照してください。

テストの概要

基本方針：インテグレーションテストよりユニットテストを優先します。原則として、ユニットテスト可能なコードを書いてください。

ユニットテスト（高速で推奨）：

• 純粋関数とビジネスロジックをテストする
• インフラストラクチャからビジネスロジックを切り離す
• 依存性注入を使用する

インテグレーションテスト（低速のため、必要な場合のみ使用）：

• ユニットテストできない機能（仮想モジュール、ビルドパイプライン全体など）に限る
• キャッシュの汚染を防ぐため、常に一意の outDir を設定する

完全なパターンと例については、testing.md を参照してください。

このスキルを使用しない場合

• バグのトリアージ：代わりに triage スキルを使用する
• GitHub Actions の分析：analyze-github-action-logs スキルを使用する
• 簡単な質問：このスキルを読み込まず、直接質問する

Related Documentation

• Root: /AGENTS.md
• Root: /CONTRIBUTING.md
• Astro docs: https://docs.astro.build/
• Package: packages/astro/src/core/README.md
• Build plugins: packages/astro/src/core/build/plugins/README.md