保守・運用・引き継ぎ設計

納品後の保守体制を設計する

多くのプロジェクトで「納品したら終わり」という認識のまま運用フェーズに入り、 後から混乱が生じます。保守体制は納品前に設計し、クライアントと合意するものです。

保守フェーズの役割分担を明確にする

HubSpot サイトの運用には、技術的な保守とコンテンツ運用の2つの軸があります。 誰が何を担当するかを最初に整理します。

保守契約の種類と内容定義

保守依頼フローの設計

クライアントへの引き継ぎドキュメント設計

引き継ぎドキュメントはマーケター・コンテンツ担当者が自走できるようにするためのものです。 エンジニア視点で書くと「難しすぎる」ドキュメントになります。 読む相手に合わせて内容を設計することが重要です。

引き継ぎドキュメントの構成

モジュール別操作ガイドのテンプレート

モジュールが多い場合、すべてを1枚のドキュメントに書くと読みにくくなります。 モジュール1つにつき1ページのスタイルで、 Notionや社内Wikiに整理するのが最も使われやすい形式です。

# ヒーローバナー モジュール操作ガイド

## このモジュールは何ですか？
ページ最上部に大きな画像とキャッチコピーを表示するバナーです。
トップページ・サービスページ等に配置されています。

## フィールドの説明

| フィールド名 | 内容 | 注意点 |
|-------------|------|--------|
| 見出し | バナーのメインテキスト | 最大30文字推奨 |
| サブ見出し | 見出し下の補足テキスト | 省略可 |
| 背景画像 | バナー全体の背景画像 | 推奨サイズ: 1440x640px |
| CTAボタンのテキスト | ボタンに表示する文言 | 最大15文字推奨 |
| CTAボタンのリンク | ボタンのリンク先URL | 外部リンクは別タブで開く |

## 推奨画像サイズ
- 幅：1440px 以上
- 高さ：640px 〜 800px
- ファイル形式：JPG（写真）/ PNG（透過あり）
- ファイルサイズ：2MB以下に圧縮推奨

## やってはいけないこと
⚠️ 縦長の画像（1:1 以下の比率）は使わないでください。
   PC表示でレイアウトが崩れる場合があります。
⚠️ テキスト入りの画像を背景に使うと、
   モバイルで読めなくなる場合があります。

運用を見据えたモジュール・テンプレート設計

「動くコード」と「運用しやすいコード」は異なります。 開発時の1時間の工夫が、クライアントの運用で何十時間もの迷いを省きます。

マーケターが触れる範囲とエンジニアが触れる範囲の分離

運用しやすい fields.json の書き方

[
  {
    "type": "text",
    "name": "heading",
    "label": "見出し",
    "required": true,
    "default": "見出しテキストを入力してください",
    "help_text": "最大 30 文字推奨。長すぎるとスマホで折り返します。"
  },
  {
    "type": "image",
    "name": "bg_image",
    "label": "背景画像",
    "help_text": "推奨サイズ: 1440×640px。JPG形式・2MB以下に圧縮してください。",
    "default": {
      "src": "",
      "alt": "",
      "width": 1440,
      "height": 640
    }
  },
  {
    "type": "choice",
    "name": "layout",
    "label": "レイアウト",
    "help_text": "テキストの配置位置を選択してください。",
    "choices": [
      ["center", "中央（デフォルト）"],
      ["left",   "左寄せ"],
      ["right",  "右寄せ"]
    ],
    "default": "center",
    "display": "radio"
  },
  {
    // STYLE タブのフィールドは「上級者向け」として
    // 通常の編集画面から切り離す
    "type": "color",
    "name": "overlay_color",
    "label": "オーバーレイカラー",
    "tab": "STYLE",
    "help_text": "背景画像の上に重ねる色。透明度も設定できます。",
    "default": { "color": "#000000", "opacity": 40 }
  }
]

テンプレートへのコメント設計

テンプレートファイルには、後から触れる人（将来の自分・引き継いだエンジニア）のために コメントを残します。「何をしているか」より「なぜこうしたか」を書くのが原則です。

{#
  =====================================================
  ブログ記事テンプレート (blog-post.html)
  =====================================================
  【用途】ブログ記事の詳細ページ
  【継承】layouts/base.html
  【DnD】なし（固定レイアウト）

  【更新履歴】
  2024-03-15  v1.2  コンテンツ種別別フォーム切り替えを追加
  2024-01-10  v1.1  前後記事ナビゲーションを追加
  2023-11-01  v1.0  初期リリース

  【注意点】
  - タグの命名規則は README.md の「タグ設計」を参照すること
  - フォームIDはこのファイル内の form_config 辞書で管理している
  - フォームを追加したい場合は form_config に追記すること
  =====================================================
#}
{% extends "./layouts/base.html" %}

{# ===== コンテンツ種別の判定 =====
   タグのプレフィックスで種別を判定する。
   詳細は第6章「タグ設計戦略」を参照。
   type: タグが複数付いている場合は最後に見つかった値が使われる（運用上1つのみ推奨）
===================================================== #}
{% set ns = namespace(content_type="blog") %}
{% for tag in content.tag_list %}
  {% if tag.slug starts_with "type:" %}
    {% set ns.content_type = tag.slug|replace("type:","") %}
  {% endif %}
{% endfor %}

{# ===== フォーム設定辞書 =====
   コンテンツ種別ごとのフォームIDとリダイレクト先を管理。
   新しい種別を追加する際はここに追記すれば OK。
   フォームIDはHubSpot管理画面のフォーム詳細URLで確認できる。
===================================================== #}
{% set form_config = {
  "blog"       : { "id": "BLOG_FORM_ID",       "redirect": "/thanks/contact"    },
  "seminar"    : { "id": "SEMINAR_FORM_ID",    "redirect": "/thanks/seminar"    },
  "whitepaper" : { "id": "WHITEPAPER_FORM_ID", "redirect": "/thanks/whitepaper" }
} %}

コーディング規約とコメント規約

チームで開発・保守する場合、規約がないとコードの書き方がバラバラになり 保守コストが上がります。最小限でも明文化された規約が必要です。

HubSpot CMS 開発コーディング規約（推奨テンプレート）

# HubSpot CMS コーディング規約

## ファイル・ディレクトリ命名規則
- ファイル名・ディレクトリ名：kebab-case（例: hero-banner, blog-post）
- モジュール名：kebab-case + .module（例: hero-banner.module）
- CSS クラス名：BEM（Block__Element--Modifier）
- HubL 変数名：snake_case（例: content_type, form_id）

## HubL 規約

### 変数定義
- ループ外で使う変数は冒頭でまとめて定義する
- 辞書（マップ）は set で定義してから参照する
- namespace（ns）は状態を持つループ処理でのみ使用する

### テンプレートコメント
- ファイル先頭：目的・更新履歴・注意事項を記載する（必須）
- 複雑なロジック：「なぜこうしたか」を書く（何をしているかは読めばわかる）
- TODO：「TODO: 」プレフィックスで検索しやすくする

### 存在チェックの原則
- image フィールド：{% if module.image.src %} でチェック
- link フィールド ：{% if module.link.url %}  でチェック
- テキスト        ：{% if module.text %}       でチェック
- 存在チェックなしで .src 等を参照してはいけない

## CSS 規約

### 命名規則（BEM）
.module-name {}              ← Block
.module-name__element {}     ← Element
.module-name--modifier {}    ← Modifier
.module-name__element--mod{} ← Element + Modifier

### レスポンシブ
- モバイルファースト（min-width でブレークポイントを上書き）
- ブレークポイントは CSS 変数で統一する
  --bp-sm: 480px;
  --bp-md: 768px;
  --bp-lg: 1024px;
  --bp-xl: 1280px;

### CSS変数の参照
- theme.json のカラー・フォントは必ず CSS 変数経由で参照する
- 直接値（#ff0000 等）はハードコードしない

## アクセシビリティ規約
- 全 img タグに alt 属性を設定する（装飾画像は alt=""）
- インタラクティブ要素に aria-label を設定する
- カラーコントラスト比は WCAG AA（4.5:1）以上を維持する
- キーボード操作でフォーカスが視覚的に確認できること

## Git コミットメッセージ規約
feat:    新機能追加
fix:     バグ修正
style:   見た目の調整（機能変更なし）
refactor:リファクタリング
docs:    ドキュメントのみの変更
deploy:  本番デプロイ（バージョンタグと合わせて使用）

HubSpot アップデートへの対応と定期メンテナンス

HubSpotは継続的にアップデートされるプラットフォームです。 機能追加・UI変更・非推奨化への対応を定期的に行うことで、 サイトの品質を長期維持できます。

定期メンテナンスの項目と頻度

HubSpot アップデートで影響を受けやすい箇所

• HubL の非推奨関数： blog_recent_posts() 等の関数仕様は変わることがある。HubSpot 開発者ドキュメントの "Deprecated" セクションを定期確認する。
• デザインマネージャーのUI変更： エディターのUIが変わっても機能は同じことが多いが、クライアント向けマニュアルのスクリーンショットが古くなる。年1回の見直しを推奨。
• HubDB のAPI仕様変更： hubdb_table_rows() のクエリパラメータに変更がある場合がある。HubDB を多用するサイトは特に注意。
• フォームの埋め込みスクリプト： js.hsforms.net/forms/embed/v2.js のバージョンが上がった際は動作確認が必要。

よくある運用トラブルと解決策

トラブルシューティングガイド

HubL デバッグの基本テクニック

{# ===== 変数の中身を確認する =====
   本番環境では必ず削除すること！
===================================================== #}

{# ① 変数の型と値を確認 #}
<pre>{{ module|pprint }}</pre>

{# ② ループカウンタの確認 #}
{% for item in module.items %}
  {# loop の状態を出力 #}
  <p>index:{{ loop.index }} / first:{{ loop.first }} / last:{{ loop.last }} / length:{{ loop.length }}</p>
{% endfor %}

{# ③ 条件分岐の確認（判定結果を出力）#}
<p>content_type: {{ ns.content_type }}</p>
<p>is_featured: {{ ns.is_featured }}</p>

{# ④ HubDB データの確認 #}
{% set rows = hubdb_table_rows("my_table") %}
<p>取得件数: {{ rows|length }}</p>
<pre>{{ rows|pprint }}</pre>

{# ⑤ request オブジェクトの確認（URLパラメータ等）#}
<pre>{{ request|pprint }}</pre>

パフォーマンスの定期モニタリング

月次パフォーマンスレポートの構成

保守契約に含まれる場合、月次でクライアントにレポートを提出します。以下の項目を含めると信頼性が高まります。

長期運用チェックリスト

教科書のまとめ：HubSpot CMS 開発者として