JordanChoo/acfs-agent-skills

astro-site

この環境におけるAstro静的サイトプロジェクトの決定論理。目標：新しいサイトをastro-template系譜と一貫性を保ち、繰り返し発生するSEO/ビルドの落とし穴を回避すること。

トリガー

以下のいずれかの条件に該当する場合、このスキルを読み込みます：

• ファイル：astro.config.{mjs,ts,js}、src/content.config.ts、src/content/、*.astroファイル
• 依存関係：astro、@astrojs/mdx、@astrojs/sitemap、@astrojs/rss、@tailwindcss/vite、astro-custom-toc
• ユーザー言及：astro、content collection、sitemap、MDX、RSS、Tailwind v4、WP migration、redirect、getCollection、<Image>

標準スタック署名

この系譜のAstroプロジェクトは厳格なスタックを共有しています。先に確認してから作業を進めてください：

"astro": "^5.x"
"@astrojs/mdx", "@astrojs/sitemap", "@astrojs/rss"   # 常に含まれる
"@tailwindcss/vite", "tailwindcss": "^4.x"            # Viteプラグイン経由のTailwind v4（v3のPostCSSではない）
"astro-custom-toc"                                    # 通常含まれる
"zod": "^4.x"                                         # コンテンツスキーマ
"@astrojs/check"                                      # 型チェック

プロジェクトに@astrojs/cloudflare、@astrojs/netlify、@astrojs/vercel、@astrojs/nodeがある場合、それはサーバーレンダリングのAstroプロジェクトです。以下のルールのほとんどは引き続き適用されますが、まずastro.config.mjsのoutput:を確認してください。

標準の src/ レイアウト

src/
  components/         # .astro / .ts コンポーネント
  config/             # サイト設定（ナビ、ブランド、フッター）
  content/
    blog/
    services/         # または locations/、team/、projects/ など
    team/             # 著者、ブログから reference('team') で参照
  content.config.ts   # すべてのコレクションのZodスキーマ
  data/               # 静的データファイル (.ts/.json)
  layouts/            # ベース + ページタイプ別レイアウト
  pages/              # ルート
  styles/
  utils/
public/               # 静的アセット、robots.txt、favicon
prd/PRD.md            # プロダクト要件（テンプレートの慣例）

新しいコンテンツタイプを追加する場合、最初にsrc/content.config.tsにスキーマを追加し、その後ディレクトリと最初のエントリを追加してください。Astroのコンテンツレイヤーは、ディレクトリが存在するがスキーマがない場合、ビルドに失敗します。

---

プレイブック

コンテンツコレクションの追加

1. src/content.config.tsを編集 — loader: glob(...) と Zod スキーマを持つ defineCollection ブロックを追加します。
2. クロスリファレンスには reference('<other-collection>') を使用します（例：ブログ投稿 → チーム著者）。
3. pubDate には z.coerce.date() を使用し、frontmatterの文字列が正しくパースされるようにします。
4. オプションフィールドは .optional() で明示的にしてください — Astro v5は厳格で、必須フィールドが欠けているとビルドが失敗します。
5. スキーマ変更後は npm run check（= astro check）を実行します。ビルド前にスキーマとデータの不一致を検出します。
6. 参考：astro-template/src/content.config.ts が標準的な例です（blog + team、reference() 使用）。

ページまたはルートの追加

1. 新しいページ → src/pages/<route>.astro または src/pages/<route>/index.astro。Astroのルーティングはファイルシステムベースです。
2. ページをサイトマップから除外する場合（サンキューページ、404、ページネーションの重複）、下記「サイトマップ規律」に従い、astro.config.mjs の sitemap() フィルターを更新します。
3. パスを置き換えたり移動する場合は、astro.config.mjs にリダイレクトを追加します（redirects: { '/old': '/new' }）。404に頼らないでください。
4. 動的ルート（[slug].astro）の場合、getStaticPaths() を実装し、getCollection('<name>') を介してコレクションからデータを取得します。

サイトマップ規律（繰り返し発生する落とし穴）

この系譜のすべてのプロジェクトはサイトマップをフィルタリングします。パターン：

sitemap({
  filter: (page) => {
    const path = new URL(page).pathname;
    // ページネーションの重複ページ
    if (/\/blog\/\d+\/$/.test(path)) return false;
    if (/\/blog\/tags\/[^/]+\/\d+\/$/.test(path)) return false;
    if (/\/blog\/categories\/[^/]+\/\d+\/$/.test(path)) return false;
    // Noindexページ
    if (path === '/thank-you/') return false;
    if (path === '/404/') return false;
    return true;
  },
  changefreq: 'weekly',
  priority: 0.7,
  lastmod: new Date(),
})

ページネーションされたルート（タグ、カテゴリ、年別アーカイブ）を追加する場合は、同時にフィルターを拡張してください。そうしないと、サイトマップが /blog/2/、/blog/3/ などで埋め尽くされ、SEOが低下します。

WordPress移行（繰り返し発生するユースケース）

この系譜の2つのプロジェクト（arp-astro、gkn-static）がWordPressから移行しました。パターン：

1. リダイレクト — すべての古いWP URLには、astro.config.mjs に redirects: エントリが必要です。一般的なWPパスパターン：/feed、/feed/atom、/?p=N、/category/...、/tag/...、/<slug>（WP書き換えルール）、および任意の /service/... や /location/... の単一パス。
2. 末尾スラッシュ — WPサイトが末尾スラッシュを使用していた場合、trailingSlash: 'always' に設定し、正規URLを安定させます。末尾スラッシュの不一致は、インバウンドリンクと検索ランキングを壊します。
3. 移行スクリプト — gkn-static には、npm run migrate:all で実行される scripts/migrate/{parse,transform,extract,media,redirects,validate}.ts があります。新しいWP移行を開始する場合は、そのスクリプト構造をコピーし、その場しのぎの方法は避けてください。
4. 起動前に検証：古いサイトのクロールを実行し、新しいサイトマップと比較し、すべての古いURLが解決されるかリダイレクトされることを確認します。

Tailwind v4 の注意点（この系譜はv4）

• プラグインは @tailwindcss/vite であり、v3のPostCSSプラグインではありません。postcss.config.js を追加しないでください。
• 設定は tailwind.config.js ではなく、CSS内の @theme { ... } ブロックを介して行います。一部のエージェントは反射的にv3スタイルの設定ファイルを追加しようとしますが、避けてください。
• @tailwindcss/typography はv4でも動作しますが、設定方法が異なります。追加する前に既存の src/styles/ を確認してください。
• クラス名はほとんどv3から引き継がれていますが、一部のユーティリティ名が変更されています（例：shadowスケール）。v3の例を移植する場合は、v4のドキュメントで確認してください。

画像

Astro v5の astro:assets が適切なツールです — import { Image } from 'astro:assets' でインポートし、文字列パスではなくインポートしたアセットを渡します。コレクションのfrontmatter画像には、Zodスキーマで image() を使用します：

schema: ({ image }) => z.object({
  cover: image(),
  ...
})

これにより、width/height/format が自動的に提供され、ビルドパイプラインが最適化を行います。

ビルド、チェック、テスト

• npm run check（= astro check）— .astro ファイルとコンテンツスキーマの型チェック。すべてのPRの前に実行します。
• npm run build — 厳格で、壊れたコレクション参照、必須frontmatterの欠落、MDX内の壊れたリンクで失敗します。
• npm run test — Vitest + happy-dom。主にユーティリティの単体テストであり、ページレンダリングではありません。
• npm run dev — HMR。コンテンツスキーマの変更は、HMRだけでなく、完全な再起動が必要になる場合があります。

ビーズ（課題追跡）— バージョンに注意

これらのプロジェクトは、br（beads_rust）ではなく bd（レガシービーズ）を使用します。ワークフロードキュメントやコマンドを更新する場合、bd-to-br-migration スキルが適用されますが、明示的に依頼されない限り移行しないでください。プロジェクトの他のツールが bd を期待しているためです。

---

危険信号 — 作業を止めて確認

• tailwind.config.js または postcss.config.js の追加 — これはTailwind v4です。CSS内で設定してください。
• src/content/ の下に、src/content.config.ts に対応する defineCollection がない新しいコンテンツディレクトリ。
• サイトマップフィルターの更新なしでの新しいページネーションルート。
• リダイレクトを追加せずにページを置き換え/リネーム。
• astro:assets を使用すべき場所でのベア文字列画像パス（<img src="/photos/foo.jpg">） — 最適化が失われます。
• アダプターとそれに対応するデプロイ計画なしでの output: の static から server への切り替え。
• SSR用のデプロイストーリーがないプロジェクトへのサーバーサイド機能（APIルート、動的SSR）の追加。

---

未知のAstroリポジトリで最初に読むべきもの

1. astro.config.mjs — サイトURL、インテグレーション、リダイレクト、サイトマップフィルター、出力モード
2. src/content.config.ts — すべてのコレクションスキーマ。マークダウンフロントマターを編集する前に確認。
3. package.json のスクリプト — dev/build/check/test が慣例的な名前であることを確認。
4. src/layouts/ — ベースレイアウトがすべてのページをラップ。SEO/メタ情報はここにあります。
5. src/config/ — サイト全体の設定（ナビ、フッター、ブランド）
6. prd/PRD.md が存在する場合 — この特定のサイトのプロダクト要件。
7. CLAUDE.md / AGENTS.md — プロジェクト固有のオーバーライド。