context-management

コンテキスト管理スキル

目的

このスキルは、インテリジェントなトークン監視、コンテキストの抽出、選択的な再読み込みを通じて、Claude Code のコンテキストウィンドウを先回りして管理できるようにします。圧縮後に事後対応で復元するのではなく、上限に達する前に重要なコンテキストを保持し、必要なときに効率よく復元できるよう支援します。

バージョン 3.0 の強化点：

• 予測型予算監視：容量のしきい値に達する時期を推定します
• コンテキスト健全性インジケーター：ステータスラインへの統合に使える視覚的なインジケーターです
• 優先度に基づく保持：要件や決定事項を保持し、冗長なログをアーカイブします
• 消費速度の追跡：トークンの消費速度を監視して、早期警告を提供します

このスキルを使う場面

• トークンの監視：現在の使用状況を確認し、推奨事項を取得します
• 上限が近いとき：使用率が 70～85％の時点でスナップショットを作成します
• 圧縮後：会話全体を使わずに重要なコンテキストを復元します
• 長時間のセッション：重要な決定事項と状態を先回りして保持します
• 複雑なタスク：要件と進捗をすぐに参照できるようにします
• コンテキストの切り替え：作業を中断するときに状態を保存します
• チームへの引き継ぎ：他の人が作業を続けられるよう、コンテキストをまとめます
• 予測的な計画：容量に達する前に早期警告を取得します
• セッションの健全性：継続的な生産性を保つため、コンテキストの健全性を監視します

クイックスタート

トークンの状態を確認する

User: Check my current token usage

context_manager ツールを使って状態を確認します：

from context_manager import check_context_status

status = check_context_status(current_tokens=<current_count>)
# Returns: ContextStatus with usage percentage and recommendations

スナップショットを作成する

User: Create a context snapshot named "auth-implementation"

context_manager ツールを使ってスナップショットを作成します：

from context_manager import create_context_snapshot

snapshot = create_context_snapshot(
    conversation_data=<conversation_history>,
    name="auth-implementation"
)
# Returns: ContextSnapshot with snapshot_id, file_path, and token_count

コンテキストを復元する

User: Restore context from snapshot <snapshot_id> at essential level

context_manager ツールを使ってコンテキストを再読み込みします：

from context_manager import rehydrate_from_snapshot

context = rehydrate_from_snapshot(
    snapshot_id="20251116_143522",
    level="essential"  # or "standard" or "comprehensive"
)
# Returns: Formatted context text ready to process

スナップショットを一覧表示する

User: List my context snapshots

context_manager ツールを使ってスナップショットを一覧表示します：

from context_manager import list_context_snapshots

snapshots = list_context_snapshots()
# Returns: List of snapshot metadata dicts

詳細レベル

コンテキストを再読み込みするときは、適切な詳細レベルを選択してください：

• Essential（最小）：要件と現在の状態のみ（約 250 トークン）
• Standard（バランス）：重要な決定事項と未対応項目を追加（約 800 トークン）
• Comprehensive（完全）：すべての決定事項、使用したツール、メタデータを追加（約 1,250 トークン）

まず Essential を選択し、さらにコンテキストが必要な場合は詳細レベルを上げてください。

アクション

アクション：status

現在のトークン使用状況を確認し、推奨事項を取得します。

使用方法：

from context_manager import check_context_status

status = check_context_status(current_tokens=750000)
print(f"Usage: {status.percentage}%")
print(f"Status: {status.threshold_status}")
print(f"Recommendation: {status.recommendation}")

戻り値：

• 使用状況の詳細を含む ContextStatus オブジェクト
• threshold_status：'ok'、'consider'、'recommended'、または 'urgent'
• recommendation：人が読める形式のアクション提案

アクション：snapshot

インテリジェントなコンテキストスナップショットを作成します。

使用方法：

from context_manager import create_context_snapshot

snapshot = create_context_snapshot(
    conversation_data=messages,
    name="feature-name"  # Optional
)
print(f"Snapshot ID: {snapshot.snapshot_id}")
print(f"Token count: {snapshot.token_count}")
print(f"Saved to: {snapshot.file_path}")

戻り値：

• メタデータを含む ContextSnapshot オブジェクト
• スナップショットは ~/.amplihack/.claude/runtime/context-snapshots/ に保存されます

アクション：rehydrate

指定した詳細レベルで、スナップショットからコンテキストを復元します。

使用方法：

from context_manager import rehydrate_from_snapshot

context = rehydrate_from_snapshot(
    snapshot_id="20251116_143522",
    level="standard"  # essential, standard, or comprehensive
)
print(context)  # Display restored context

戻り値：

• 復元したコンテキストを含む、書式設定済みの Markdown テキスト
• 作業を処理して続行できる状態です

アクション：list

利用可能なコンテキストスナップショットをすべて一覧表示します。

使用方法：

from context_manager import list_context_snapshots

snapshots = list_context_snapshots()
for snapshot in snapshots:
    print(f"{snapshot['id']}: {snapshot['name']} ({snapshot['size']})")

戻り値：

• スナップショットのメタデータ辞書のリスト
• 次の情報が含まれます：id、name、timestamp、size、token_count

先回り機能（v3.0）

予測型予算監視

現在の使用状況を確認するだけでなく、しきい値に達する時期を予測します：

# The system tracks token burn rate over time
# When checking status, you get predictive insights

status = check_context_status(current_tokens=500000)

# Status includes predictions (when automation is running):
# - Estimated tool uses until 70% threshold
# - Time estimate based on current burn rate
# - Early warning before you hit capacity

# Example output interpretation:
# "At current rate, you'll hit 70% in ~15 tool uses"
# "Consider creating a checkpoint before your next major operation"

予測の仕組み：

自動化機能は次の情報を追跡します：

1. 各確認間隔におけるトークン数
2. 確認の間に使用されたツールの数
3. ツールの使用ごとに消費された平均トークン数
4. 確認間の経過時間

このデータから、次の項目を推定します：

• しきい値に達するまでに使用できるツールの数
• しきい値に達するまでのおおよその時間
• 現在のタスクが上限に達する前に完了するかどうか

コンテキスト健全性インジケーター

セッションの健全性を示す視覚的なインジケーターです。ステータスラインへの統合に適しています。

インジケーター	意味	使用率	推奨アクション
[CTX:OK]	健全	0-30%	通常どおり続行
[CTX:WATCH]	要監視	30-50%	チェックポイントを計画
[CTX:WARN]	警告	50-70%	まもなくスナップショットを作成
[CTX:CRITICAL]	危険	70%+	直ちにスナップショットを作成

ステータスラインへの統合例：

# In your statusline script, check context health:
# The automation state file contains health status

# Example statusline addition:
if [ -f ".claude/runtime/context-automation-state.json" ]; then
    LAST_PCT=$(jq -r '.last_percentage // 0' .claude/runtime/context-automation-state.json)
    if [ "$LAST_PCT" -lt 30 ]; then
        echo "[CTX:OK]"
    elif [ "$LAST_PCT" -lt 50 ]; then
        echo "[CTX:WATCH]"
    elif [ "$LAST_PCT" -lt 70 ]; then
        echo "[CTX:WARN]"
    else
        echo "[CTX:CRITICAL]"
    fi
fi

優先度に基づくコンテキストの保持

スナップショットを作成するとき、システムは重要度に基づいて内容の優先順位を付けます。

優先度：高（常に保持）：

• 元のユーザー要件（最初のユーザーメッセージ）
• 主要なアーキテクチャ上の決定
• 現在の実装状況
• 未解決の項目とブロッカー

優先度：中（Standard 以上で保持）：

• ツールの使用履歴
• 決定の根拠
• 質問と確認事項

優先度：低（Comprehensive のみ）：

• 詳細な出力ログ
• 中間ステップ
• デバッグ情報

使用パターン：

# Create snapshot with priority awareness
snapshot = create_context_snapshot(
    conversation_data=messages,
    name='feature-checkpoint'
)

# Essential level (~200 tokens): Only high priority content
# Standard level (~800 tokens): High + medium priority
# Comprehensive level (~1250 tokens): Everything

# Start minimal, upgrade as needed:
context = rehydrate_from_snapshot(snapshot_id, level='essential')

消費速度の追跡

コンテキストの消費速度を監視します。

# The automation tracks consumption velocity
# Adaptive checking frequency based on burn rate:

# Low burn rate (< 1K tokens/tool): Check every 50 tools
# Medium burn rate (1-5K tokens/tool): Check every 10 tools
# High burn rate (> 5K tokens/tool): Check every 3 tools
# Critical zone (70%+): Check every tool

# This means:
# - Normal development: Minimal overhead (checks rarely)
# - Large file operations: Increased monitoring
# - Approaching limits: Continuous monitoring

消費速度のしきい値：

消費速度	リスクレベル	監視頻度
< 1K/tool	低	50 ツールごと
1-5K/tool	中	10 ツールごと
> 5K/tool	高	3 ツールごと
70% 以上なら任意	危険	すべてのツール

自動要約のトリガー

上限に達する前に、システムがスナップショットを自動的に作成します。

# Automatic snapshot triggers (already implemented):
# - 30% usage: First checkpoint created
# - 40% usage: Second checkpoint created
# - 50% usage: Third checkpoint created (for 1M models)

# For smaller context windows (< 800K):
# - 55% usage: First checkpoint
# - 70% usage: Second checkpoint
# - 85% usage: Urgent checkpoint

# After compaction detected (30% token drop):
# - Automatically rehydrates from most recent snapshot
# - Uses smart level selection based on previous usage

事前対応型の使用ワークフロー

ステップ 1：トークン使用量を監視する

長時間のセッションでは、定期的にステータスを確認します。

status = check_context_status(current_tokens=current)

if status.threshold_status == 'consider':
    # Usage at 70%+ - consider creating snapshot
    print("Consider creating a snapshot soon")
elif status.threshold_status == 'recommended':
    # Usage at 85%+ - snapshot recommended
    create_context_snapshot(messages, name='current-work')
elif status.threshold_status == 'urgent':
    # Usage at 95%+ - create snapshot immediately
    create_context_snapshot(messages, name='urgent-backup')

ステップ 2：しきい値に達したらスナップショットを作成する

70～85% のしきい値に達したら、名前付きのスナップショットを作成します。

snapshot = create_context_snapshot(
    conversation_data=messages,
    name='descriptive-name'
)
# Save snapshot ID for later rehydration

ステップ 3：作業を続ける

スナップショットを作成した後：

• 自然に会話を続けます
• 必要に応じて Claude Code に圧縮させます
• 必要であれば、完全な履歴に /transcripts を使用します
• PreCompact フックがすべてを自動的に保存します

ステップ 4：圧縮後にコンテキストを再読み込みする

圧縮後、必要なコンテキストを復元します。

# Start minimal
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='essential'
)

# If more context needed, upgrade to standard
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='standard'
)

# For complete context, use comprehensive
context = rehydrate_from_snapshot(
    snapshot_id='20251116_143522',
    level='comprehensive'
)

既存システムとの統合

PreCompact フックとの比較

PreCompact フック（自動セーフティネット）：

• 圧縮前に Claude Code によってトリガーされます
• 会話の完全なトランスクリプトを保存します
• 自動で実行されるため、ユーザー操作は不要です
• 会話全体を Markdown にエクスポートします

Context Skill（事前対応型の最適化）：

• 監視結果に基づいてユーザーがトリガーします
• 必要なコンテキストを抽出して保存します
• ユーザーが意図的に選択して実行します
• 完全なダンプではなく、必要なコンテキストのみを保存します

関係性：競合するものではなく、相互に補完します。フックはセーフティネット、Skill は最適化です。

/transcripts コマンドとの比較

/transcripts（事後対応型の復元）：

• 圧縮後に会話全体を復元します
• すべてのメッセージを含む完全な履歴です
• すべてを元に戻す必要がある場合に使用します
• 事後対応型の復旧ツールです

Context Skill（事前対応型の保持）：

• 圧縮前に必要なコンテキストを保持します
• 完全な履歴ではなく、選択的に再読み込みします
• コンテキストを効率的に管理したい場合に使用します
• 事前対応型の最適化ツールです

関係性：完全な復旧には transcripts、効率的な管理には skill を使用します。

保存場所

• スナップショット：~/.amplihack/.claude/runtime/context-snapshots/ (JSON)
• トランスクリプト：~/.amplihack/.claude/runtime/logs/<session_id>/CONVERSATION_TRANSCRIPT.md
• 競合なし：保存先ディレクトリも目的も異なります

自動管理

コンテキスト管理は post_tool_use フックによって自動的に実行されます。

• トークン使用量を N 回目のツール使用ごとに監視します（頻度は適応的に調整されます）
• しきい値（1M モデルでは 30%、40%、50%）でスナップショットを作成します
• 圧縮を検出します（トークン数の減少が 30% 超）
• 適切なレベルで圧縮後にコンテキストを自動的に再読み込みします

これらはユーザーの操作なしで透過的に実行されます。

実装

コンテキスト管理機能はすべて、以下によって提供されます。

• ツール：~/.amplihack/.claude/tools/amplihack/context_manager.py
• フック統合：~/.amplihack/.claude/tools/amplihack/context_automation_hook.py
• フックシステム：~/.amplihack/.claude/tools/amplihack/hooks/tool_registry.py

API の完全なリファレンスと実装の詳細については、ツールのドキュメントを参照してください。

よくあるパターン

パターン 1：事前のスナップショット作成

長時間の操作の前に確認し、必要であればスナップショットを作成します。

status = check_context_status(current_tokens=current)
if status.threshold_status in ['recommended', 'urgent']:
    create_context_snapshot(messages, name='before-refactoring')

パターン 2：コンテキストの切り替え

別の機能に取り組むために作業を中断する際、状態を保存します。

# Pausing work on Feature A
create_context_snapshot(messages, name='feature-a-paused')

# [... work on Feature B ...]

# Resume Feature A later
context = rehydrate_from_snapshot('feature-a-snapshot-id', level='standard')

パターン 3：チームへの引き継ぎ

チームメイト向けに包括的なスナップショットを作成します。

snapshot = create_context_snapshot(
    messages,
    name='handoff-to-alice-api-work'
)
# Share snapshot ID with teammate
# Alice can rehydrate and continue work

哲学との整合性

徹底したシンプルさ

• 1 つのツールに、単一目的のコンポーネントを 4 つまとめています
• 必要なときに呼び出す方式で、バックグラウンドプロセスはありません
• 標準ライブラリのみを使用し、外部依存関係はありません
• 便利な関数を備えた、明確なパブリック API です

単一責任

• ContextManager がすべての操作を調整します
• トークンの監視、抽出、再構築を 1 か所にまとめています
• コードの重複やロジックの分散はありません

ごまかしのない実装

• スタブやプレースホルダーはありません
• すべての関数が完全に動作します
• トークン数を実際に推定し、偽の値は使いません
• ファイル操作を実際に行い、シミュレーションはしません

創発を信頼する

• 自動ではなく、ユーザーがスナップショットを作成するタイミングを決めます（フック経由の場合を除く）
• 詳細度はシステムではなく、ユーザーが選びます
• 積極的な選択によって、ユーザーの主体性を高めます

効果的なコンテキスト管理のヒント

1. 定期的に監視する：自然な区切りで状態を確認します
2. 戦略的にスナップショットを作成する：使用率が 70～85％になったとき、または長時間の操作の前に作成します
3. 最小限から始める：まず essential レベルを使い、必要に応じて上げます
4. 内容がわかる名前を付ける：後で参照しやすいよう、明確なスナップショット名を付けます
5. 定期的に一覧を確認する：古いスナップショットを確認し、整理します
6. ツールを組み合わせる：完全な復旧手段として /transcripts と併用します
7. 創発を信頼する：スナップショットを作りすぎず、コンテキストの流れに任せます

リソース

• ツール：~/.amplihack/.claude/tools/amplihack/context_manager.py
• フック：~/.amplihack/.claude/tools/amplihack/context_automation_hook.py
• 哲学：~/.amplihack/.claude/context/PHILOSOPHY.md
• パターン：~/.amplihack/.claude/context/PATTERNS.md

覚えておくこと

このスキルは、シンプルで再利用可能なツールを通じて、積極的なコンテキスト管理を実現します。このツールは、スキル、コマンド、フックから呼び出せます。既存のツール（PreCompact フック、/transcripts）を置き換えるのではなく、補完します。長時間のセッションを通じてコンテキストを整理し、効率的に保つために活用してください。

重要なポイント：ビジネスロジックは context_manager.py にあり、このスキルはその使い方を説明するだけです。