flag-schedule

flag-schedule

GrowthBook のフィーチャーフラグルールに、時間指定の有効期間を追加します。スケジュールされたルールは、開始時刻に自動的に有効になり、終了時刻に自動的に無効になります。毎回手動で公開する必要はありません。

スケジュールは force と rollout のルールタイプに適用されます。experiment-ref または safe-rollout ルールには適用されません。

すべての API 呼び出しは、同梱のヘルパー ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call を経由します。GB_API_KEY を環境変数に設定するか、/growthbook:gb-setup によって ~/.config/growthbook/.env に書き込む必要があります。

スケジュールの仕組み

GrowthBook は、ルールで 2 つのスケジュール方式をサポートしています。

シンプルなスケジュール（ルール作成時の schedule フィールド） — 推奨される方法です。startDate および／または endDate を ISO 8601 タイムスタンプで指定します。サーバーが基盤となる scheduleRules を自動的に設定します。

レガシーの scheduleRules — [start, end] という 2 要素配列で、各要素は { timestamp: "<ISO 8601 or null>", enabled: <bool> } です。引き続き API で受け付けられますが、新しいルールではシンプルな schedule フィールドのほうがすっきりしています。

OFF 状態の仕組み

スケジュールされたルールは、フラグレベルの切り替えではなく、ルールレベルの仕組みです。ルールが非アクティブな期間（有効期間外）には、評価時にスキップされます。フラグはルール順で次の項目に進み、最終的に defaultValue に到達します。

つまり、次のようになります。

• 有効期間中、ルールは ON の値（ブール値フラグの場合は "true"）を返す必要があります。
• ルールに一致するものがない場合の OFF 状態は defaultValue です。公開する前に、正しく設定されていることを確認してください。
• 新しいルールでは、スケジュールされたルールを rules 配列の最後に配置してください。そうすれば、スケジュールが無効なときに、その下にあるルールが誤って ON の値を返すことはありません。既存のルールの場合は、その下にあるルールを確認してください。このルールより下に一致する値を返すものがあると、スケジュールがオフのときにそのルールが適用されます。

ワークフロー

パス A — スケジュール付きの新しいルールを作成する

1. フラグを取得します：

   gb-call GET /api/v2/features/<flag-id>
   

   valueType、defaultValue、environmentSettings、現在のルールを確認します。

   対象の環境が有効になっていることを確認します。 environmentSettings.<env>.enabled が false の場合、スケジュールされたルールは何も実行せずに終了します。ユーザーに次のように警告してください：

   「フラグは現在 <env> で無効になっています。フラグが有効になるまで、スケジュールされたルールは実行されません。flag-toggle から有効にしてください（この変更と同じドラフトに含めることができます）。」

   defaultValue が OFF 状態であることを確認します。 boolean フラグの場合は "false" である必要があります。そうでない場合は、ユーザーに次のように警告してください：

   「スケジュールされたルールが無効なとき、フラグは <defaultValue> を返します。これが意図した OFF 状態ですか？そうでない場合は、先に flag-default-value から更新してください。」

   ルールの順序を確認します。 新しいルールは最後に追加されます。その上にある既存のルールがすべてのユーザーに無条件で ON の値を返す場合、スケジュールより先に実行されます。ユーザーに警告し、追加後に flag-rules からルールの順序を確認するよう提案してください。

2. スケジュールの時刻を収集します：

   次の情報を確認します：

   • 開始時刻（または「すぐに」の場合は null）
   • 終了時刻（または「期限なし」の場合は null）
   • ユーザーが時刻の文字列で明示的に指定していない場合は、ユーザーのタイムゾーン

   API はタイムゾーンオフセット付きの ISO 8601 を受け付けます。ユーザーの現地時間をそのまま使用し、UTC への変換は不要です。該当する日付の正しいオフセットを使用してください（夏時間を考慮します）：

   "tomorrow at midnight" in US Eastern (summer, EDT) → "2026-05-30T00:00:00-04:00"
   "right after Christmas" in US Eastern (winter, EST) → "2026-12-26T00:00:00-05:00"
   

   自然言語による時刻の場合は、相対日付（「明日」、「次の金曜日」）の基準としてコンテキストの currentDate を使用します。「クリスマスのすぐ後」や「セールの終了時」など、曖昧な表現の場合は、先に正確な日時をユーザーに確認してください。ペイロードを作成する前に、解決した日時を完全な形で必ずユーザーに確認してください。

3. ペイロードを作成して送信します：

   事前に value がフラグの valueType（手順 1 で取得）に適合することを検証します。boolean フラグには "true"／"false"、number フラグには数値として解析できる値、json フラグには有効な JSON を指定する必要があります。

   echo '{
     "rule": {
       "type": "force",
       "value": "<on-value>",
       "description": "<optional>",
       "enabled": true,
       "allEnvironments": false,
       "environments": ["<env-id>"]
     },
     "schedule": {
       "startDate": "2026-05-30T00:00:00-05:00",
       "endDate": "2026-12-26T00:00:00-05:00"
     }
   }' | gb-call POST /api/v2/features/<flag-id>/revisions/new/rules -
   

   その側に境界がない場合は、startDate または endDate を省略します。

4. 返された version を取得します。flag-publish に引き継ぎます。

パス B — 既存のルールにスケジュールを追加する

1. フラグを取得してルールを特定します：

   gb-call GET /api/v2/features/<flag-id>
   

   ルールの一覧を表示します。スケジュールを設定するルールの id（UUID）をユーザーに確認します。配列内での現在のルールの位置を確認します。最後でない場合は、このスケジュールが無効なときに、その下のルールが意図しない値を返さないか確認します。

2. スケジュールの時刻を収集します（パス A の手順 2 と同じ）。

3. scheduleRules パッチを作成します：

   {
     "scheduleRules": [
       { "timestamp": "2026-05-30T00:00:00-05:00", "enabled": true },
       { "timestamp": "2026-12-26T00:00:00-05:00", "enabled": false }
     ],
     "scheduleType": "schedule"
   }
   

   • 要素 0：開始イベント（enabled: true — この時刻にルールが有効になります）
   • 要素 1：終了イベント（enabled: false — この時刻にルールが無効になります）
   • その境界を設定しない場合は、タイムスタンプに null を使用します（開始または終了の境界なし）
   • scheduleType は "schedule" にする必要があります

4. パッチを適用します：

   echo '<patch>' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id> -
   

5. 返された version を取得します。flag-publish に引き継ぎます。

パス C — ルールからスケジュールを削除する

echo '{
  "scheduleRules": [
    { "timestamp": null, "enabled": true },
    { "timestamp": null, "enabled": false }
  ],
  "scheduleType": "none"
}' | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id> -

すべてのタイムスタンプを null に設定し、scheduleType: "none" にすると、スケジュールが解除されます。ルールは常に有効になります（enabled フィールドと条件の制約は受けます）。

注意事項

• ドラフトのバージョンを引き継ぐ。 このセッションで以前の書き込みスキルからバージョン番号を引き継いでいる場合は、new ではなく、明示的にその番号を使用してください（例：.../revisions/42/rules）。これにより、すべての変更が同じドラフトにまとまります。新たに開始する場合は new を使用してください。
• OFF 状態はトグルではなく defaultValue です。 スケジュールはルール単位で機能します。有効期間外はルールがスキップされ、フラグは defaultValue にフォールスルーします。公開前に、defaultValue が意図したオフ状態であることを必ず確認してください。
• 新しいスケジュール設定ルールは最後に配置する。 ルールは上から下へ評価されます。スケジュール設定ルールが非アクティブの場合、そのルールは単にスキップされます。その下に ON 値を無条件で返す別のルールがあると、非アクティブ期間中にそのルールが適用されます。新しいルールは最後に配置するのが最も安全です。
• API はタイムゾーンオフセット付きの ISO 8601 を受け付けます。 ユーザーの現地時間をオフセット形式で指定してください（例："2026-12-26T00:00:00-05:00"）。UTC への変換は不要です。ペイロードを作成する前に、解決した日時をユーザーに確認してください。タイムゾーンを勝手に想定してはいけません。
• 自然言語で指定された日時は明確に解決する。 相対日付（「明日」、「次の金曜日」）には、コンテキストの currentDate を使用してください。「クリスマスのすぐ後」、「セール終了時」のように曖昧な表現の場合は、続行する前に正確な日付と時刻をユーザーに確認してください。
• scheduleRules は2要素の配列です。 要素0は開始イベント（enabled: true）、要素1は終了イベント（enabled: false）です。サーバーはこの形式を強制します。任意のイベントを並べたリストではありません。
• 新しいルールには schedule フィールドを、既存ルールへのパッチには scheduleRules を使用してください。
• スケジュール設定ルールでは enabled: true が必須です。 スケジュールは評価サイクル内でルールがアクティブになるタイミングを制御しますが、ルールの enabled: false はスケジュール全体を無効にします。
• 公開するとスケジュールが有効になります。 承認によって公開が遅れ、リビジョンが有効になる前に開始時刻を過ぎた場合、ルールはスケジュールされた時刻ではなく、公開時に直ちに有効になります。
• 複数段階の段階的なロールアウトには flag-ramp を使用してください。 このスキルが扱うのは、オン／オフの期間のみです。

使用するエンドポイント

• GET /api/v2/features/:id — フラグと現在のルールを取得する
• POST /api/v2/features/:id/revisions/new/rules — schedule フィールドを指定してルールを作成する（本文には rule と schedule を含む）
• PUT /api/v2/features/:id/revisions/new/rules/:ruleId — 既存ルールの scheduleRules と scheduleType にパッチを適用する

引き継ぎ先

• flag-targeting — スケジュールと併せてルールのターゲティング条件を作成する
• flag-ramp — 対象範囲を段階的に拡大する複数段階のロールアウトを設定する
• flag-rules — スケジュール設定ルールを追加した後にルールを並べ替える
• flag-publish — ドラフトを公開する