静的サイトレビュー
ゴール
ユーザーがさらに編集したり、公開したり、完成したものとして扱う前に、静的ウェブサイトの出力を検証します。
このスキルは、生成されたHTML/CSS/JSサイトの品質ゲートです。テーマの選択、参照の再作成、コンテンツの移行、サイトのデプロイは行いません。生成されたフォルダが実際の静的サイトのように動作することを確認します。
コアチェック:
- ソースファイルが有効なUTF-8であり、人間が読み取り可能であること。
- ローカルリンク、スクリプト、スタイルシート、画像、その他のアセットが解決されること。
- サイトローカルのリンクとアセットは、デフォルトでルート絶対パス(例:
/assets/style.css)ではなく、ページ相対パスを使用すること。 - 出力は、ユーザーが明示的にサーバー専用の動作を許可しない限り、手動プレビューのために
index.htmlから直接開けること。 - 生成されたページが期待されるページタイプをカバーしていること。
- サイトがローカルHTTP上で実際のブラウザにレンダリングされること。
- デスクトップとモバイルのレイアウトが使用可能であること。
- コンソールエラー、壊れたインタラクション、残っているプレースホルダ、コピー元ソース固有のテキストが報告または修正されること。
契約
入力:
site/、dist/、out/、public/、docs/、またはリポジトリルートなどの静的サイトルート。- オプションの期待されるページスコープ、ローカルプレビューURL、
EDITING.md、参照URL/スクリーンショット、禁止するソース固有文字列。
出力:
- 重要度順に並べられた所見、または検証がビルド/修正タスクの一部である場合は修正。
- 静的監査結果、チェックしたブラウザページ/ビューポート、および変更されたファイル(ある場合)。
- 公開または引き渡し準備ができているかの明確な合格/不合格状態。
境界:
- テーマの選択、ウェブサイトの再作成、コンテンツの移行、アイデンティティのカスタマイズ、またはデプロイを行わないこと。
- 視覚的な問題がユーザビリティを妨げ、ユーザーが修正を依頼した場合を除き、検証中にサイトを再設計しないこと。
--allow-root-absoluteが意図的に使用され、その制限が明記されている場合を除き、ルート絶対パスのサイトローカルパスを承認しないこと。
成功ゲート:
- ブロッカーが残っていないこと:壊れたプライマリナビゲーション、必須ページタイプの欠落、読み取れないソースエンコーディング、ローカルアセットの失敗、コンソールクラッシュ、モバイルの使用不可、または偶発的なルート絶対パスの問題。
- 警告が修正、文書化、またはユーザーに受け入れられていること。
ゲート失敗時:
- 検証がビルドの一部である場合は、簡単なローカルの問題を修正する。
- より大きな失敗は、失敗した箇所に応じて、
make-personal-site、copy-website-style、personalize-site、add-blog-posts、またはedit-site-partにルーティングする。 - 決定論的監査と影響を受けるブラウザチェックを再実行する。
使用タイミング
このスキルは以下で使用します:
make-personal-siteがオリジナルの静的個人サイトを作成または再設計した後。copy-website-styleがターゲットサイトのスタイルを静的ファイルとして再現した後。- ユーザーが既存の静的出力フォルダを指し示し、それが十分に良いかどうかを尋ねてきたとき。
- ユーザーが公開前に静的サイトのチェック、検証、QA、検査、監査、またはテストを依頼したとき。
ユーザーがフレームワークのソースプロジェクトを提供した場合、可能であれば既にビルドされた静的出力フォルダを検証してください。ユーザーが明示的に依頼しない限り、ここでフレームワークのビルドワークフローを導入しないでください。
入力
利用可能な入力を使用します:
- 静的サイトルートフォルダ(例:
site/、dist/、out/、public/)。 - ローカルプレビューURL(サーバーが既に実行中の場合)。
- 期待されるページスコープ:ホームページのみ、完全な個人サイト、ブログ、ポートフォリオ、ノート、リンク、スタイル再現など。
EDITING.md、ページマップ、または別のスキルによって生成された引き継ぎノート。- 参照URLまたはスクリーンショット(スタイル再現を検証する場合)。
- 元の著者名、ドメイン、メールアドレス、分析ID、または古いプレースホルダテキストなど、残存してはならない既知の文字列。
サイトルートが不明な場合は、近くのフォルダを検査し、index.html と静的アセットを含むフォルダを選択します。
ワークフロー
- 静的サイトルートと期待されるページスコープを特定する。
EDITING.mdを読むか、HTMLファイルとナビゲーションリンクからページマップを推測する。- 決定論的ファイル監査スクリプトを実行する。
- 静的ルート用のローカルHTTPサーバーを起動または再利用する。
- 実際のブラウザでデスクトップおよびモバイル幅でサイトを検証する。
- 生成されたすべてのページタイプについて、少なくとも1つの代表的なページを開く。
- ナビゲーション、テーマ切り替え、検索/フィルター、コピーボタン、モバイルメニュー、ページネーションなどのコアインタラクションをテストする。
- ブラウザコンソールエラーと欠落しているネットワークリソースをチェックする。
- 相対パスの互換性、プレースホルダ、UTF-8の可読性、ソース固有の残留テキストを監査する。
- ユーザーがビルドの一部として検証を依頼した場合は簡単な欠陥を修正し、それ以外の場合は最初に所見を報告する。
決定論的ファイル監査
ブラウザ検証の前にバンドルされたスクリプトを使用します:
python scripts/static_site_check.py <site-root>
スタイル再現やコピーサイトのクリーンアップの場合は、禁止するソース固有文字列を渡します:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
スクリプトは以下をチェックします:
- HTML、CSS、JS、JSON、Markdown、SVG、XML、テキストファイルのUTF-8デコード。
- 疑わしい文字化けと置換文字。
- HTMLファイル内の
<meta charset="utf-8">の欠落。 - 壊れたローカル
href、src、srcset、poster、action、data-src参照。 - 明示的に許可されていない場合の
/assets/...、/posts/...、/data/...、/images/...などのルート絶対サイトローカル参照。 - CSS
url(...)アセット参照(欠落またはルート絶対のローカルURLを含む)。 - HTML、JavaScript、JSONデータ内の一般的なルート絶対サイトローカル文字列。
- サイトルートをエスケープするリンク。
- 一般的なプレースホルダ文字列。
--forbidで指定された禁止文字列。.env、秘密鍵、認証情報ファイル、ローカルサービスアカウントアーティファクトなどのプライバシーに関わるデプロイルートファイル。- シークレットのような割り当て、既知のトークンパターン、秘密鍵ブロック、ソーステキスト内のローカル絶対ファイルシステムパス。
- 公開すべきでない一時ファイル、ログ、バックアップ、OSアーティファクト。
- HTMLページ数と推測されるページタイプ。
EDITING.mdが存在するかどうか。
ファイル監査はベンダーファイルのUTF-8可読性を検証する必要がありますが、サードパーティのミニファイドベンダーバンドル内のプレースホルダのような単語をサイトのプレースホルダコンテンツとして扱うべきではありません。
ユーザーが簡単な探索的レビューのみを希望する場合を除き、スクリプトエラーをブロッカーとして扱います。警告は手動で検査する項目として扱います。
サイトが意図的にカスタムドメインルート下でルート相対パスを必要とするように設計されている場合は、--allow-root-absolute を指定してスクリプトを実行し、直接 file:// で開くこととGitHubプロジェクトサブパスへのデプロイが保証されないことを明記してください。ユーザーがそのトレードオフを明示的に受け入れない限り、生成されたプレーンな静的個人サイトにはこの例外を使用しないでください。
パス互換性
生成されたプレーンな静的サイトは、3つの一般的なコンテキストで動作する必要があります:
- 簡単な手動プレビューのためにファイルシステムから
index.htmlを直接開く。 - ブラウザ自動化とコンソール/ネットワークチェックのためにフォルダをローカルHTTPで提供する。
- ドメインルートまたはサブパスからサイトを提供する可能性のある静的ホストにデプロイする。
デフォルトルール:
- サイトローカルのリンクとアセットにはページ相対パスを使用します。
- ルートページからは、
assets/style.css、posts/example.html、about.htmlを使用します。 - ネストされたページからは、
../assets/style.css、../blog.html、および必要に応じて兄弟相対リンクを使用します。 - デフォルトでは、内部ナビゲーションに
/assets/style.css、/posts/example.html、/data/posts.json、/images/foo.png、または/を使用しないでください。
また、JavaScript 生成リンク、検索結果、タグフィルター、コピーボタン、動的カード、RSS/サイトマップ参照、画像カバー、CSS url(...) 値、ファビコン、フォント、KaTeX/math ベンダーアセットもチェックします。後にJavaScriptがルート絶対パスを挿入する場合、静的なHTML属性が相対的であるだけでは十分ではありません。
ルート絶対パスは、ユーザーが明示的にサーバールート専用デプロイ(カスタムドメインルートなど)を希望し、直接ファイルを開くことやGitHubプロジェクトPagesのサブパスが壊れる可能性があることを理解している場合にのみ許容されます。
ブラウザ検証
最終納品前に実際のブラウザを使用します。ローカルファイルは file:// ではなくHTTPで提供します:
python -m http.server 8000
次に開きます:
http://127.0.0.1:8000/
ローカルHTTPターゲットの検証パスとして、実際に利用可能なインタラクティブブラウザツールを最初の選択肢として使用します。「利用可能」とは、ツールが現在のターンの呼び出し可能ツールリストに公開されていることを意味し、スキル、プラグインリスト、またはシステム説明に単に言及されているだけではありません。Codexでは、これはユーザーまたはクライアントがそれをターンにルーティングした場合のBrowser/アプリ内ブラウザプラグインである可能性があります。他のエージェントでは、同等の可視ブラウザ、ブラウザ使用ツール、またはdevtoolsバックアップのブラウザである可能性があります。ローカルURLを開き、デスクトップ/モバイルビューポートを検査し、インタラクションを実行し、可視のコンソール/ネットワーク問題をチェックする必要があります。
現在のターンでインタラクティブブラウザツールが公開されていない場合、ブラウザパスが行われたふりをしないでください。検証がそれに依存する場合、ユーザーにクライアントのルーティング方法を使用してブラウザツールを有効にするか呼び出すよう依頼してください。Codexの場合、それは @browser を明示的に言及するリクエストを送信することを意味する可能性があります。ユーザーがルーティングを変更しないか、クライアントにそのようなツールがない場合、Playwright、スクリーンショット、静的監査、またはシェルチェックにフォールバックし、これがフォールバックであり、完全なインタラクティブブラウザ検証ではないことを明記します。
インタラクティブブラウザツールが実際に呼び出し可能な場合、デフォルトでPlaywright、ヘッドレス専用スクリーンショットスクリプト、シェルで開かれたブラウザウィンドウ、または静的スクリーンショット生成を使用しないでください。スクリーンショットは有用な証拠ですが、インタラクティブブラウザパスを置き換えるものではありません。インタラクティブブラウザツールが呼び出し可能でない場合、ユーザーが明示的にPlaywrightを要求した場合、または繰り返し可能なスクリプト化された回帰テストが特に必要である場合にのみ、Playwrightをフォールバックとして使用します。
Chrome自動化は、タスクにユーザーのChromeプロファイル、既存のタブ、拡張機能、認証されたリモートページ、またはChrome固有の動作が必要な場合にのみ使用します。file:// ページにChrome拡張機能の自動化を依存しないでください。代わりにローカルHTTPを使用します。
自動化はローカルHTTPを使用する必要がありますが、生成されたソースは、相対パスを使用し、コアコンテンツに対してサーバー専用の前提を避けることにより、依然として直接開く互換性がある必要があります。アプリ/ブラウザが簡単な file:// 簡易チェックを許可する場合、ルート index.html を直接開き、CSS、画像、ナビゲーション、代表的なサブページが壊れていないことを確認します。ファイル自動化が利用できない場合は、決定論的ルート絶対パス監査に依存し、直接開くことが手動または自動でチェックされたかどうかを言及します。
ブラウザチェック:
- デスクトップ最初の画面:構成、間隔、タイポグラフィ、可視ナビゲーション、および明らかなオーバーフロー。
- モバイル最初の画面:ナビゲーション動作、テキストラッピング、コンテンツ優先順位、および水平オーバーフロー。
- 内部ナビゲーション:すべてのプライマリナビゲーションリンクがレンダリングされる。
- ページタイプカバレッジ:生成されたすべてのページタイプに対して少なくとも1つのブラウザパスまたはスクリーンショット。
- インタラクションカバレッジ:テーマ切り替え、メニュー、フィルター、検索、コピーボタン、ページネーション、アコーディオン、タブ、ホバー/クリック状態、またはその他の可視コントロール。
- コンソール状態:明らかなJavaScriptエラーがないこと。
- ネットワーク状態:欠落しているローカルCSS、JS、画像、またはフォントアセットがないこと。
- アクセシビリティの基本:インタラクティブコントロールのフォーカス可視性、読みやすいコントラスト、意味のあるページタイトル、および実用的な場合の空でない画像代替テキスト。
小規模サイトの場合は、生成されたすべてのページをクリックします。大規模サイトの場合は、すべてのページタイプと EDITING.md で言及されているルートをサンプリングします。
ページタイプカバレッジ
ファイル名、ルート、可視ナビゲーション、および EDITING.md からページタイプを推測します。
典型的なページタイプ:
- ホーム
- アバウトまたはプロフィール
- ブログ、アーカイブ、カテゴリ、タグ、ノート、またはリストページ
- 記事または詳細ページ
- プロジェクト、ポートフォリオ、出版物、または仕事ページ
- リンク、フレンズ、リソース、Now、Uses、ガーデン、検索、テーマ/設定、その他の特別なページ
生成されたサイトがブログであると主張しているが、記事/詳細ページがない場合は報告します。存在しないサブページへのナビゲーションがある場合は、ブロッカーとして報告します。
エンコーディングとソースの可読性
ブラウザのスクリーンショットだけでは不十分です。ソースファイルは将来のモデルや人間が読み取れる必要があります。
要件:
- HTMLファイルには
<meta charset="utf-8">を含める。 - 非ASCIIテキストはUTF-8として保存される。
- HTML、CSSコメント、JavaScript文字列、JSON/データファイル、SVGテキスト、および
EDITING.mdはソース形式で読み取り可能であること。 - 文字化け、置換文字、または偶発的なブラウザエンコーディング復旧がないこと。
ターミナルに文字化けが表示されるがブラウザは正しく見える場合、壊れていると判断する前にUTF-8認識リードで確認してください。ファイルコンテンツ自体に文字化けが含まれている場合は、別のエンコーディング変換を重ねるのではなく、クリーンなテキストから影響を受ける文字列を書き換えます。
プレースホルダと残留物の監査
生成されたサイトにまだ含まれていないかチェックします:
TODO、FIXME、lorem ipsum、placeholder、replace me、your name、example.com、またはサンプル/デモテキスト。- ダミーのメールアドレス、偽のソーシャルリンク、空のボタン、またはデッドなコールトゥアクション。
- スタイル再現における元サイトの著者名、ドメイン、記事タイトル、メールアドレス、分析ID、ソーシャルリンク、フレンドリンク、またはプライベートURL。
ユーザーがまだ意図的な編集可能マーカーとしてそれらを必要としている場合、プレースホルダを盲目的に削除しないでください。明確に報告するか、ユーザーが実際のコンテンツを提供した場合にのみ置き換えます。
プライバシーとローカル残留物
公開前にこれらをブロッカーとして扱います:
- デプロイ可能ルート内の
.env、.npmrc、.pypirc、秘密鍵ファイル、認証情報JSONファイル、サービスアカウントファイル、またはパスワードボールト/エクスポートファイル。 - HTML、CSS、JavaScript、JSON、Markdown、SVG、またはテキストファイル内のシークレットのような割り当て、アクセストークン、秘密鍵ブロック、またはAPIキー。
- 生成されたソース内の Windows ドライブパス、
file:///...、/Users/...、/home/...、/mnt/...などのローカル絶対ファイルシステムパス。
ログ、バックアップ、一時ファイル、OSメタデータは、プライベートコンテンツを公開しない限り警告として扱います。パッケージ化または公開の前に、デプロイ可能な出力からそれらを削除します。
修正ポリシー
ユーザーが「チェック」、「レビュー」、または「何が問題かを教えて」と依頼した場合は、最初に所見を報告し、広範な編集は避けます。
検証がビルドの一部である場合、またはユーザーが明示的に修正を依頼した場合(例:「これが正しいかチェックして、問題を修正して」)、次のルールに従います:
- すべてのブロッカーを自動的に修正します。修正項目を変更されたファイルのリストに記録します。
- ブロッカーでない簡単な問題(軽微なHTML調整、欠落したメタタグ、クリーンアップされたプレースホルダ、調整されたパス)は、それらが求められており、かつ潜在的に破壊的でない場合に修正します。
- ページのスタイルやコンテンツを変更する修正は、影響を受けるページタイプの新しいブラウザスクリーンショットを撮り、変更を検証します。
- 修正が複数のページにわたる場合、または明らかに別のスキル(例:
copy-website-style、add-blog-posts)の目的の範囲内にある場合は、そのスキルにルーティングします。 - インタラクティブブラウザパスとファイル監査の両方を再実行します。