ビルド成功はサイト完成ではありません：検証が証明できるのは、その範囲だけです

「ビルドが通りました」は必要な報告ですが、「サイトが完成しました」と同じ意味ではありません。

ビルドで分かるのは、現在のコードから出力を生成できるかどうかです。公開 URL がすべて正しいか、下書きが漏れていないか、ボタンが目的に合っているか、スマートフォンの読む順序が快適かまでは確認できません。サイトオーナーに代わって、この版のビジュアルの方向性を決めることもできません。ここでの判断は、引き渡しでは完成を複数の証拠に分け、各ツールの結果は、そのツールが実際に確認したことだけの根拠にするというものです。

「完成」を別々の問いに分けます

コンテンツサイトには、少なくとも次のような異なる完成条件があります。

問い	必要な証拠
Astro がコードを理解できるか	型チェック、Astro diagnostics
コードのスタイルやルールに違反していないか	lint
サイトの静的出力を生成できるか	ビルド
出力された固定ページと metadata が正しいか	静的出力の検証
下書き、日付、記事ルートがコンテンツの契約を守っているか	記事テスト、記事出力の検証
利用者が実際に操作できるか	ブラウザー操作、キーボードとエラー経路の確認
この版が意図した読み心地になっているか	サイトオーナーによるビジュアルと内容の受け入れ確認
公開してよいか	明示的な公開許可と frontmatter の状態

これらは互いに関係していますが、一つのコマンドでほかの問いまで答えることはできません。すべてを「npm run build が成功した」にまとめると、未確認の部分が見えなくなるだけです。

check では、まず型と Astro ファイルを確認します

npm run check は Astro のチェック処理を使い、Content Collection を読み込み、型を生成し、Astro ファイルの診断を行います。

次の確認に適しています。

• コンポーネントの props が現在の型に合っているか。
• Content Collection の frontmatter が schema を満たしているか。
• Astro template と TypeScript に診断可能なエラーがないか。
• ルート、layout、データ読み込みの間で型が正しくつながっているか。

一方、次のことは分かりません。

• 読者が記事の内容を理解できるか。
• あるリンクを主なナビゲーションに置くべきか。
• 利用者がモバイル版の段落幅を好むか。
• 型チェックを通ったコンポーネントが、実際にページで使われているか。

型チェックは、コンテンツとコードを接続するための条件です。内容の質やプロダクトの方向性の代わりにはなりません。

lint が確認するのはルールであり、意図ではありません

npm run lint は ESLint を実行します。未使用の変数、一部の構文上の問題、プロジェクトで明示的に禁止した書き方など、現在の設定が対象にするルール違反を検出できます。

lint を通るという結果は、そのルールにコードが従っていることを示します。ルール自体が、すべての使いやすさの問題を網羅しているとは限りません。たとえば、lint を完全に通るボタンでも、置く場所が間違っていることはあります。文として正しい説明でも、下書き段階の機能を完成済みと伝えてしまうことがあります。

そのため、lint の結果は「ルールのチェックを通りました」と報告し、「機能が正しい」「利用体験が完成した」まで意味を広げないようにします。

build ではサイトを生成できるか確認します

Astro build は、現在の routes、Content Collection、コンポーネントから静的ファイルを生成します。ビルド処理が最後まで進むことを確認でき、ルートやコンテンツデータが不正な場合にはエラーを表面化させられます。

ただし、ビルドの範囲にも限界があります。

• 参照されていないコンポーネントが使われている証拠にはなりません。
• サイトオーナーに代わってアニメーションのテンポを確認しません。
• sitemap に公開すべきでない URL が含まれているかを、自動で判断しません。
• すべての操作がキーボードやエラー状態でも使えることを証明しません。
• 本番ホストの rewrite、404、キャッシュの挙動を証明しません。

ビルドは出力パイプラインに必要な条件ですが、サイト全体の受け入れ確認ではありません。

静的出力の検証では実際の HTML を読み戻します

原稿で説明している静的出力の検証は、ビルドの exit code だけを見るものではありません。dist/ のファイルを読み、固定ページ、互換ルート、404 を一つずつ確認します。

たとえば、次の条件を確認します。

• 各固定ページに正しい lang があること。
• ページに h1 が一つだけあること。
• 想定したページに canonical、description、Open Graph metadata、hreflang があること。
• 公開ページが空の SPA shell ではなく、想定外の hydrated framework のマーカーもないこと。
• 旧 /work ルートを読める入口として残しつつ、canonical が /about/work を指すこと。
• 404 が noindex であり、自分をホームページとして宣言していないこと。
• HTML と CSS が参照するローカルリソースが実在すること。

この検証によって、「元のコンポーネントは妥当に見える」から「ビルド後の文書が契約を満たしている」へと根拠が変わります。ブラウザーでの受け入れ確認とは別ですが、少なくとも読者が実際に受け取るファイルを確認しています。

記事出力の検証では公開対象の集合を確認します

記事システムには、どの記事を正式出力に含め、どの記事をプレビューだけに残すかという、別の問題があります。

原稿で説明している記事出力の検証は、すべての Markdown を読み、schema に沿って frontmatter を解析して、公開対象の記事集合を算出します。次のことを確認します。

• 公開済みの記事に、それぞれ正式な記事ページがあること。
• 公開済みの記事に canonical と sitemap のリンクがあること。
• 下書き、公開日がない記事、公開日がまだ来ていない記事が、正式な HTML、sitemap、ホームページのカードに出ないこと。
• 英語または日本語に公開記事がない場合、その言語の一覧とホームページが実態に合った空の状態になること。これは条件付きの検証項目であり、翻訳が存在する現在も両言語が空だという意味ではありません。
• ホームページと正式な記事一覧が、同じ公開データを使っていること。

これは一般的なビルドとは異なります。ビルドがサイトを正常に生成しても、記事データと dist/ を読み戻さなければ、コンテンツの状態が公開境界を越えていないか確認できません。

ブラウザーでの確認と主観的な受け入れ確認も残します

静的ファイルが正しくても、ブラウザー上の操作がすべて完成しているとは限りません。実際に次のことを確認する必要があります。

• 言語切り替えが、対応するページへ本当に移動するか。
• 記事の目次とページ内アンカーを使えるか。
• アバターの dialog を Escape で閉じられ、フォーカスが呼び出し元のボタンに戻るか。
• 非表示のタブ、reduced-motion の設定、ページから離れる際に、背景アニメーションがルールどおり停止またはクリーンアップされるか。
• JavaScript が動かない場合でも、記事、制作実績、主なリンクを読めるか。
• モバイル版の読む順序、ボタンの折り返し、表、長いタイトルに調整が必要か。

一部はブラウザーツールで確認できますが、別の部分はサイトオーナーが実際に見る必要があります。特に「この順序でよいか」「この余白は心地よいか」「視覚的な強調が別の場所に向いていないか」といった判断は、ビルドでは代替できません。

公開するかどうかは別の判断です

内容が工程上のチェックを通っていても、それだけで記事の公開が許可されたことにはなりません。一般的な下書きの運用では、次の状態を維持します。

publishedAt: ''
draft: true

記事の内容、公開範囲、画面上の読みやすさを確認してから、実際の公開日を設定し、正式な状態に切り替えます。「書き終わった」「サイトに組み込んだ」「工程上のチェックを通った」「公開してよい」は、それぞれ別の出来事です。上の YAML は運用の例であり、この翻訳記事の frontmatter を示すものではありません。

引き渡しの説明が「すべて完成しました」だけでは、読者や協力者は、まだ人の判断が必要な部分を把握できません。次のように分けるほうが、確かな報告になります。

変更済み：実際に変わった内容とコード
検証済み：通過したコマンドと成果物の検証
受け入れ確認待ち：人が見る必要のあるビジュアル、操作、内容の判断
未公開：現在も下書きか、公開許可がまだないか

結果に合った言い方を使います

次のようには言えます。

• 「npm run check で診断エラーはありませんでした。」
• 「静的出力の検証で、固定ページに canonical と実際の HTML があることを確認しました。」
• 「記事出力の検証で、下書きが正式出力に漏れていないことを確認しました。」
• 「記事は下書きのままで、公開許可はまだ得ていません。」

これらの結果だけから、次のようには言えません。

• 「だから利用者は必ず気に入ります。」
• 「だからすべての端末で問題ありません。」
• 「だから SEO は必ず改善します。」
• 「だから本番環境もローカルと必ず同じように動きます。」

これは必要以上に慎重になるためではありません。結論の強さを、証拠の範囲に合わせるためです。ツールは多くのことをしていますが、確認していないことも報告に残す必要があります。

自分の完成チェックリストを作ります

ページ、内容、操作を同時に変更するタスクでは、次の順序で整理できます。

1. データと要件の境界を確認します。
2. 型チェックと lint を実行し、コード上の問題を解消します。
3. ビルドを実行し、出力を生成できることを確認します。
4. 正式な HTML、sitemap、コンテンツ集合を読み戻し、公開境界を確認します。
5. ブラウザーで実際のリンク、キーボード操作、エラー経路を試します。
6. サイトオーナーがビジュアル、読む順序、公開範囲を確認します。
7. 最後に、下書きを正式公開へ切り替えるか決めます。

この順序は、毎回の変更を大掛かりな手続きにするものではありません。異なるリスクを適切な検証に割り当て、一度ビルドが通っただけで未確認の部分まで覆い隠さないためのものです。

この記録の範囲

この記事は、原稿が記録した Astro 静的サイトのコマンド、出力検証、コンテンツ公開の境界を整理しています。各検証がどの結論の根拠になるかを説明するものであり、これらのコマンドによって性能、検索順位、事業上の成果、ユーザー調査の結果、本番ホストの挙動が証明されたとは主張しません。