Claude Codeで実践するJavaScript SEO：テンプレートを触る前に証拠フォルダを作る

JavaScript SEO で本当に危険なのは、チェックリストを実行することではありません。もっと危険なのは、もっともらしいチェック項目を根拠に、複数ページで共有されているテンプレートを変更してしまうことです。カテゴリページが自分のブラウザでは正常に見えていても、リンクがクリックハンドラーに依存していたり、有用なコンテンツの表示が遅れたり、canonical と HTTP レスポンスの挙動が食い違ったりすることがあります。誤った「SEO 修正」は、ナビゲーション、計測、アクセシビリティ、さらにはそのコンポーネントを使うすべてのページを壊しかねません。

Claude Code が最も役立つのは、実際にページで観測した現象を、原因になり得る最小のコード経路、レビュー可能な diff、そしてテストへ結び付ける場面です。フレームワークを書き換えたり、いきなりパッチをデプロイしたりするところから始めるべきではありません。

この手順で完成するもの： リポジトリ内の証拠フォルダ、ローカル調査のルール、ページ上の一つの症状から関連しそうなファイルへの対応図、責任者が承認した実装ブリーフ、そしてテスト済みの変更記録です。ここでいう「完了」は、Google がそのページを再クロールしたことや、検索順位が上がったことを意味しません。

第1部：リポジトリを開く前にJavaScript SEOを理解する

ページがJavaScriptに依存すると何が変わるか

Web サーバーは URL へのアクセスにレスポンスを返します。そのレスポンスに主要コンテンツがすでに含まれている場合もあれば、ブラウザにスクリプトの実行と追加データの取得を求める外枠だけが含まれている場合もあります。ブラウザはその後、最終的なページ状態を組み立てます。

検索システムも URL を発見し、レスポンスを取得し、許可されたリソースを処理し、出来上がったページを理解する必要があります。現代的な JavaScript を使っているだけで SEO の問題になるわけではありません。問題は、重要な工程が不安定なとき、またはページの各層が異なる説明をしているときに発生します。

初心者には、次のモデルが役立ちます。

URL が発見される
  -> サーバーレスポンスを受信する
  -> HTML とリソースが処理される
  -> JavaScript とデータリクエストが完了する
  -> コンテンツ、リンク、ページシグナルが解釈される
  -> 検索システムが URL をインデックスするか、どう扱うかを判断する

矢印のどこでも問題は起こり得ます。そして、リポジトリに含まれる証拠はその一部にすぎません。コードを読めば、コンポーネントが意図上どう動くかは分かります。しかし、それだけでは Google がどの URL をインデックスしたか、昨日の本番リクエストが失敗したか、特定の端末で利用者が何を経験したかまでは分かりません。

「JavaScript」という一つの問題ではなく、六つのページ挙動を確認する

1. URLが意図したステータスを返す

正常なページは通常 200 を返します。削除済みページは、意味のある not found または gone の状態を伝えるべきです。リダイレクトは意図した最終 URL に到達する必要があります。クライアント側リダイレクトは遅くなることがあり、HTTP 層なら明確に見える間違いを隠す場合もあります。

2. 主要コンテンツを利用できる

ページの目的を決める本文や項目が、該当するレスポンスまたはレンダリング後の状態に現れる必要があります。コンテンツの表示にスクリプト、データリクエスト、スクロール、クリック、ログインなどの条件が必要かを記録してください。ソース HTML にないという事実は観測結果であり、そのページがインデックス不可能だと自動的に決める判定ではありません。

3. 重要な到達先が実リンクになっている

検索システムは一般に標準的なリンクから到達先を発見します。onClick、ボタン、フラグメントだけで移動するカードは見た目上は動いても、URL への経路としては弱くなる可能性があります。修正方法は実リンクの追加かもしれませんが、キーボード操作、アクセス解析、スタイル、アプリケーションのルーティングを維持しなければなりません。

4. canonical、robots、サイトマップのシグナルが一致している

リクエスト URL、canonical の指定先、robots 指示、内部リンク、サイトマップ登録が、同じ優先ページを示しているか確認します。canonical はヒントです。整理された URL 処理の代わりにはならず、無関係なページを指定してはいけません。

5. 遅延読み込みと無限スクロールに到達可能な状態がある

遅延読み込みはパフォーマンスを改善できますが、重要なコンテンツを任意の操作に依存させるべきではありません。無限スクロールでは通常、安定したページネーション URL、またはより深い項目へ到達できる別のクロール可能な経路を用意します。正しい実装はサイトごとに異なるため、変更を提案する前に既存のルーティングとデータモデルを確認してください。

6. メタデータと構造化データが表示内容に合っている

title、canonical、robots 指示、構造化データが JavaScript 実行後に生成される場合があります。それらは画面に見える内容と正確に一致していなければなりません。構造化データはページを解釈しやすくしますが、リッチリザルトや検索順位を保証するものではありません。

四種類の証拠を分ける

リポジトリエージェントを使うとき、この分離が重要です。Claude Code はコンポーネントの追跡に優れていますが、コードに近い位置で調査するほど、もっともらしい仕組みを確認済みの原因として扱いたくなるからです。

証拠に基づく症状を一つ書く

「Google は当社サイトをレンダリングできない」という文から始めてはいけません。その文には、まだ証明していない結論が含まれています。もっと範囲を狭めて書きます。

提供されたカテゴリページの記録では、商品名はレンダリング後に表示される一方、レンダリング済み DOM の商品カードに標準的な到達先リンクがありません。検索エンジンでのインデックス状態は不明です。

これなら Claude Code が追跡できる具体的な対象になります。また、調査範囲をアプリケーション全体のレンダリング判断ではなく、カテゴリカードとナビゲーションを担当するコードに限定できます。

第2部：証拠からレビュー済みdiffへ進むClaude Codeワークフローを作る

リポジトリに証拠フォルダを用意する

アプリケーションのソースコードとは別の場所を選びます。リポジトリに生成物やレポートの既存ルールがあれば、それに従ってください。規約がなければ、次のような構成から始められます。

reports/javascript-seo/
  collection-page-links/
    page-story.md
    response-notes.md
    rendered-notes.md
    search-evidence.md
    decision.md

このフォルダは四つの質問に答える必要があります。どのページを調査しているか、何を観測したか、何がまだ利用できないか、責任者が何を決めたかです。キャプチャやエクスポートをバージョン管理に入れるべきでない場合は、ignore 対象にします。

Cookie、API トークン、パスワード、顧客の非公開データ、制限のないエクスポートを絶対に入れないでください。どのツールに証拠を渡す場合でも、先に非公開 URL と個人情報をマスキングします。

責任者が実装ブリーフを承認するまで、読み取り専用の調査記録をソースコードから分けて保管します。

最初のプロンプト前にリポジトリルールを追加する

関連する CLAUDE.md や既存の .claude ルールなど、プロジェクトで使われている Claude Code のガイダンス場所に方針を置きます。すでに指示体系があるなら、二つ目を作らないでください。

## JavaScript SEO 調査ポリシー

- JavaScript SEO の作業は、読み取り専用の証拠収集から始める。
- 調査メモは、承認された証拠ディレクトリにだけ保存する。
- 観測事実、可能性のある仕組み、不明点、責任者の判断を分ける。
- 人間が指定した実装ブリーフを承認するまで、ソース、ルート、robots ルール、
  コンテンツ、CMS データ、デプロイファイル、CI を編集しない。
- Search Console、クロールログ、本番指標、インデックス状態は、権限のある
  エクスポートが提供されない限り「利用不可」と扱う。
- 秘密情報、Cookie、トークン、非公開 URL、顧客データを決して公開しない。
- 承認後は、対象を限定した最小の変更を行い、diff を提示し、合意済みテストを実行し、
  ロールバック条件を明記する。別途許可がない限りデプロイしない。

このルールは継続的な指針になりますが、それ自体が強制力のある制御層ではありません。プロジェクトに合ったリポジトリ権限、ブランチ保護、コマンド承認、コードレビューも併用してください。

ページストーリーを作る

リポジトリ調査をページ本来の目的に結び付けるため、短い page-story.md を追加します。

## ページ
https://example.com/collections/shoes

## 訪問者の目的
販売中の靴を比較し、商品ページを開く。

## 必須のページ要素
- カテゴリ見出し
- 商品名と価格
- 安定した商品の到達先
- 一貫した title、canonical、robots 指示、ステータス

## 観測された症状
提供されたレンダリング済み DOM には商品カードがあるが、標準的な商品リンクがない。

## 利用できる証拠
- 保存したレスポンスメモ
- レンダリング済み DOM の抜粋
- リポジトリのチェックアウト

## 利用できない証拠
- Google URL 検査
- サーバーログ
- 本番環境のフィールド指標

## 禁止する操作
調査中はソース編集、デプロイ、CMS 変更、URL 送信、外部への連絡を行わない。

ページストーリーがあれば、調査が一般的なコードレビューへ脱線するのを防げます。

Claude Codeに修正ではなくコードマップを依頼する

最初のプロンプトは読み取り専用モードで実行します。

JavaScript SEO の症状を一つ、読み取り専用モードで調査してください。

ページストーリー：reports/javascript-seo/collection-page-links/page-story.md
証拠フォルダ：reports/javascript-seo/collection-page-links/

リポジトリのガイダンスを読んでください。記載されたページと症状に関係する可能性が
あるコード経路だけを調査し、次を返してください。
1. 確認済み証拠の要約
2. 関連しそうなルート、テンプレート、コンポーネント、データ経路と、その理由
3. 不確実な点と不足データ
4. 最小の実装選択肢
5. 受け入れ確認項目とロールバック条件

ファイル編集、パッケージのインストール、デプロイ、書き込み可能な API の呼び出し、
Google がページをインデックスした／しなかったという断定は行わないでください。
調査ブリーフを書いたところで停止してください。

期待する出力： ページルートからテンプレート、コンポーネント、ナビゲーション挙動、関連テストまでの対応図です。品質確認： 候補ファイルがそれぞれ観測済みの症状に結び付いていることを確認します。復旧方法： フレームワーク移行を提案されたら、根拠を示したうえで、元に戻せる最小のテンプレート単位の選択肢を求めます。

開発者の視点でコードマップをレビューする

役立つコードマップは、データとマークアップがページへ届く経路を説明します。カテゴリカードの問題なら、次の項目を特定するはずです。

• ルートまたはページのエントリ
• カテゴリテンプレート
• カードコンポーネント
• 商品の到達先を作る関数
• ナビゲーションとアクセス解析のハンドラー
• 既存のコンポーネント、アクセシビリティ、E2E テスト

不明点も明示する必要があります。カードコンポーネントは href を受け取れるのにテンプレートが渡していないのかもしれません。ラッパーの都合でリンクの入れ子を避けている可能性もあります。あるいは、初期レスポンスでは利用できないデータから到達先を作っているのかもしれません。これらは別々の仕組みであり、必要な修正も異なります。

次の表でレビューします。

コードマップを実装ブリーフへ変換する

編集を始める前に、責任者が次の内容を含む文書を承認します。

Finding（発見事項）：[観測済みの条件を一つ]
Evidence（証拠）：[ファイルまたはキャプチャ]
Affected page family（影響するページ群）：[確認済みの範囲]
Candidate mechanism（候補となる仕組み）：[コード経路と不確実性]
Approved action（承認された対応）：[範囲を限定した変更を一つ]
Behavior to preserve（維持する挙動）：[ナビゲーション、アクセシビリティ、計測、スタイル、ルーティング]
Acceptance checks（受け入れ確認）：[一覧]
Rollback condition（ロールバック条件）：[一覧]
Owner（責任者）：[氏名または役割]
Status（状態）：APPROVED FOR LOCAL IMPLEMENTATION / NOT APPROVED

「クロール可能なリンクを追加する」だけではまだ広すぎます。より良い承認内容は、対象コンポーネントと意図する挙動を指定しつつ、コード責任者が既存アプリケーションに合う有効なマークアップを選べるようにします。

制約付きの編集を一度だけ実行する

承認後は、新しいプロンプトを開始します。広範な調査の文脈を、そのまま変更の許可として扱わないでください。

次の文書に記録された承認済み対応だけを実装してください。
reports/javascript-seo/collection-page-links/decision.md

編集前に、対象ファイル、維持する挙動、受け入れ確認項目、禁止操作、
ロールバック条件を言い直してください。

一貫性を保てる最小の変更を行ってください。無関係なコードのリファクタリング、
依存関係の変更、デプロイ設定の変更、CMS コンテンツの編集、デプロイは禁止です。

編集後：
- 完全な diff を提示する
- 承認済みのローカル確認だけを実行する
- 範囲を広げずに失敗を報告する
- 結果を decision.md に追記する

リポジトリの証拠が承認済みの仕組みと矛盾する場合は停止し、修正版ブリーフを返してください。

対象テンプレート、レビューゲート、プレビュー確認、ロールバック経路が明確になって初めて、引き継ぎは完了します。

説明を信じる前にdiffを確認する

変更の主要な記録として diff を読みます。次を確認してください。

• 想定したファイルだけが変更されている
• 必要なイベント処理とアクセス解析が維持されている
• 無効なインタラクティブ要素の入れ子を作っていない
• キーボード操作とスクリーンリーダーの挙動を維持している
• 安定した正しい到達先を生成している
• 関連テストを追加または更新している
• robots、canonical、リダイレクト、無関係なメタデータを密かに変えていない

いくら説明が流暢でも、広すぎる diff の代わりにはなりません。

訪問者とクローラーが出会う順序でページを検証する

ローカルと機能面の挙動

対象領域をビルドし、訪問者の目的をテストします。マウスとキーボードの両方で到達先を開けるか。クライアントルーティングは引き続き動くか。アクセス解析の前提は保たれているか。データ不足時にもコンポーネントが正しく動くかを確認します。

レスポンスシグナル

想定レスポンスまたはプレビューを確認します。ステータス、リダイレクトの挙動、title、canonical、robots 指示、レスポンスに含まれるべき主要コンテンツを調べます。「ページのソースを表示」にある内容だけで SEO 全体を判定しないでください。

レンダリング後の出力

最終 DOM に意図したコンテンツと通常の到達先があることを確認します。代表的なページに加え、空の状態、エラーまたはデータを利用できない状態も、該当する場合はテストします。

権限のある検索証拠

チームが URL 検査、クロール、ログ、Search Console の証拠を利用できるなら、日付とともに別記録として保存します。ローカルプレビューだけでは Google が再クロールまたはインデックスしたことを証明できません。検索データの変化には時間がかかる場合があり、どの実装も順位を保証しません。

ロールバックと記録

承認済みブリーフ、最終 diff、テスト出力、プレビュー参照、日付、責任者の判断を一緒に保管します。維持すべき挙動が失敗した場合、範囲が予想外に拡大した場合、またはプレビューがページストーリーと一致しなくなった場合は、合意した方法で元に戻します。

三つの調査例

安定リンクのないクリック可能なカード

観測： カードのテキストは見えるが、レンダリング記録では通常の到達先リンクではなく、コンテナにナビゲーションが設定されています。リポジトリでの問い： 主要な到達先を担当するコンポーネントはどれで、アクセス解析とアクセシビリティをどう維持しているか。最小変更の候補： 主要アクションに適切な標準リンクを追加する。決めつけてはいけないこと： カード内部のすべての場所をリンクの入れ子にする必要がある。

より深いURL経路がない無限スクロール

観測： スクロール後に追加項目が表示される一方、提供された証拠には後続グループへの安定したページ経路がありません。リポジトリでの問い： データ層は、URL に対応付けられるページまたはカーソルをすでに扱えるか。最小変更の候補： プログレッシブエンハンスメントを維持しながら、クロール可能なページネーションを公開する。決めつけてはいけないこと： インターフェース全体を置き換える必要がある。

クライアントレンダリングのnot foundページが200を返す

観測： 利用できない商品にはレンダリング後に「not found」が表示される一方、レスポンス記録は 200 です。リポジトリでの問い： ルートを利用できるかどうかはどこで判明し、サーバーまたはフレームワークが意味のあるステータスを返せるか。最小変更の候補： 適切なルート境界で欠落状態を扱う。決めつけてはいけないこと： 表示文言を変えればレスポンス問題が解決する。

よくある間違い

Claude Codeにサイト全体の監査を依頼する

出力が広範になり、検証しにくくなります。代表 URL 一つとページストーリー一つから始めてください。同じ仕組みが別ページでも確認できた後にだけ範囲を広げます。

CLAUDE.mdをセキュリティ制御として扱う

これはガイダンスであり、単独の権限システムではありません。コマンド承認、リポジトリ権限、人間によるレビューを維持してください。

証拠ファイルをプロダクトのコミットに混ぜる

キャプチャやエクスポートには非公開情報が含まれたり、不要に大きな diff を作ったりする可能性があります。承認済みの ignore 対象ディレクトリに保存し、意図したコードとテスト変更だけをコミットします。

成功をすぐ検索順位で測る

まず技術上の対象を検証します。その後、権限のあるクロールデータと検索データを使います。検索順位には関連性、競合、コンテンツ品質、リンクなど多くの要素も影響します。

テスト成功によって誤ったページ状態を見落とす

コンポーネントテストが通っても、本番ルートでは異なるデータ、メタデータ、ステータス処理を受ける場合があります。実際の訪問経路に近いルート単位またはプレビューの確認を少なくとも一つ含めます。フィルター、ページネーション、利用不可の商品、多言語版がある場合は、承認済み変更がどの状態を対象とし、どれが今回の対象外かを明記してください。

範囲確認なしで共有コンポーネントを編集する

カテゴリカードが検索、レコメンド、カート、アカウント画面でも使われているかもしれません。変更前に、コンポーネントが使われる場所と、提案するマークアップが各状況に影響するかを Claude Code に確認させます。対象が広がるなら、狭い修正を無言の再設計へ変えてしまわず、新しいブリーフを責任者に戻してください。

最初の実践ケースを最初から最後まで進める

ページストーリーに、訪問者は商品を比較して詳細を開きたいと書かれているとします。証拠フォルダには、商品名はあるものの通常の到達先リンクがないレンダリング済み DOM の抜粋があります。Claude Code はプロジェクトガイダンスを読み、ルートからカテゴリテンプレート、再利用可能なカードコンポーネント、そのナビゲーションハンドラーまでを対応付けます。そして、そのコンポーネントがレコメンドレールでも共有されているため、まだ範囲を確定できないと報告します。

ここで役立つ成果は即時パッチではありません。責任者は、二つの限定された次の手順から選べます。両方の利用状況でコンポーネントを調べるか、有効な主要到達先を与えるカテゴリ専用ラッパーを作るかです。責任者が選んだ後、実装プロンプトに対象ファイル、必要なテスト、維持するアクセス解析挙動、ロールバック条件を明記します。

パッチ後、チームはレンダリング済みカテゴリページを確認し、キーボード操作で到達先を開き、ルートのレスポンスと canonical を調べ、レコメンドレールが引き続き意図どおり動くことを検証します。最後に意思決定記録へ、テストした事実だけを書きます。検索エンジンがすべての商品 URL をすでに再処理したとは主張しません。

よくある質問

Claude Codeはライブサイトとリポジトリを一緒に調査できますか？

必要なツールとアクセス権が利用でき、許可されている場合に限ります。ライブページの証拠、リポジトリの証拠、検索プラットフォームの証拠には別々のラベルを付けてください。

CLAUDE.mdでClaude Codeによる編集を止められますか？

継続的なプロジェクトガイダンスにはなりますが、それ自体は強制力のある仕組みではありません。実行環境の権限とレビュー制御を使ってください。

JavaScript SEOの問題には必ずサーバーサイドレンダリングが必要ですか？

いいえ。安定リンク、正しいステータス、一貫したメタデータ、利用可能なデータ経路、小さなコンポーネント変更が適切な解決策かもしれません。先に診断してください。

Claude Codeに承認済みパッチをデプロイさせるべきですか？

責任者、テスト、ロールバック計画を含む別のデプロイ許可がない限り、実行させるべきではありません。ローカル実装の承認は、本番リリースの承認ではありません。

初心者は何から調査すべきですか？

価値の高いページ一つと、標準リンクの欠落や誤ったレスポンス状態のような目に見える症状一つを選びます。コード変更を依頼する前に、証拠フォルダを作ってください。

著者：Julian Mercer。Auspia で 14 年の経験を持つテクニカル SEO 実務家。クロール可能性、レンダリング、サイト構造、AI が読み取りやすいコンテンツの技術基盤について執筆しています。