ワークフローは、作るより引き継ぐほうが難しい機能です。画面を開けば条件もアクションも見えるため、設計書は不要だと判断されがちですが、実際に後任が困るのは「何が設定されているか」ではなく「なぜその設定なのか」です。登録条件にこのステージが含まれている理由、分岐の順序がこうなっている理由、再登録をオフにしている理由。これらは画面からは読み取れません。

設計文書をユーザー企業側の責任で整備するという考え方は、IPA（情報処理推進機構）のユーザのための要件定義ガイドでも繰り返し示されています。ベンダーに作らせた文書は、ベンダーが離れた時点で更新が止まります。

結果として起きるのは、誰も触れないワークフローが積み上がる状態です。止めてよいか分からないので止めない、変えると何が壊れるか分からないので変えない。従業員1,000名規模の組織でHubSpotを数年運用すると、稼働中のワークフローの半数以上が「作った人がもういない」状態になります。私たちが大手企業の運用を引き継ぐ際、最初に着手するのがこの設計書の再構築です。

本記事では、ワークフロー設計書に何を書き、どの仕様を根拠に判断するのかを整理します。ワークフロー機能そのものの基本はHubSpotワークフローとはで解説していますので、本記事は設計を文書に残す工程に絞ります。

なぜワークフローは「作れるのに引き継げない」のか？

HubSpotのワークフローエディターは、設定内容を視覚的に表示します。それでも引き継げないのは、画面に表示される情報が「現在の状態」に限られるからです。設計時に検討して却下した選択肢、意図的に除外した対象、運用の中で追加された例外。これらは画面に痕跡を残しません。

もう一つの要因が、情報の保存期間です。アクションログのデータは90日間保存され、登録の履歴データはワークフローベースのフィルターを有効にするために6か月間保持されます。半年以上前に何が起きたかは、画面からは追えません。設計書は、この保存期間の外側を補う記録でもあります。

設計書は、どの時点で書くべきか？

実装の後に書くと、画面の内容を転記しただけの文書になります。私たちは、ワークフローエディターを開く前に設計書を書き、レビューを通してから実装する順序を標準にしています。設計書を先に書くと、登録解除条件や例外処理の検討漏れが実装前に見つかります。

既存のワークフローを文書化する場合も、画面を見ながら転記するのではなく、作成者または業務担当者にヒアリングして「業務上の意図」から書き起こします。意図を聞けないワークフローは、その事実自体を設計書に記録してください。「作成者不明・意図不明」と書かれたワークフローは、廃止検討の候補として台帳に残ります。

ワークフロー設計書には、何を書けばよいのか？

設計書は2層構造にします。全ワークフローを一覧する台帳と、1ワークフローごとの個票です。台帳だけでは設計意図が残らず、個票だけでは全体の重複と依存が見えません。両方を同じ番号体系で紐づけます。

個票に書く項目は、後任が「変更してよいか」を判断するために必要な情報という観点で選びます。以下は私たちが標準で使っている個票の項目です。実装画面を見れば分かる項目はあえて減らし、画面から読み取れない項目に紙幅を割いているのが特徴です。

台帳側には、個票の要約に加えて「更新プロパティー」「使用セグメント」「送信メール」の3列を持たせます。この3列があると、プロパティーを1つ変更したときに影響するワークフローを検索で特定できます。設計書を作る最大の実利はここにあります。

登録条件（エンロールメント）は、どう書けば意図が伝わるのか？

登録条件を設計書に転記するだけでは、情報量が画面と変わりません。書くべきは、その条件が業務上の何を表しているかです。たとえば「ライフサイクルステージがマーケティング適格リード」という条件は、業務的には「マーケティング部門が営業に渡してよいと判断した状態」を意味します。この一文があることで、後任はステージの定義を変更するときに、このワークフローを確認すべきだと判断できます。

条件の設定手順そのものはワークフローの作成に整理されています。設計書では手順を再掲せず、「この条件に含めなかったもの」を書いてください。除外した対象こそが、設計の判断そのものです。

既存レコードを登録するかどうかを、なぜ明記するのか？

ワークフローを有効化するとき、既存レコードを登録するかを選択します。この選択は一度きりで、後から「やはり既存分も」と思っても、同じ操作は繰り返せません。既存分を登録する場合は対象件数を事前に数え、登録後に送信されるメールの通数を見積もる必要があります。

私たちは、既存レコードの登録を行う場合、設計書に「実行日」「対象件数」「実行者」を記録させています。稼働後に「なぜ過去の顧客に突然メールが届いたのか」を問われたとき、この記録がないと説明ができません。

登録解除と再登録は、なぜ設計書に書かないと事故が起きるのか？

再登録の仕様は、HubSpotのワークフローで最も誤解が多い領域です。設定画面のトグル1つに見えますが、実際には複数の制約が組み合わさっています。設計書にこの制約を書いておかないと、後任が「再登録をオンにすれば過去分も動く」と誤解します。

再登録トリガーには、設計書に必ず書き写すべき制約があります。読み方の要点は、「できないこと」の行です。これらを知らずに設計すると、動かない理由が分からないまま時間を使います。

登録解除・抑制・目標の3つを、どう書き分けるか？

レコードをワークフローから外す仕組みは複数あり、設計書で混同されがちです。ワークフローの登録設定の管理には、コンタクトベースのワークフローでは、登録条件を満たさなくなったコンタクト、ワークフローの目標を達成したコンタクト、抑制セグメントに追加されたコンタクトを削除する設定を選べると記載されています。

会社・取引・チケット・見積ベースのワークフローでは、登録解除トリガーの設定に記載のとおり、登録解除条件を設定します。同ページには、登録解除条件の設定はレコードが登録されること自体も防ぐと記載されています。つまり、登録解除条件は「出口」だけでなく「入口」にも効きます。設計書では、この二重の効果を明記してください。

目標（ゴール）の扱いは別の意味を持ちます。コンタクトベースのワークフローでの目標の使用にあるとおり、目標は達成率の測定と登録解除の両方に関わります。設計書には、目標を「効果測定のために置いているのか」「登録解除のために置いているのか」を書き分けてください。目的が違えば、見直すときの判断も変わります。手動での登録解除についてはレコードの手動登録解除に手順があります。除外設計の実務的な考え方はHubSpotワークフロー活用術｜「除外」と「目標」の使いこなし方でも整理しています。

マージされたレコードは、どう扱われるのか？

名寄せを運用に組み込んでいる組織では、マージ後の登録挙動を設計書に書いておく必要があります。既定では、マージされたコンタクトは登録条件を満たしていても登録されません。再登録がオンであれば、その後に登録トリガーを再び満たした時点で登録されることがあります。

具体例として、登録トリガーがライフサイクルステージ「顧客」の場合、両方とも顧客ステージにある2件をマージしても新しいコンタクトは登録されず、ステージが別の値に変わってから再び顧客に戻ったときに登録される、という挙動になります。名寄せ直後にメールが飛ばないのはこの仕様によるもので、不具合ではありません。設計書に書いておけば、問い合わせの往復を減らせます。あわせて、レコードのマージは取り消しできないため、マージを自動化の中に組み込む設計は避けることをお勧めします。

分岐は、設計書でどう表現するのか？

分岐を画面のスクリーンショットで残すと、更新されなくなります。文章と表で表現し、スクリーンショットは補助に留めてください。分岐の表現で必要なのは、条件の羅列ではなく「どの順で評価され、どこにも該当しない場合どうなるか」です。

HubSpotの分岐には複数の種類があり、それぞれ設定できる条件の形が異なります。ワークフローアクションの選択には、1つのプロパティーまたはアクションの出力に基づく分岐はANDとORの条件を設定できないこと、1つのプロパティーに対して最大250の分岐を作成できることが記載されています。AND／ORのロジックを使う場合は、別種の分岐を選ぶ必要があります。

同ページには、割合によるランダム分配の分岐がMarketing Hub ProfessionalおよびEnterpriseでのみ利用できること、「ワークフローへ移動」アクションでは登録トリガーを迂回して別のワークフローに登録され、元のワークフローにも残り続けることが記載されています。この「登録トリガーを迂回する」挙動は、設計書に書かないと後任が追えません。あるワークフローのログに、登録条件を満たしていないレコードが現れる理由がここにあります。

「どこにも当てはまらない」経路を、なぜ必ず書くのか？

分岐の設計で漏れるのは、想定外の値が入ったレコードの行き先です。プロパティーの選択肢が後から追加された場合、既存の分岐はその値を拾いません。設計書に既定経路を明記し、そこに流れたレコードを検知する仕組み（通知アクションや専用プロパティーへの記録）を入れておくことをお勧めします。

プロパティーの選択肢を追加するときに、どのワークフローを確認すべきかを特定できるのは台帳です。HubSpotプロパティーとはで扱っている選択肢の管理と、ワークフロー台帳の「更新プロパティー」列は、必ずセットで運用してください。

停止条件は、どう設計書に残すのか？

ワークフローを止める操作には複数あり、効果が異なります。ここを混同した設計書は、障害対応のときに役に立ちません。

ワークフローをオフにすると、新規の登録は止まりますが、すでに登録済みのレコードは登録されたまま残り、アクションは実行されないものの待機（ディレイ）はスキップされません。また、ワークフローをオフにしても登録済みレコードを特定のステップで一時停止させることはできず、特定の日にアクションを実行させたくない場合は一時停止日（pause dates）を使います。

設計書には、この3つを区別して書いてください。恒久停止（オフ）、日付指定の停止（一時停止日）、期間満了による自動停止（指定日以降のオフのスケジュール）です。これらの設定場所はワークフロー設定の管理にまとまっています。アカウントにタイムゾーンが設定されていない場合、ワークフローのタイミング設定は既定でEST（東部標準時）になります。日本の営業時間に合わせてアクションの実行時間帯を絞る設計をしているのに意図した時刻に動かない場合、まずこの設定を疑ってください。期間限定の施策では、3つめを設定したうえで、設計書に停止予定日を書き込んでおくと、棚卸しのときに廃止判断が即座にできます。

命名規則とフォルダ構成は、どう決めるべきか？

命名規則は、検索で特定できることを最優先に設計します。画面上で美しく並ぶことよりも、台帳と画面を突き合わせたときに一意に対応することが重要です。私たちが使っている型は、「オブジェクト種別・業務領域・処理内容・連番」を区切り文字でつないだものです。

この型を採る理由は、ワークフロー一覧の絞り込みと相性が良いためです。ワークフローの整理には、一覧をフォルダ、作成者、チーム、作成元のツール、アクション種別などで絞り込めることが記載されています。名称の先頭にオブジェクト種別を置くと、これらの絞り込みと組み合わせたときに目的のワークフローへ最短で到達できます。

フォルダは業務領域で切り、ライフサイクルの段階では切らないことをお勧めします。段階で切ると、1つの業務が複数フォルダにまたがり、棚卸しのときに全体像が見えません。Brandsアドオンを利用している場合は、ブランドによる絞り込みも使えます。

プロパティーの内部名は、なぜ設計書で内部名を使うのか？

設計書にプロパティーを表示ラベルで書くと、ラベルが変更された時点で設計書と実装が一致しなくなります。プロパティーのオブジェクトタイプと内部名は編集できません。変わらない識別子は内部名だけです。

API経由の連携がある場合は、HubSpot開発者ドキュメントのプロパティーAPIで取得できる内部名を設計書の正とし、表示ラベルは参考情報として併記します。この順序を逆にすると、ラベル変更のたびに連携が壊れたように見える問い合わせが発生します。

設計書に残さないと、後任が触れなくなる項目は何か？

ここまで挙げた項目は、画面からある程度は復元できます。復元が不可能で、かつ無いと手が出せなくなるのが次の3つです。この3つが書かれていない設計書は、量があっても機能しません。

1つめは依存関係です。あるワークフローが更新するプロパティーを、別のワークフローが登録条件に使っている構成は頻出します。片方を止めると、もう片方が静かに動かなくなります。台帳の「更新プロパティー」列と「登録条件で使用するプロパティー」列を突き合わせると、この依存が機械的に抽出できます。プロパティーやパイプラインの保有数には契約内容に応じた上限があり、使用状況はCRMデータ使用状況の確認に記載された画面で確認できます。依存関係の整理と同時に、不要なプロパティーの棚卸しも進めてください。

2つめはカスタムコードアクションと外部連携です。カスタムコードアクションのドキュメントには、実行は20秒以内に完了すること、使用メモリは128MBまでであること、レート制限や429・5XXのエラーで失敗した場合は失敗の1分後から最大3日間、最大8時間の間隔で再試行されることが記載されています。再試行の仕様は、障害発生時の挙動を大きく左右します。コードを読めない後任のために、何を呼び出し、失敗したらどうなるかを日本語で書き残してください。

3つめは廃止判断の材料です。「このワークフローを止めたら誰が困るか」を設計書に書いておかないと、棚卸しのたびに全件を調査し直すことになります。私たちは、個票の「停止した場合の業務影響」欄が空欄のワークフローを、年次の棚卸しで廃止候補として自動抽出する運用にしています。

ワークフローが動かないとき、どの順で切り分けるのか？

切り分けの順序を設計書の付録として用意しておくと、障害時の初動が安定します。私たちが使っている手順は、登録されているかを確認し、登録されているなら経路を確認し、それでも分からなければログの保存期間を疑う、という3段階です。

第1段階では、対象レコードがそもそも登録されているかを確認します。ワークフローのテストの機能で登録条件の充足を確認できますが、同ページには、このテストは現行バージョンに対してのみ実施されると記載されています。過去に登録されたレコードの挙動を調べる場合、現行バージョンでのテスト結果は根拠になりません。

第2段階では、レコードのワークフロー経路とアクションの確認で、個別レコードがどの経路を通ったかを確認します。分岐の誤りはここで見つかります。

第3段階で確認するのがログの壁です。ワークフロー詳細ページでは、アクションログのデータは90日間保存され、登録の履歴データは6か月間保持されます。成功したワークフロー実行のログには1日あたり100,000件の上限があり、アカウントのタイムゾーンの深夜0時から計算されます。上限を超えると、成功ログと情報ログはその日の残りの時間について保存されません。大量実行を行うアカウントでは、「ログが無い」ことが「実行されていない」ことを意味しません。この点を知らないと、原因調査が迷走します。

誤った更新を戻す必要がある場合は、ワークフローによるCRMプロパティー変更の復元が使えます。ワークフローエディターから、特定のワークフローが行ったプロパティー変更を対象に復元できると記載されています。復元の可否と期限は設計書の付録に書いておき、障害時に調べ直さなくて済む状態にしてください。

設計書の運用は、どう回し続けるのか？

設計書が陳腐化する原因は、更新のタイミングが決まっていないことです。私たちは、ワークフローの変更を行う権限と、設計書を更新する義務をセットで運用しています。具体的には、変更作業の前に設計書の該当箇所を更新し、更新後の設計書を添えてレビューを依頼する手順です。設計書の更新漏れは、アカウントのアクティビティー履歴の表示とエクスポートで実際の変更記録と突き合わせれば検出できます。

作成できる本数には上限があるため、棚卸しの頻度も設計に織り込みます。本数の上限は、Marketing・Sales・Service Hub Professionalで最大300、同Enterpriseで最大1000、Data Hub Professionalで最大400、Data Hub Enterpriseで最大1100、Brandsアドオンで追加100です。上限に近づいてから棚卸しを始めると、業務を止めながらの判断になります。

なお、ワークフローとは別系統の自動化としてジャーニー自動化があり、設定の置き場所が分かれます。設計書の台帳は、ワークフローだけでなく自動化全体を対象にしてください。プレースホルダーとしてアクションを保存する機能（プレースホルダーのワークフローアクションの保存）を使った未完成の設定が残っている場合も、台帳に記録しておくと棚卸しで拾えます。自動化全体の考え方はプロセスの自動化に整理されています。

よくある質問（FAQ）

設計書はスプレッドシートとドキュメントのどちらで作るべきですか？

台帳はスプレッドシート、個票はドキュメントをお勧めします。台帳は検索と突合に使うため表形式が適しており、個票は設計意図という文章を書く場所だからです。両方を1つの形式に寄せると、どちらかの用途が犠牲になります。

すでに数百本あるワークフローを、すべて文書化すべきですか？

全件を同じ密度で書く必要はありません。私たちは、稼働中かつ直近3か月に登録実績があるものを優先し、実績ゼロのものは個票を作らず台帳に「実績なし・廃止検討」と記録する運用をお勧めしています。全件を均等に書こうとすると、着手前に頓挫します。

再登録をオンにすれば、過去に取りこぼしたレコードも拾えますか？

拾えません。再登録をオンにしても、過去に遡って新規レコードが登録されることはありません。再登録がオフだった期間に登録済みだったレコードは、手動・自動を問わず再登録できません。過去分を処理したい場合は、手動での登録、または別のワークフローを作る必要があります。

ワークフローをオフにすれば、処理中のレコードは止まりますか？

止まりません。オフにすると新規登録は止まりますが、登録済みレコードは登録されたまま残り、アクションは実行されないものの待機はスキップされません。特定の日にアクションを実行させたくない場合は、オフではなく一時停止日を使ってください。

命名規則を途中で変更してもよいですか？

名称の変更自体は可能ですが、一括で変えるのではなく、棚卸しのタイミングで段階的に移行することをお勧めします。名称を外部の手順書やトレーニング資料で参照している場合、変更が現場の混乱につながります。移行期間中は、台帳に旧名称の列を残してください。

設計書に記載した「停止した場合の業務影響」は、誰が書くべきですか？

技術担当ではなく業務オーナーが書いてください。技術担当が書くと、処理内容の説明になり、業務影響になりません。業務オーナーが書けない場合は、そのワークフローが業務に紐づいていない可能性があり、それ自体が廃止検討の材料になります。

ワークフローの設計書と、基本設計書は分けるべきですか？

分けることをお勧めします。基本設計書はオブジェクト・プロパティー・パイプライン・権限といった構造を扱い、更新頻度が低い文書です。ワークフローは運用の中で頻繁に増減するため、同じ文書に含めると、基本設計書の版管理が煩雑になります。相互参照は台帳の番号で取ります。

ログが残っていない期間の挙動は、どうやって確認すればよいですか？

ワークフローのログからは確認できません。レコード側のプロパティー変更履歴、または外部に送信された記録（メールの送信履歴など）から間接的に推定することになります。アクションログは90日間、登録履歴は6か月間であり、それ以前の実行ログを後から取得する方法の記載は確認できませんでした。長期の監査要件がある場合は、ログを定期的にエクスポートして保管する運用を設計段階で組み込んでください。

ワークフロー設計書の整備を支援が必要な場合

株式会社100は、HubSpotの認定エリートパートナーとして、大手企業の運用引き継ぎにおけるワークフローの棚卸しと設計書の再構築を支援しています。既存ワークフローの依存関係の洗い出しのみ、台帳フォーマットの設計のみといった部分的なご相談もお受けしています。お問い合わせよりご連絡ください。

本記事に記載したHubSpotの仕様・上限値は、2026年10月23日時点の公式ナレッジベースおよび開発者ドキュメントの内容に基づいています。仕様および上限は変更される可能性があるため、設計の際には各公式ページで最新の内容をご確認ください。