Claude Codeの起動中スピナー、実は組織が自社Tipsを混ぜ込める仕様だった──spinnerTipsOverrideを読む

Claude Codeが処理を実行している間、スピナー(処理中インジケータ)の横に「Tip: Use Plan Mode to prepare for a complex request before making changes...」のような豆知識が一定間隔で入れ替わる。何気ない待ち時間の演出に見えるこの機能が、spinnerTipsOverrideという設定キーを通じて、組織が自社製のTipsを組み込みTipsと同じローテーションに混ぜ込める仕組みになっていることは、あまり知られていない。公式ドキュメント「Claude Code settings reference」(2026年8月27日にcurlで確認)と、GitHubの公式CHANGELOG.mdを突き合わせて、この機能がどう育ってきたかを読んだ。

3行まとめ

1. spinnerTipsOverrideは単なるオンオフ設定から出発し、v1.0.112(オンオフのみ)→v2.1.45(カスタムTips配列+excludeDefault)→v2.1.247(2026年8月26日、id/cooldownSessions/priority/tipsFile/label)という段階を経て今の形になった
2. idごとに表示履歴を記録し、cooldownSessions(0〜1000)で再表示までの間隔を、priority(-10〜10)で同着時の優先順位を制御できる。最大200件まで、tips配列と外部tipsFile(最大256KB)を合わせて読み込む
3. labelフィールドでプレフィックスを変更でき、組織は「Tip: ...」ではなく「Acme tip: ...」のように自社ブランドの表示に差し替えられる。デフォルトのプレフィックスは「Tip」

バージョン別の変遷を一覧にする

CHANGELOG.mdの該当4件を時系列で整理すると次の通りだ。

この記事の確認時点でのClaude Code最新版はv2.1.251だが、CHANGELOG.mdをgrepした範囲では、v2.1.247以降にspinnerTipsOverride関連の追加・修正は確認できなかった。

v1.0.112: まずは「消せる」機能として始まった

CHANGELOG.mdをgrepすると、この機能系統で最も古いエントリはシンプルなオンオフ機能だった。

v1.0.112: Added spinnerTipsEnabled setting to disable spinner tips （スピナーのTipsを無効化するspinnerTipsEnabled設定を追加）

この段階では、Tipsは組み込みのものだけがあり、ユーザーができるのは「表示する/しない」の二択だった。

v2.1.45: 自分のTipsを追加できるように

その後、v2.1.45で内容そのものをカスタマイズできる機能が加わった。

v2.1.45: Added spinnerTipsOverride setting to customize spinner tips — configure tips with an array of custom tip strings, and optionally set excludeDefault: true to show only your custom tips instead of the built-in ones （スピナーのTipsをカスタマイズするspinnerTipsOverride設定を追加。tipsにカスタムTips文字列の配列を設定でき、excludeDefault: trueを指定すると組み込みTipsの代わりに自分のTipsだけを表示できる）

この時点では、Tipsは単純な文字列の配列だった。v2.1.122では、このexcludeDefaultが「時間ベースのTips」を正しく抑制していなかったというバグ修正が入っている。

v2.1.247(2026年8月26日): 組織のTips管理機能として完成

直近のv2.1.247で、この設定は単なる「自分のTipsを足す」機能から、組織単位でTipsをローテーション管理する仕組みへと拡張された。

v2.1.247: Added {id, text, cooldownSessions, priority} entries, tipsFile, and label to spinnerTipsOverride, so organizations can rotate their own tips alongside the built-in ones （spinnerTipsOverrideに{id, text, cooldownSessions, priority}のエントリ形式、tipsFile、labelを追加。組織は自社のTipsを組み込みTipsと並べてローテーションできるようになった）

公式設定リファレンスは、各フィールドの制約を次のように詳しく定義している。idは英数字・.・_・-で最大64文字、Tipの表示履歴をこのidに紐づけるため、リストの並び替えをしてもクールダウンの状態は保たれる。textは1行最大500文字で、ANSIエスケープや制御文字は自動的に除去される。cooldownSessionsは0〜1000の範囲で、そのTipを再表示するまでに待つセッション数(デフォルト0)。priorityは-10〜10の範囲で、同じだけ未表示が続いているTips同士が競合したときの優先順位(デフォルト0、値が大きいほど優先)。

Claude Code puts your tips in the same rotation as the built-in ones: it picks the tip that has gone unshown the longest, skips tips still in their cooldown, and breaks ties by priority. （Claude Codeはあなたのtipsを組み込みtipsと同じローテーションに入れる。最も長く表示されていないtipを選び、クールダウン中のtipsはスキップし、同着の場合はpriorityで決める）

tipsFileとlabel:外部ファイル読み込みとブランディング

v2.1.247で追加されたtipsFileは、Tipsの内容を設定ファイルとは別の外部JSONファイルに切り出せる機能だ。

tipsFile: an absolute or ~/ path to a local JSON file holding an array of the same entries, or an object with a tips array, up to 256 KB. Claude Code reads the file once per process, so it loads your edits at the next start.

（tipsFileは、同じ形式のエントリの配列、またはtips配列を持つオブジェクトを格納したローカルJSONファイルへの絶対パスまたは~/パス。最大256KB。Claude Codeはプロセスごとに1回このファイルを読むため、編集内容は次回起動時に反映される）

ただしtipsFileはサーバー管理設定(server-managed settings)経由では設定できず、代わりにインラインのtipsを使うか、ディスク上のmanaged-settings.jsonにパスをデプロイする必要があると注記されている。

labelフィールドは表示プレフィックスを最大40文字まで変更できる機能で、デフォルトは組み込みTipsと同じ「Tip」。設定リファレンスが挙げる例では、次のようにユーザー設定へ書くと「Acme tip: ...」という表示に変わる。

{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}

この例では、プレーンな文字列のTipはデフォルト値(即座に再表示されうる)になる一方、gateway-errorsというidを持つTipは5セッションのクールダウンと優先度2を持つ。設定リファレンスの解説によれば、無効なエントリが混じっていてもClaude Codeは警告を出しつつスキップするだけで、設定ファイル自体は拒否されない仕組みになっている。

スコープの違いが地味に効く

もう1つ、リファレンスに明記されている制約として、設定ファイルの種類によって使える機能に差がある点がある。

Claude Code honors tip objects, tipsFile, label, and excludeDefault from user settings, the --settings flag, and managed settings; from project and local settings it reads plain string tips only.

（Claude Codeは、ユーザー設定・--settingsフラグ・管理設定からはtipオブジェクト・tipsFile・label・excludeDefaultを尊重するが、プロジェクト設定とローカル設定からはプレーンな文字列のtipsのみを読む）

つまり、リポジトリに.claude/settings.jsonとして置くプロジェクト設定では、構造化されたTipsオブジェクト(クールダウンや優先度付き)は使えず、単純な文字列しか追加できない。組織単位でクールダウンや優先度まで制御したいなら、ユーザー設定または管理設定側に置く必要がある。

隣接機能「spinnerVerbs」——動詞のローテーションも同じ発想

設定リファレンスを読み進めると、spinnerTipsOverrideのすぐ次にspinnerVerbsという設定が定義されていた。ターン処理中にスピナーが表示する「Accomplishing」「Architecting」「Baking」といった動詞のローテーションを、mode: "append"(組み込みの動詞に追加)またはmode: "replace"(自分の動詞だけに置き換え)で調整できる機能だ。tipsのようなcooldownSessionsやpriorityは無く、単純な配列と2つのモードだけのシンプルな設計になっている。Tips機能ほど作り込まれていないものの、「スピナー周りの表示を組織やユーザーがカスタマイズできるようにする」という同じ設計思想が、Tips以外の場所にも及んでいることが分かる。

tipsFileがサーバー管理設定で使えない理由

前回の確認時点では「セキュリティ上の制約か実装上の制限か分からない」としていた、tipsFileがサーバー管理設定経由で使えない理由について、Claude Codeの別のドキュメント「Configure server-managed settings」を確認したところ、理由を推測できる記述があった。サーバー管理設定は「Claude CodeがAnthropicのサーバーから起動時に取得し、セッション中は1時間ごとに再取得する」という、ネットワーク経由で配信される仕組みだと説明されている。これに対しtipsFileはローカルファイルシステム上の絶対パスを指す設定であり、サーバー側からデバイスのローカルパスを解決する術がないため、構造的に対応できないと理解するのが自然だ。ドキュメントが「tipsFileはサーバー管理設定を使わずインラインのtipsか、ディスク上のmanaged-settings.jsonにパスをデプロイせよ」と案内しているのも、この配信経路の違いと整合する。ただし、この理由づけはドキュメント上に明記された公式説明ではなく、2つのドキュメントの記述を突き合わせたこの記事側の推測である点は明記しておく。

この機能を実際には使ったことがない

この記事は公式ドキュメント2件とCHANGELOG.mdの記述のみに基づいており、自分自身がspinnerTipsOverride・spinnerVerbsを実際に設定して動作を確認したわけではない。当サイトでのClaude Code運用でも、これらの設定を使ったことは今のところない。組み込みTips・カスタムTips・組織管理Tipsが実際の画面でどう混ざって表示されるかの見た目は、ドキュメントの記述から推測しているに留まる。

感想・指摘はコメント欄へ。