【初心者向け】Claude Codeで「Context left until auto-compact: 15%」が出たときの対処法

こちらの記事は「MEDLEY Summer Tech Blog Relay」の4日目の記事です。

Claude Codeでコンテキスト警告が出たらどうする？

Claude Codeで長時間作業していると「⚠️ Context left until auto-compact: 15%」のような警告が出る。この対処法を3つのステップで解説する。

STEP 0: 常時監視（基礎編）

概要

コンテキストの使用状況を常に可視化することで、警告が出る前に計画的に対処できる。

設定方法

Claude Codeのステータスバーにコンテキスト使用状況を表示する設定：

{
    "statusLine": {
        "type": "command",
        "command": "npx -y ccusage statusline",
        "padding": 0
    }
}

これでステータスバーに

 Opus 4.1 | 💰 $3.10 session / $229.22 today / $56.71 block (1h 32m left) | 🔥 $22.19/hr | 🧠  ⧉ In 
  51,090 (26%)  

のような表示が追加される。この%がコンテキスト使用量。自動compactがかかるその前に対処するのがコツ。

STEP 1: 都度対応（初級編）

概要

最も基本的な対処法。警告が出たら手動で引き継ぎ資料を作成し、新しい会話で読み込む。

警告が出たときの手順

1. 引き継ぎ資料の作成

もっとも乱暴な指示がこちら。

コンテキストなくなりそうだから引き継ぎ資料つくって

詳細に指示したい場合は、作業内容・進捗・課題・次のタスクなどを含めるよう伝える。作成された資料をコピーまたはファイル保存。

2. 会話のクリア

/clear

または新しいタブ/ウィンドウでClaude Codeを開く。

3. 引き継ぎ資料の読み込み

保存した引き継ぎ資料をペーストして作業を再開。

STEP 2: スラッシュコマンド活用（中級編）

概要

カスタムスラッシュコマンドを作成して、引き継ぎを半自動化する方法。

事前準備

カスタムコマンドの作成

1. プロジェクトルートに .claude/commands/ ディレクトリを作成

---
description: 残りコンテキストが少ないときに、作業引き継ぎを作成してファイルに保存します（Serena不要）。
argument-hint: [作業タイトル]
allowed-tools: Read(*), Write(*), Bash(git status:*), Bash(git diff:*), Bash(git branch:*), Bash(date:+%Y%m%d-%H%M), Bash(mkdir -p docs/handoffs:*), Bash(tail:*), Bash(jq:*)
hook: check-context
---

## トランスクリプトからのコンテキスト情報
フックから渡されるトランスクリプトパスを使用して、現在のコンテキスト使用状況を確認します。
これは `check-context` フックによって自動的に処理されます。

## 自動取得（変更可）
- Now(時刻): !`date +%Y-%m-%d" "%H:%M`
- TS(タイムスタンプ): !`date +%Y%m%d-%H%M`
- Branch: !`git branch --show-current || echo "(no-git)"`
- Changed files: !`git diff --name-only HEAD || echo "-"`

## あなたがやること
**目的**：会話のコンパクト前に、引き継ぎ要約を**短く**作って保存する。

1) 下の**固定セクション**で、2,000文字以内の要約を作成（箇条書き中心）：
   - Goal / Scope（やること・やらないこと）
   - Key decisions（採用・却下と理由を一行ずつ）
   - Done / Pending（完了・未完）
   - Next actions（順序つき 3–7個、各≤140字）
   - Affected files（必要なら path:line）
   - Affected symbols（例: Class#method(sig)／不明なら省略可）
   - Repro / Commands（再現・実行コマンド）
   - Risks / Unknowns（不確定要素と検証案）
   - Links（PR/Issue/Docs）

2) リポジトリ直下の `CURRENT_WORK.md` に**追記**する。見出しは以下：

[Handoff] “$ARGUMENTS” — {{Now}} (branch: {{Branch}})

- ファイルが無ければタイトル `# CURRENT_WORK` を付けて新規作成。
- 直近の履歴が上に来るように追記。

3) 同じ内容を `docs/handoffs/` に**スナップショット保存**する：
- パス：`docs/handoffs/handoff-{{TS}}-{{Branch}}.md`
- ディレクトリが無ければ作成してから書き込む。

4) 最新ポインタ更新：
- `docs/handoffs/_latest.txt` に**上で作ったファイル名**を上書き保存。

### 注意
- 大きなコード貼り付けは禁止。代わりにファイル・行番号で示す。
- 具体的な編集対象（ファイル/クラス/メソッド名）を優先して書く。

警告が出たときの手順

1. 引き継ぎコマンドの実行

/handoff

このコマンドを実行すると、以下のような引き継ぎドキュメントが自動生成される：

# CURRENT_WORK

## [Handoff] "コンポーネント最適化とテスト追加" — 2025-08-28 01:17 (branch: feature/optimization)

### Goal / Scope
- **やること**: Reactコンポーネントの最適化、単体テスト追加、パフォーマンス改善
- **やらないこと**: 新機能実装、API変更、インフラ設定変更

### Key decisions
- **採用**: React.memoによるメモ化（再レンダリング削減）
- **採用**: vitest + testing-libraryでのテスト実装
- **却下**: 完全なリファクタリング（段階的改善を選択）

### Done
- ✅ UserListコンポーネントのメモ化実装
- ✅ usePaginationカスタムフックの分離
- ✅ 不要な依存関係12個削除
- ✅ バンドルサイズ: 450KB→320KBに削減

### Pending
- ⏳ 残り3コンポーネントの最適化
- ⏳ E2Eテストの追加

### Next actions
1. ProductCardコンポーネントの最適化（src/components/ProductCard.tsx:45）
2. 画像の遅延読み込み実装
3. テストカバレッジ80%達成（現在65%）

### Affected files
- src/components/UserList.tsx:120 - メモ化追加
- src/hooks/usePagination.ts - 新規作成
- package.json:35 - 依存関係整理

### Repro / Commands

bash
# テスト実行
npm run test
# バンドルサイズ確認  
npm run analyze


### Risks / Unknowns
- **リスク**: メモ化による過度な最適化でメモリ使用量増加の可能性
- **検証案**: Chrome DevToolsでメモリプロファイリング実施

### Links
- PR: https://github.com/your-org/project/pull/123
- Issue: #456

2. 会話のクリア

/clear

3. 作業の再開

/rehydrate

これでコマンド一つでそれなりに再現性のある引き継ぎが完了。初期設定は必要だが、繰り返し利用できるし作業効率が大幅に向上する。

推奨される導入順序

1. 今すぐ: STEP 0でコンテキスト使用状況を可視化
2. 第1週目: STEP 1を実践し、引き継ぎの流れを理解
3. 第2週目: STEP 2に移行し、コマンドで効率化

今後の展望

STEP 3: 完全自動化への道

次のステップとして、コンテキスト70%で自動通知、作業パターン学習による最適な引き継ぎタイミング提案、チーム間での引き継ぎ共有などを検討中。

コミュニティからの引き継ぎテンプレートや最適化Tipsの共有も期待している。これらが実現すれば、コンテキスト管理から完全に解放される未来も近いかも。

---

次はDevRelの重田さんです！