pacing-playbooklisted

# Pacing Playbook — 別把 bucket 燒燙 設定 agents / workflows、要 fan-out 之前讀這份。目標只有一個:**不觸發 Anthropic 的 acceleration-limit / short-burst 節流**,避免「燒一堆 token 換 0 產出」。 ## 機制(為什麼會撞) 官方 rate-limit 文件 + Claude Code 行為的三個事實: 1. **Token bucket，連續回填**:容量是持續滴回來的，不是整點重置。暴衝把 bucket 抽乾 = 變「燙」。 2. **Acceleration limit**:「a **sharp increase in usage**」會吃 429。官方藥方原文是 **"ramp up gradually and maintain consistent usage patterns"**。 3. **Short bursts**:「short bursts of requests can exceed the limit」——一次噴一堆並發就是 burst。 三種錯誤別混: | 類型 | 是什麼 | 訊號 | 對策 | |------|--------|------|------| | 用量上限 (quota) | 5h / 週 budget | "hit your limit" | 等時鐘重置 | | 429 rate / acceleration | RPM/TPM 或暴衝 | 帶 `retry-after` | **讀 header 等**、ramp 漸進 | | 529 overloaded | 全站容量，**非你的額度** | "Server is temporarily limiting requests (not your usage limit)" | 等，**別狂 retry** | > 看到 529 時，Claude Code **已自動退避失敗好幾次才顯示**。你再 hammer = 純浪費。 > `retry-after` 的定義是「earlier retries **will fail**」——早一秒都 fail，所以別瞎猜秒數。 ## 規則(怎麼不撞) 按效益排序: 1. **串行 > fan-out**。對「N 個同類小任務」(批次診斷、批次改檔)，逐個處理 + idempotent guard 跨窗口收斂，**結構上不可能 burst**。慢，但會完成。這是最強的一條。 2. **一次只跑一個 workflow**。累積 back-to-back launch 是 acceleration-limit 元兇。 3. **讀 `retry-after`，別猜**。它給精確秒數。 4. **Ramp gradually + consistent pattern**(官方原話)。別背對背 launch，節奏均勻。 5. **小並發**(3-4，不要 16)。壓掉 short-burst。 6. **Idempotent guard**。讓串行慢跑可中斷、可續、零重工——慢就不再是問題。 7. **Probe before commit**。要 fan-out 一大批前，先用 1 個探一下節流退了沒，退了才丟整批。 ## 工具選擇 gate — fan-out 之前先問(hook 照不到的那一層) pacing-guard hook 只數**主迴圈發出的啟動**;一個 w