背景
Claude Code の公式チュートリアルを日本語にまとめたサイトを1つ運用しています。
記事は毎日1本ずつ足していて、雛形を作るスクリプトと、それを埋める作業に分かれています。
私は「雛形があるから大丈夫」と思い込む癖があって、埋め残しに気づかないことがよくあります。
今日それを、デプロイの直前のゲートに止められました。
何が起きたか
新しい記事を1本足しました。
雛形は scaffold-tutorial.js というスクリプトが作ります。
やってくれるのは、記事ページの HTML、一覧ページへのカード挿入、ItemList（一覧を機械に伝えるための JSON-LD の構造化データ）の採番し直し、sitemap.xml への URL 追加まで。
出力にはこう書いてありました。
"todo": "各 H2 セクションの本文と related-section/article-nav を LLM が公式に基づき翻訳・執筆する"
本文は書きました。
related-section と article-nav は読み飛ばしていました…。
この2つは、記事の下にある「関連チュートリアル」と「前後の記事」のリンクです。
無くても記事そのものは表示されるので、ブラウザで見ても気づきません。
ゲートで止まった
本番反映の直前に preflight という検査を通す運用にしています。
ビルドの後、デプロイの前です。
node automation/run.js preflight --site claude_web
出た結果がこれでした。
branch:pass up-to-date:pass tests:pass expired-content:skip
affiliate-tag:pass emoji:pass
nav-links:fail(回遊導線が欠けた記事 1/63本:
claude-model-migration-guide.html(article-nav,related-section,related-actions))
seo-must:pass
exit 1
63本のうち1本だけ、記事の中から他の記事へ出ていくリンクが無い。
つまり 一覧からは入れるが、そこから先へ進めない行き止まりのページ ができていました。
exit 1 なら deploy しない、という運用にしてあるので、ここで止まりました。
なぜ「デプロイの直前」なのか
以前は、この種の検査をサイト全体の監査としてまとめて回していました。
問題は、その監査が 全部のデプロイが終わったあと に走っていたことです。
つまり「本番に出してから気づく」配置でした。
気づいた時点で本番にはもう出ていて、直すには次のデプロイを待つことになる。
配置を「ビルドの後・デプロイの前」に移すと、意味が変わります。
検査が通らなければ、そもそも出ない。
同じ検査でも、置く場所によって「事後報告」から「ゲート」に変わる、というのが今回いちばん腑に落ちたところでした。
直した内容
既存の記事から同じ構造をコピーして、リンク先だけ実在するページに差し替えました。
<nav class="article-nav" aria-label="前後の記事">
<a class="nav-prev" href="/tutorials/choosing-the-right-claude-model.html">...</a>
<a class="nav-next" href="/tutorials/count-tokens-before-calling-claude.html">...</a>
</nav>
<div class="related-section">
<h3>関連チュートリアル</h3>
<div class="related-list">
<a href="/tutorials/extended-thinking-with-claude.html">...</a>
</div>
<div class="related-actions">
<a href="/tutorials/">チュートリアル一覧へ戻る</a>
</div>
</div>
リンク先が実在するかは ls で確かめました。
存在しないパスを書いても HTML としては通ってしまうので、ここは機械に聞くしかありません。
再実行するとこうなりました。
nav-links:pass ... exit 0
デプロイして、公開されたのがこの記事です。
https://claude-guide.autoarticles.net/tutorials/claude-model-migration-guide.html
学んだこと
雛形を作るスクリプト側で related-section まで自動生成する、という直し方も考えました。
やらなかったのは、関連記事の選び方が内容に依存するからです。
機械が適当に4本選ぶと、関連していない記事が並んで、かえって読者を迷わせます。
そうすると「人間（あるいは LLM）が埋める前提の穴」は残り続ける。
残るなら、埋め忘れを検出する側を用意するほうが現実的でした。
埋め忘れが起きる場所が分かっているなら、埋め忘れないようにするより、埋め忘れたまま本番に出ないようにするほうが安い。
前者は毎回の注意力に頼りますが、後者は1回書けば効き続けます。
本記事はAI補助で執筆した、個人開発の紹介記事です。