スキル疎通テスト手順書
snowmole-html-report スキルが Hard Gate 6 要素を満たし、Cloudflare Pages へ公開できるかを 5 分で一気通貫に確認する。
1. 目的
この手順書は、snowmole-html-report スキルそのものが正しく動作するかを短時間で検証するためのテスト手順です。
新しい PC にセットアップした直後、CLOUDFLARE_API_TOKEN の設定を変えた直後、スキルをアップデートした直後など、
本番の長い資料を書く前に「ちゃんと通るかどうか」をここでサッと確認してください。
本番の作業手順書ほどの情報量は不要ですが、Hard Gate 6 要素は全て揃えてあります。 この手順書自体がスキルの出力品質のベースラインにもなっています。
2. 現状の課題
テスト用の簡単な資材が用意されていないと、以下が起きます。
- 🚨 セットアップが動くかどうか、本番資料でしか検証できないのでコストが高い
- 🚨 トークン期限切れや権限抜けに、長文を書いた後で気付いてしまう
- 🚨 スキルアップデート後、6 要素が揃ったままかを毎回目で確認している
- 🚨 新メンバーに 「動く状態」 を示す再現可能な例がない
3. ありたい姿
このテスト手順書を 1 本回すだけで、次の状態が確認できている。
- ✅ セットアップ直後に 5 分 でスキルが生きているか分かる
- ✅ Hard Gate 6 要素が揃った テンプレ的サンプル が常に手元にある
- ✅
CLOUDFLARE_API_TOKENの有効性が 本番資料を書く前に 検証できる - ✅ 新メンバーは「このテスト手順書と同じ URL が出れば OK」と ゴールが明確
4. 現状 → ありたい姿（切替ビュー）
ボタンで切り替えて対比してください。ここがトグル式の比較ビジュアル（Hard Gate 要素 4）です。
- 本番資料でしか疎通確認できない
- トークン不備の発覚が遅い
- 6 要素抜けを目検に依存
- 再現可能な「動く例」がない
- 5 分でスキルの生存確認
- トークン有効性も同時に検証
- 6 要素テンプレを常備
- 公開 URL が「動く例」として共有可能
5. 全体フロー
3 ステップで完了します。
6. 前提条件
| 項目 | 要件 |
|---|---|
| Claude Code | snowmole-html-report プラグインがインストール済み |
| Node.js | npx wrangler --version が通る（v18+ 推奨） |
| 環境変数 | CLOUDFLARE_API_TOKEN が設定済み（権限: Pages Edit / User Read / Memberships Read） |
| ネットワーク | Cloudflare API（api.cloudflare.com）へ HTTPS で到達可能 |
CLOUDFLARE_API_TOKEN が二重連結（106 文字）で設定されている PC では、wrangler 実行前に ${CLOUDFLARE_API_TOKEN:0:53} でトリムする必要があります（snowmole 社内既知）。
1Claude にテスト生成を依頼
ターミナル or エディタ統合の Claude Code で、次の一言を送ります。
2生成ファイルの絶対パスを受け取る
完了案内に、次のような絶対パスと https://...pages.dev/ URL が返ってきます。
1左サイドバー TOC をクリックしてスクロール追従を確認
スクロールに応じて現在地がハイライトされれば OK。
2「現状 → ありたい姿」の切替ボタンを押す
赤系 ↔ 緑系の SVG とリストがフェードインで切替されれば OK。
3目的・現状・ありたい姿の 3 点セットが揃っているか目視
| 要素 | 見る場所 |
|---|---|
| 目的 | §1 |
| 現状の課題 | §2（Before SVG） |
| ありたい姿 | §3（After SVG） |
| 比較ビジュアル | §4（トグル切替） |
| サイドバー TOC | 左側全体 |
| インタラクティブ要素 | トグル・コピー・accordion・チェックリスト |
1返ってきた *.pages.dev URL をブラウザで開く
Cloudflare Pages がグローバル配信するまで初回は 10〜30 秒の遅延があります。
2ローカルで見たページと同じ内容・レイアウトか確認
フォント・配色・SVG が一致し、TOC・トグル・コピーボタンが動けば疎通 OK。
3モバイル幅に絞って崩れがないか確認
Chrome DevTools の iPhone エミュレーション等で、サイドバーが上部に畳まれて縦積みになることを確認。
同じプロジェクト名で再度 「公開して」 と依頼すれば上書きデプロイ。URL は変わりません。
7. 動作確認
ターミナルでも疎通が取れるかを合わせて確認すると、トークン側の問題と HTML 側の問題を切り分けられます。
npx wrangler whoaminpx wrangler pages project list | head -208. トラブルシューティング
🔒Authentication error (code 10000) が出る
トークンに User > Memberships > Read が無い場合に発生。対処：
- Cloudflare Dashboard でトークンを編集し、Memberships Read を追加
- または
CLOUDFLARE_ACCOUNT_IDを環境変数で明示指定
🔄トークン長が 106 文字になっている
二重連結の既知事象。wrangler 呼び出し時に ${CLOUDFLARE_API_TOKEN:0:53} でトリムするか、~/.zshrc の export 文を 1 箇所に直します。
❌公開 URL が 404 になる
デプロイ直後は反映に 10〜30 秒かかります。以下を確認：
- 30 秒ほど待って再読込（初回は特に時間がかかる）
- デプロイ対象フォルダに
index.htmlが存在するか（ファイル名は必ずindex.html） - プロジェクト名が他テナントと衝突していないか
🎨ローカルと公開ページで見た目が違う
highlight.js の CSS/JS を CDN から読み込んでいます。ネットワーク制限下では pre code のシンタックスハイライトが無効化されるだけで、レイアウトには影響しないはず。ほかに差異があれば Cloudflare のキャッシュを purge してください。
9. FAQ
このテスト手順書を顧客に共有しても良いですか？
社内検証用です。意図せず外部に出ないよう、ファイル名・プロジェクト名からは顧客固有情報を排除しています。共有しても実害はありませんが、基本は社内利用にとどめてください。
同じプロジェクト名で何度もデプロイして大丈夫？
はい。Cloudflare Pages は同名プロジェクトに対して新しいデプロイメントを上書き追加する仕様です。URL は変わりません。
PDF に落としたい
ブラウザの印刷機能から PDF として保存できます。@media print 対応済みで、サイドバー・コピー・トグルが非表示になり、比較ビジュアルは両方同時表示に切り替わります。
10. 完了チェックリスト
クリックでチェックできます（状態は保存されません）。
- 左サイドバー TOC がスクロール追従している
- 「現状 / ありたい姿」トグル切替が動く
- コピーボタンでクリップボードに値が入る
- accordion（トラブルシューティング）が開閉する
- 公開 URL（*.pages.dev）でローカルと同じ見た目が出る
- モバイル幅でサイドバーが上部に畳まれる
- ブラウザ印刷プレビューでサイドバーが消えて A4 に収まる
全てチェックが入れば、snowmole-html-report スキルは本番運用可能な状態です。お疲れさまでした。