📚 ナレッジベース
Claude_Code_容量不足対策
最終更新 2026年05月09日 ／ 21_ナレッジベース/プロダクト開発/Claude_Code_容量不足対策.md
Claude Code 容量不足対策・省エネ完全マニュアル
「容量問題で作業を止めない・全セッション総量も最適化する。」
Per-Session（Context Window）+ Account-Wide（5h/週次）の両方を仕組みで管理。
30秒で全体像
| 観点 | 一言 |
|---|---|
| 核心 | StatusLine常時表示 + 自動警告Hook + /handoff引き継ぎ + 省エネ法 |
| キーワード | /context / /compact / /handoff / Codex resume / fork / Subagent / Plan mode / Skills |
| 使う人 | Claude Code / Codex ユーザー / 並行セッション運用者 |
| 読了目安 | 10分（マニュアル） |
2つの容量問題（区別重要）
| 問題 | 範囲 | 制限 | 対策 |
|---|---|---|---|
| Context Window | 1セッション内 | 200K（標準）/ 1M（Opus 4.7等） | /compact, /handoff, 省エネ |
| アカウント使用量 | 全セッション合計 | Max 20x: 5h・週次 | /usage, セッション終了, API併用 |
Codex版の結論（2026-05-09確認）
Codexも1セッションが長くなると、文脈量が増えて重くなる。内部では自動圧縮が入ることがあるが、重要な作業では Vault保存 + 引き継ぎメッセージ生成 + 新セッション移行 を標準にする。
ローカル確認結果
| 項目 | 結論 |
|---|---|
~/.codex / ~/.Codex |
commands/ ディレクトリは見当たらない |
Claude Code形式の ~/.claude/commands/handoff.md |
既存あり |
| Codex CLI 標準 | codex resume / codex fork は存在 |
| Codex用 handoff | source-command-handoff skill が存在。/handoff または「引き継ぎメッセージ作って」で実行対象 |
Codexでの使い分け
| やりたいこと | 使うもの | 注意 |
|---|---|---|
| 同じセッションを続ける | codex resume --last |
文脈量も引き継ぐため、重さ解消にはならない |
| 既存セッションから派生する | codex fork --last |
分岐には使えるが、引き継ぎ文作成とは別 |
| 新セッションへ軽く移る | /handoff or 「引き継ぎメッセージ作って」 |
SCALE標準。Vault更新 + コピペ用要約 |
| 長くなりすぎた時 | 新セッション + handoff本文貼付 | 最も安全 |
SCALE標準運用
- 70%前後で「容量が膨らんできた」と警告する
- 75%超なら要点をVaultへ保存し、handoff準備に入る
- 85%超なら
/handoff相当を実行して新セッションへ移る - システム作業中は、最新基準点・changelog・作業ログを更新してから引き継ぐ
- 新セッションでは
AGENTS.md+ 作業ログ + 対象システムの最新基準点を読む
追加方針: 容量問題はhandoffで解消する
大串方針（2026-05-09）
Codexの長文セッション問題は、resume/forkで延命するより、handoffで新セッションへ移して解消する。
| 状況 | 対応 |
|---|---|
| 会話が長くなった | まず重要情報をVaultへ反映 |
| まだ作業が続く | /handoff 相当で引き継ぎ本文を生成 |
| 新セッションへ移る | 引き継ぎ本文を貼って再開 |
| 旧セッション | 必要なら参照のみ。作業継続は新セッション側 |
resume は「前の会話に戻る」用途、fork は「分岐」用途。
容量解消の標準手段は handoff + 新セッション とする。
Codexにおける注意
- Codexネイティブの「
~/.codex/commands/handoff.md型カスタムコマンド」は、2026-05-09時点のローカル確認では見当たらない - ただしこの環境には
source-command-handoffskill があるため、会話上で/handoffと言われたら同等フローを実行できる resumeは便利だが、長い会話をさらに続ける用途。容量対策には「要約して新規セッション」が強い
重要: 画像送付ルール（必読）
制限
- Claude API は画像の最大寸法を2000pxに制限
- 複数画像セッションでこの制限が発動
- 超えると以降の全プロンプトが詰まる（/handoff も /context も使えない）
解決: 完全自動リサイズ実装済み（2026-05-05）
もう手動リサイズ不要！ スクショ撮ったら自動で1800pxに縮小される仕組み完成。
仕組み
スクショ撮影 → ~/Desktop or ~/Downloads に保存
↓ macOS LaunchAgent が WatchPaths で検知
↓ auto_resize_screenshots.sh 実行
↓ 2000px超のPNG/JPG/JPEG を 1800px に自動リサイズ
↓ macOS 通知 "📸 自動リサイズ"
設置ファイル
| ファイル | 役割 |
|---|---|
~/.claude/scripts/auto_resize_screenshots.sh |
リサイズスクリプト |
~/Library/LaunchAgents/com.scale.auto-resize-screenshots.plist |
LaunchAgent設定 |
~/.claude/scripts/auto_resize.log |
リサイズ履歴 |
監視対象
~/Desktop（Macスクショのデフォルト保存先）~/Downloads（ブラウザDLの画像）
動作仕様
- 過去2分以内に作成された PNG/JPG/JPEG を対象
- 2000px 超えのみリサイズ（小さい画像は触らない）
- リサイズ後 1800px（縦横どちらか長い方）
- 古いファイル（2分以上前）は対象外（履歴の写真等は触らない）
設定変更コマンド
# リサイズサイズ変更
vi ~/.claude/scripts/auto_resize_screenshots.sh
# → MAX_SIZE=1800 を変更
# 一時停止
launchctl unload ~/Library/LaunchAgents/com.scale.auto-resize-screenshots.plist
# 再開
launchctl load ~/Library/LaunchAgents/com.scale.auto-resize-screenshots.plist
# ログ確認
cat ~/.claude/scripts/auto_resize.log
手動リサイズ（自動が動かない時の予備）
Mac Preview.app（GUI）
1. 画像を Preview で開く
2. メニュー: ツール → サイズを調整
3. 横幅 1500px に変更（高さ自動）
4. 保存
ターミナル（一括処理）
# 単一ファイル
sips -Z 1800 ~/Desktop/screenshot.png
# Desktop の全PNG一括
for f in ~/Desktop/*.png; do sips -Z 1800 "$f"; done
詰まった時の復旧
- 全プロンプトが「image dimension limit」エラー → そのセッション継続不可
- 取れる手段:
1. transcript ファイルを直接読み（~/.claude/projects/.../*.jsonl）
2. 別セッションで Claude に内容抽出させる
3. 手動で引き継ぎメッセージ作成 → 新セッションへ - 詳細: 過去の事例（2026-05-05 SCALE CRM Zoom Phone 連携セッション詰まり）
教訓（2026-05-05）
- 1セッションで複数画像 + 1枚でも2000px超 = 全プロンプト詰まる
- /handoff も使えなくなる（最悪パターン）
- 手動リサイズの徹底は人間に無理 → 自動化が唯一の解
- LaunchAgent で OS レベルの自動化 = 確実
重要: Desktop版 vs CLI版 の違い
| 機能 | CLI版 (claude コマンド) |
Desktop版 (Mac/Winアプリ) |
|---|---|---|
| StatusLine 常時表示 | ⭕ 動く | ❌ 未対応 |
| Hook自動警告 | ⭕ 動く | ⚠️ 推定誤差大・無効化推奨 |
| コンテキストウィンドウ表示 | ❌ なし | ⭕ 標準搭載・正確 |
| /handoff コマンド | ⭕ 動く | ⭕ 動く |
| /context | ⭕ 動く | ⭕ 動く |
| /compact | ⭕ 動く | ⭕ 動く |
Desktop版の正確な容量確認方法
画面下部「コンテキストウィンドウ XX/1.0M (XX%)」表示 が公式・正確。
これがあるのでHook推定は不要。
容量推定の限界（2026-05-04 判明）
独自の count_token●●●●●● はセッションのcontent typeで誤差大:
- 日本語テキスト多: 比較的正確
- コード/ファイル読込多: 過大評価（最大3倍超）
- → 正確な計算は Claude API 内部実装不可
- → Desktop版ではHook停止・標準UIで確認が結論
Hook無効化（2026-05-04 適用）
~/.claude/settings.json から context_warn.sh を削除済み。
CLI版でStatusLine使う場合のみ context_status.sh が動く。
自動化の仕組み（実装済）
① StatusLine 常時可視化（CLI版のみ）
画面下に常時表示:
🟢 35% (OK) | O4.7-1M 1M | 📂 scale-base
🟡 65% (注意) | S4.7 200K | 📂 scale-lead → /context
🟠 80% (警戒) | O4.7-1M 1M | 📂 scale-base → /compact
🔴 90% (危険) | O4.7-1M 1M | 📂 scale-base → /handoff!
- モデル別 Context Window 自動判定（200K vs 1M）
- 較正済（実測 53% = 表示 53%）
② UserPromptSubmit Hook 自動警告
入力毎に自動チェック:
- 60%超 → 🟡 注意メッセージ挿入
- 75%超 → 🟠 「/compact 実行推奨」
- 85%超 → 🔴 「/handoff 実行推奨」
- Claude が応答冒頭/末尾に必ず警告を含める
③ /handoff スラッシュコマンド
ユーザー: /handoff
↓
コピペ可能な引き継ぎメッセージ生成（自己完結形式）
↓
新セッションに貼り付け → 即作業再開
④ システム別 Compact Instructions
/compact 時に保持すべき情報を CLAUDE.md に明示:
- scale-base / 株式会社SCALE 設定済
⑤ Vault作業ログテンプレ
_Templates/作業ログ.md をベースに 00_Inbox/作業ログ_YYYY-MM-DD.md に蓄積
スラッシュコマンド完全リファレンス
Context・容量管理
| コマンド | 用途 | 使うタイミング |
|---|---|---|
/context |
現在の使用量・内訳表示 | StatusLineが🟡になったら |
/cost |
トークン数・推定コスト | 振り返り時 |
/usage |
アカウント全体（5h/週次） | 1日1回確認 |
/compact |
自動圧縮 | 75%超 |
/compact focus on "X" |
特定領域を保持して圧縮 | 75%超・作業途中 |
/clear |
セッション完全リセット | 新タスク開始時 |
セッション・メモリ
| コマンド | 用途 |
|---|---|
/resume |
前のセッション再開 |
/branch |
セッションをフォーク |
/memory |
Auto Memory表示 |
/handoff |
引き継ぎメッセージ生成（カスタム） |
設定・モデル
| コマンド | 用途 |
|---|---|
/model [name] |
モデル切替（Haiku→Sonnet→Opus） |
/agents |
サブエージェント一覧 |
/commands |
スラッシュコマンド一覧 |
/hooks |
Hook設定確認 |
/mcp |
MCP server コスト確認 |
ワークフロー
| コマンド | 用途 |
|---|---|
/batch |
大規模変更を5-30並列worktreeで実行 |
/loop [interval] |
プロンプトを定期実行 |
/debug |
デバッグログ有効化 |
/refresh-vault |
Vault状態再ロード（カスタム） |
キーボードショートカット
| キー | 機能 |
|---|---|
| Ctrl+C | Claude を中断（処理停止） |
| Ctrl+D | セッション終了 |
| Esc (1回) | 現在の応答キャンセル |
| Esc Esc (2回) | ファイル編集ロールバック（checkpoint） |
| Shift+Tab | パーミッションモード切替（4段階循環） |
| ↑↓ | コマンド履歴 |
| Tab | コマンド補完（/後） |
Shift+Tab 4段階モード
- Default: 毎回確認
- Auto-accept edits: ファイル編集OK・コマンドは確認
- Plan mode: 読み取り専用・実行前計画提示 推奨
- Auto mode: 安全チェック付き完全自動
容量省エネ法 TOP 15
🅰️ Per-Session（Context Window）省エネ
1. CLAUDE.md を薄く保つ ⭐ 最重要
- 最初の200行 / 25KB だけが毎回ロードされる
- 詳細は Skills（
.claude/skills/）に分散 - グローバル
~/.claude/CLAUDE.mdも最重要だけ
2. MCP tools の deferred 設定 ⭐
- MCP ツール定義は名前だけロード（必要時に詳細取得）
- 設定ファイルで
deferred: true /mcpで per-server コスト確認
3. Skills の disable-model-invocation: true
- Claude が自動呼び出ししない設定
- 手動
/skill-nameだけで起動 - 説明が context に常駐しない
4. Read() は最小単位で
Read(file.md, limit: 500, offset: 0) # 最初の500行だけ
- 全ファイル読みは避ける
grepで事前絞り込み
5. Subagent 委任 ⭐
/batchで worktree agent に大規模作業を委任- 親セッションに結果サマリだけ返却
- 親が膨張しない
6. Plan mode の活用
- Shift+Tab 2回 → Plan mode
- 実行前に計画提示 → 無駄な試行が減る
- 最初の設計が固まれば後の効率UP
7. /compact の選別圧縮
/compact focus on "現在のscale-baseのhome画面修正"
- 古い会話だけ削除、現在の作業は保持
/clearより柔軟
8. システム別 Compact Instructions
各CLAUDE.mdに「圧縮時の優先保持ルール」を書く
- 編集中ファイル / changelogスタンプ / バックアップID 等
9. Read重複の回避
同じファイルを何度も読み込まない:
- 1回読んだらメモして覚える
- 必要なら一部だけ再Read
10. Worktree mode
複数タスク = 複数worktree = 複数セッション
- 親1つで管理 → 容量N分の1
🅱️ Account-Wide（5h/週次）省エネ
11. Model downgrade（タスク別）
| タスク | 推奨モデル |
|---|---|
| 軽い文章作成・相談 | Haiku |
| 標準的な開発・分析 | Sonnet |
| 複雑な意思決定・大規模設計 | Opus |
/model haiku で切替
12. 不要セッション即終了
Ctrl+Dでセッション終了- 開きっぱなしは課金対象外だが、5h窓に残る場合あり
13. /loop で自動実行
- 寝てる間に進める作業は
/loop設定 - Scheduled Tasks MCPで夜間実行
14. API併用（Max超え対策）
export ANTHROPIC_API_KEY="<your-api-key>"
# 別枠課金で実行
15. キャッシュ最適化
- CLAUDE.md先頭部分が自動キャッシュ対象
- 2回目以降のキャッシュ済みトークンは 90% オフ
- 静的コンテンツを先頭に集中
運用フロー
通常モード（容量50%未満）
StatusLine 🟢 → 普通に作業
注意モード（50-75%）
StatusLine 🟡 → /context で正確値確認 → 継続
警戒モード（75-85%）
StatusLine 🟠 → /compact focus on "現在の作業" → 圧縮後継続
危険モード（85%+）
StatusLine 🔴 → /handoff → コピペ → /clear or 新セッション
実践チェックリスト
毎日
- [ ]
/usageで5h/週次の残量確認（朝1回） - [ ] 不要セッションを
Ctrl+D終了 - [ ] CLAUDE.md 先頭25KBに重要情報集約
大規模タスク前
- [ ]
/contextでカレント使用量確認 - [ ] Plan mode（Shift+Tab ×2）で計画確認
- [ ] Subagent 委任可否検討
- [ ] バッチ依頼にまとめる
システム編集時
- [ ] グローバルCLAUDE.md確認
- [ ] 該当システムCLAUDE.md確認
- [ ] バックアップ取得
- [ ] 編集後 changelog 追記
デプロイ前
- [ ]
/compactで古い探索結果削除 - [ ]
/batchで並列実行検討 - [ ] 本番URL動作確認
1日終了時
- [ ] 作業ログ_YYYY-MM-DD.md 更新
- [ ] 翌日の最重要タスク決定
効果見込み
| 指標 | Before | After |
|---|---|---|
| セッション中断による作業ロス | 週3-5回 | 週0-1回 |
| 引き継ぎ時間 | 10-30分 | 2-5分 |
| 1日の総トークン消費 | 100% | 40-60% |
| 5h制限到達回数 | 週2-3回 | 週0-1回 |
| 実質開発時間/日 | 2-3h | 5-6h |
較正の物語（2026-05-04）
問題
最初の Hook 実装で 117% 表示（明らかに過大）
原因
- file_size /13 で計算 → JSON構造分も含まれる
- Context Window 200K前提 → 実は Opus 4.7 [1m] = 1M
- 計算divisor が不正確
較正プロセス
- JSONLパース改善（Python）
- 1Mモード自動判定追加
- 実測 /context: 534,500 と比較
- 経験的較正係数:
chars * 1.25 + 35,000 overhead - 結果: 推定 536,433 vs 実測 534,500（誤差 0.4%）
教訓
- Hook計算は推定値、
/contextが正確 - 但し較正されてれば警告タイミングは十分機能
- モデルとContext Windowの組み合わせを把握
設定ファイル一覧
グローバル設定
| ファイル | 役割 |
|---|---|
~/.claude/CLAUDE.md |
容量管理ルール記載 |
~/.claude/settings.json |
StatusLine + Hook 設定 |
~/.claude/scripts/context_status.sh |
StatusLine 表示スクリプト |
~/.claude/scripts/context_warn.sh |
自動警告 Hook |
~/.claude/scripts/count_token●●●●●● |
トークン計算（較正済） |
~/.claude/commands/handoff.md |
/handoff 定義 |
システム別 CLAUDE.md
| システム | パス | Compact Instructions |
|---|---|---|
| SCALE Base | ~/.../scale-base/CLAUDE.md |
✅ 追加済 |
| SCALE CRM等 | ~/.../株式会社SCALE/CLAUDE.md |
✅ 追加済 |
Vault
| ファイル | 役割 |
|---|---|
_Templates/作業ログ.md |
テンプレート |
00_Inbox/作業ログ_YYYY-MM-DD.md |
日次ログ |
21_ナレッジベース/プロダクト開発/Claude_Code_容量不足対策.md |
このマニュアル |
関連ナレッジ
改訂履歴
| 日付 | 内容 |
|---|---|
| 2026-05-03 | 初版作成。StatusLine + /handoff + Compact Instructions + 作業ログテンプレ の5つを実装 |
| 2026-05-09 | Codex版の容量管理・handoff運用を追記。~/.codex にcommands形式は見当たらず、source-command-handoff skillで代替する方針 |
| 2026-05-09 | 大串方針「容量問題はhandoffで解消」を追記。resume/fork延命ではなく、handoff + 新セッションを標準化 |
| 2026-05-04 | 較正完了（実測 53% = 推定 53%、誤差 0.4%）。1Mコンテキスト自動判定追加。スラッシュコマンド全リファレンス・キーボードショートカット・省エネ法TOP15・実践チェックリスト追加 |
| 2026-05-04 | Hook推定の不正確性判明（content type依存で大ぶれ）→ Hook無効化。Desktop版「コンテキストウィンドウ」標準表示が正確と確認 |
| 2026-05-05 | 画像送付ルール追加（2000px制限）。SCALE CRM Zoom Phone セッション詰まり事例から学び |
| 2026-05-05 | 画像自動リサイズ完成（LaunchAgent + auto_resize_screenshots.sh）。スクショ撮るだけで自動1800px化。手動リサイズ撤廃 |