Codexで長文HTMLを
専用parts化した実践ログ

今回やった作業

公開中サイトで、説明guideのような長文HTMLを追加する際に、対象ページ本体へ直接書き込まず、専用partsとして分離して読み込んだ作業を一般化して書きます。この作業では、ページ本体を大きく書き換えるのではなく、専用の静的guideパーツを作成し、対象ページの適切な位置からrequireで読み込む形にしました。

その後、PHP構文確認と公開HTML確認を行い、実際に表示されていることを確認します。ここで大事なのは、ファイルを作っただけで完了にしないことです。読み込み位置、公開URLの状態、公開HTML上の本文、対象外ページへの混入、既存カード部品や共通部品への影響まで見る必要があります。

作業前の状態

作業前は、カード一覧やランキングページに説明guideを追加したい状態でした。追加する文章は短い一文ではなく、ある程度まとまった説明ブロックです。ページ本体に直接HTMLを書くと、あとから保守しづらくなる可能性がありました。

既存カード部品や共通header/footerは触りたくありませんでした。CSSも大きく変えず、静的partsとして安全に追加したい作業です。ページ本体には、データの準備、対象ページの判断、parts呼び出し、最低限の表示制御という役割を残し、説明guide本文は別ファイルに分ける方針にしました。

作業前に問題だったこと

ページ本体に長文HTMLを直書きすると、ページ生成ファイルの役割が混ざります。本来、ページ本体は、必要なデータを準備する、対象ページかどうか判断する、partsを呼び出す、最低限の表示制御を行う、という役割にしておくと見直しやすくなります。

そこに長文の説明ブロックが増えると、データ取得、条件分岐、HTML本文が同じ場所に混ざり、どこを直せばよいか分かりにくくなります。Codexに修正を頼む時も、変更範囲が広がるほど事故の可能性が上がります。小さな説明追加のつもりが、カード出力や共通部品へ影響する作業になってしまうことがあります。

長文HTML直書きを避ける理由

長文HTML直書きを避ける理由は、単に見た目の好みではなく、保守性の問題です。ページ本体へ長文を直接書くと、ページ全体の見通しが悪くなります。同じ型を別ページへ横展開しにくくなり、文章修正のたびにページ本体を触る必要が出ます。

条件分岐の中にHTMLが増えると、処理と文章が混ざって読みづらくなります。誤って既存処理を壊す可能性も上がります。特にCodex作業では、触る範囲が広がるほど、意図しない変更や確認漏れが起こりやすくなります。説明guideのように静的なブロックは、ページ本体から分けた方が確認しやすく、戻しやすく、再利用しやすくなります。

専用parts化するメリット

専用partsに分けると、説明guideだけを独立して編集できます。対象ページ本体の変更量を減らせるため、レビューもしやすくなります。同じ構造を別ページにも流用しやすく、不要になった場合は読み込みを外すだけで済みます。

公開HTMLでguide本文を確認しやすいことも利点です。Codex報告で「作成したparts」と「読み込んだページ」を分けて確認できます。また、条件分岐とHTML本文を分けられるため、どのページで表示するかの制御もしやすくなります。ページ本体、共通部品、カード部品の役割を混ぜないことで、あとからの修正や調査が楽になります。

Codexに任せたこと

Codexに任せたのは、単なる文章追加ではなく、parts化まで含めた安全な実装です。確認させる内容は、partsディレクトリの確認、既存のparts構成の確認、新規partsファイルの作成、対象ページからのrequire追加、読み込み位置の確認、php -lによる構文確認、公開HTMLにguide本文が出ているかの確認です。

さらに、対象外ページへ混入していないか、共通header/footerやカード部品を触っていないかも確認させます。Codexに「説明文を追加して」とだけ頼むと、ページ本体に長文を入れるか、共通部品へ入れてしまう可能性があります。実装方法まで指定することで、変更範囲を小さく保てます。

人間が判断したこと

人間が判断したのは、ページ本体に長文HTMLを直書きしないことです。説明guideは専用partsとして分離します。既存カード部品を触らないこと、共通header/footerを触らないこと、CSSは必要最小限にすることも判断しました。

対象ページからrequireで読み込み、公開HTML確認まで行うことも条件にします。php -lで構文確認することも大切です。PHP構文エラーは公開画面の500につながる可能性があるため、ファイルを保存しただけで終わらせません。人間は、どの位置に置くか、どのページだけに出すか、どこまでCodexに触らせるかを先に決めます。

parts化する時の実装イメージ

実装イメージは、まず専用partsファイルを作るところから始まります。たとえば、一般化した例として、parts/guide/example-guide.php のような専用ファイルを作ります。実際の記事では案件固有のファイル名やサーバーパスは出しません。

次に、対象ページの表示したい位置を確認します。H1説明ブロックの直後、カード一覧本体の前、ランキング本体の前など、読者が一覧を見る前に説明を読める位置が候補です。その位置からrequireで読み込みます。読み込み後は、対象ページとpartsに構文エラーがないか確認し、公開HTMLでguide本文が出ているかを確認します。ここまで行って、はじめて実装済みと言えます。

require読み込み後に確認したこと

requireで読み込んだだけでは完了にしません。確認することは、PHP構文エラーがないか、公開URLが200 OKか、公開HTMLにguide本文が出ているか、表示位置が意図通りか、一覧本体やランキング本体が壊れていないか、対象外ページに混入していないかです。

title、description、H1、canonical、robotsが維持されているかも確認します。説明guideの追加は本文改善の作業であり、SEOタグを変える作業ではありません。もし公開HTMLにguide本文が出ていない場合は、require位置、条件分岐、ファイル名、読み込み対象を確認します。報告書には、作成したparts、読み込んだページ、確認した公開URLを分けて残すとレビューしやすくなります。

うまくいった点

うまくいった点は、ページ本体を大きく汚さずに説明を追加できたことです。guide本文だけを別ファイルで管理でき、既存カード部品を壊さずに済みました。共通header/footerへ影響を出さずに済んだことも大きいです。

公開HTMLで確認しやすくなったことも利点です。専用partsとして作っているため、どの本文が追加されたのかを追いやすくなります。今後、別ページへ同じ型を横展開する場合も、partsの考え方を使えます。ただし、横展開する時も、同じ文章を無条件に大量展開するのではなく、ページごとの役割に合わせて調整します。

詰まった点・危なかった点

危なかった点は、require位置を間違えると表示位置がズレることです。H1直下に出したいのにカード一覧の下へ出たり、ランキング本体の前に出したいのに下部へ回ったりすると、guideの役割が弱くなります。対象外ページにも読み込まれる危険があります。

parts化したつもりでも公開HTMLに出ていないことがあります。php -lをしないと構文エラーに気づきにくい点も注意が必要です。共通部品に入れると影響範囲が広がりすぎます。CSSを追加しすぎると既存デザインが崩れる可能性もあります。小さな実装ほど、確認を省略しないことが大事です。

作業後に確認したこと

作業後は、専用partsを作成したこと、対象ページから読み込んでいること、PHP構文エラーがないこと、公開HTMLに表示されていることを確認します。ページ本体への長文直書きがないこと、共通部品を触っていないこと、カード部品を触っていないことも見ます。

title、description、H1を変更していないこと、canonicalとrobotsが維持されていること、noindexが入っていないことも確認します。parts作成、require追加、構文確認、公開HTML確認、対象外混入なしまでそろって、ようやく安全な追加と言えます。報告書では、変更ファイルと触っていないファイルを分けて書くと、あとから確認しやすくなります。

次回使えるCodex指示文テンプレート

同じような説明guideを追加する時は、次のように依頼します。長文HTMLをどこに書くかを最初に指定することで、ページ本体の見通しを守りやすくなります。

長文の説明ブロックは、対象ページ本体に直書きせず、専用partsとして作成してください。

まず、既存のpartsディレクトリや似た構造のpartsがあるか確認してください。

新規partsを作成し、対象ページからrequireで読み込んでください。

読み込み位置は、H1説明ブロック直後、カード一覧本体の前、ランキング本体の前など、読者が一覧を見る前に説明を読める位置にしてください。

title、meta description、H1、canonical、robotsは変更しないでください。

既存カード部品、共通header/footer、DB、cron、.htaccess、robots.txt、ads.txt、広告タグ、Search Console確認タグは触らないでください。

作業後は、php -lで構文確認し、公開HTMLにguide本文が出ていること、一覧表示が壊れていないこと、対象外ページに混入していないことを確認してください。

確認チェックリスト

長文guideをparts化する時は、次の項目を確認します。実装したかどうかだけでなく、どこに出ているか、何を触っていないかまで見るのが安全です。

• 専用partsを作成した
• 対象ページから読み込んでいる
• require位置が意図通り
• PHP構文エラーなし
• 公開HTMLに表示されている
• ページ本体への長文直書きがない
• 共通部品を触っていない
• カード部品を触っていない
• titleを変更していない
• descriptionを変更していない
• H1を変更していない
• canonicalが維持されている
• robotsが維持されている
• noindexが入っていない
• 対象外ページに混入していない

注意書き

この記事は、実際の作業を一般化してまとめた実践ログ型ガイドです。具体的な案件名、内部情報、サーバーパス、秘密情報は掲載していません。

特定のフレームワークや公式手順ではなく、公開中サイトで説明guideを安全に追加するための実務上の考え方として整理しています。実際の実装では、サイトの構成、テンプレート、読み込み方式に合わせて確認してください。