サイトの記事に目次がなかったのでAI（Claude）と一緒に追加してみた

みずかげ製作所が運営するAI伴走支援サービスTOUHAのサイトのコラムページですが、公開から1ヶ月ほど目次がありませんでした。SEOメディアともなれば目次があるのはほぼ当たり前ですので、なんとかしないといけません。

そこで、記事本文に目次を追加しました。作業はAI（Claude Code）と一緒に進めています。この記事では、何を変えたのか、どう進めたのか、そして「目次を出すだけ」に見えて実際にはつまずいた点をまとめます。

TOUHAサイトに目次を付けた理由

公開中の経営コラム49記事を調べたところ、1記事あたりの見出し（h2）は4〜9個。全記事の合計は316個であることが分かりました。

SEOを意識したコラムなので、どの記事も「リード文のあとに本文が複数の節に分かれて続く」構成になっています。ここに目次があることで、読者としても記事内容の全体像や流れを最初に把握できるわけであります。

そのほか、検索エンジンにとってもページ内リンクの構造がわかりやすくなるので、評価されやすくなります。
読者にとっても検索エンジンにとってもメリットがあるため、今回実装を決めました。

目次の追加をBefore・Afterで比較

同じ記事（「生成AIを業務に組み込む7工程｜チャット利用で終わらせない設計」）で比べます。

PC表示

Before：リード文のあと、すぐに最初の見出しが始まります。

After：リード文と最初の見出しの間に目次が入ります。

スマホ表示

目次の項目を押すと、その見出しまで移動します。画面上部に固定されたヘッダーの下に、見出しがきちんと見える位置で止まります（理由は後述）。

目次の実装を解説します

TOUHAブログページはWordPressで動くオウンドメディアです。今回は以下の仕様に沿って目次の追加をしました。

仕様

小見出しを載せないのは、目次が長くなりすぎるためです。たとえば検証に使った記事は見出し7個に対して小見出しが19個あり、両方を載せると26項目の長大な目次になってしまいます。

プラグインを使わず、テーマに直接組み込んだ

WordPressには「Table of Contents Plus」のように、目次を自動で作るプラグインがあります。今回は使わず、テーマ（サイトのデザインを決めるプログラム）に直接書き足しました。理由は2つです。

• TOUHAサイトは記事本文の見た目を独自のCSSで作り込んでいて、プラグインが出力するHTMLとぶつかりやすい
• 記事本文にはすでに独自の加工（プロンプトの表示枠や関連記事カード）を入れているため

変更したのは、テーマの中の2つのファイル（処理を書く「functions.php」と、見た目を決める「contents.css」）だけです。

作業はClaude Codeメインで進めました

作業は Claude Code というAIのコーディングツールで進めました。1つのAIに全部を任せるのではなく、役割を分けています。

ポイントは、作る人と確かめる人を分けたことです。実装したAIが「できました」と言っても、レビュー役のAIは報告を鵜呑みにしません。実装側が試していない条件（見出しに記号が入る場合、見出しがない記事など）を自分で試します。次に紹介するつまずきの多くは、この確認で見つかりました。

作業指示書には、変更するファイル、触ってはいけないファイル、確認コマンドとその期待値まで書いています。

AIによる実装でつまずいた点

「見出しを集めてリストにするだけ」に見えますが、実際に開発中に動かしてみると4つも大きな問題が出ました。

見出しの一部の文字が目次から消えた

「月額$19で始めるAI活用」という見出しが、目次では「月額で始めるAI活用」になりました。「$」などの記号をプログラムが特別な意味に受け取っていたためです。記号をそのまま文字として扱う書き方に直しました。

目次を押しても移動しない見出しがあった

今回は各見出しに、目次用のid『toc-1、toc-2 …』を付ける計画でした。

ところが、記事を書く人がページ内リンクのために、見出しへ自分で目印を付けている場合があります。たとえば次のような見出しです。

<h2 id="already-here">すでに id がある見出し</h2>

ここに目次用の目印を足すと、目印が2つある見出しになっていました。

<h2 id="already-here" id="toc-1">すでに id がある見出し</h2>

1つの見出しに目印は1つしか持てないのがルールです。ブラウザは最初のidだけを採用し、toc-1を無視します。そのため「目次をクリックしても動作しない」という事象が起きてしまったのです。

目次の見た目が本文とちぐはぐになった

リンクや番号つきリストのデザインはサイトのデザインと合わせないと、無駄にCSSが増えたりデザインの統一感がなくなったりします。
目次のデザインに関してはAIに丸投げしていたので、目次のリンクだけ本文のリンクと色が違って出力されてしまいました。
人間の目視確認で気が付き、修正依頼をしています。

移動した先の見出しが画面上部のヘッダーに隠れた

このサイトは、スクロールしても画面上部にヘッダーが残る作りです。見出しの上に余白を取り、ヘッダーの下に見出しが見えるようにしました。上のスマホの画像がその結果です。

どれも公開前の確認で見つかり、本番の記事では起きていません。

自分で目次を付けるときのチェックリスト

• 見出しに $ や \ を含めても、目次の文字が欠けないか
• もとから目印（ID）がある見出しでも、目次から飛べるか
• 見出しが0個・1個の記事で、目次が出ない（エラーにもならない）か
• 本文のリストやリンクのデザインが、目次に意図せず効いていないか
• 目次のリンクの見た目が、本文のリンクとそろっているか
• 固定ヘッダーの裏に、飛んだ先の見出しが隠れないか（PCとスマホの両方で）
• 記事の一覧ページやトップページに、目次が紛れ込んでいないか

まとめ

目次の追加は、機能としては「見出しを集めてリストにする」だけです。それでも、既存のサイトに組み込むと、文字列の扱い、HTMLの目印、デザインのルール、固定ヘッダーといった、周りの仕組みとの関係で4つのつまずきがありました。

AIに実装を任せるときほど、「作る役と確かめる役を分けること」「想定外の入力を試してみること」が重要です。今回の不具合について実装中に見つけられたのは、この確認の手順があったからでした。

みずかげ製作所では、こうしたAIを使った業務改善の支援をしています。「AIに作業を任せたいが、品質をどう担保すればよいか分からない」という場合は、お気軽にご相談ください。