context-compression

コンテキスト圧縮 — 長時間セッションの管理

重要な決定事項を保持しながら、完了した作業を圧縮して、セッションを生産的に保ちます。

概要

長時間のセッション（30ターン以上）では、コンテキストが劣化し、AI が以前の作業を把握できなくなったり、同じ内容を繰り返したり、決定事項を忘れたりします。コンテキスト圧縮では、完了したフェーズをあらかじめ要約し、コンテキストウィンドウを現在進行中の作業に集中させます。

トークンへの影響： 長時間のセッションで、冗長なツール出力を意味のある要約に置き換えることで、5,000～15,000 トークンを回収できます。

---

圧縮するタイミング

シグナル	アクション
セッションが20ターン以上ある	先を見越した圧縮を検討します
エージェントが以前の提案を繰り返す	コンテキストが飽和しています。すぐに圧縮します
ユーザーが「それはすでに話し合いました」と言う	直ちに圧縮します
新しい作業フェーズに移る	完了したフェーズを圧縮します
ツール出力が大きい（500行以上）	出力をマイクロ圧縮します

---

圧縮レベル

レベル1：マイクロ圧縮（ツール出力）

意味のある内容を保持しながら、個々のツール出力を圧縮します。

❌ Before (raw grep output — 200 lines, ~4,000 tokens):
src/auth/jwt.ts:15: import { verify } from 'jsonwebtoken'
src/auth/jwt.ts:23: export function validateToken(token: string) {
src/auth/jwt.ts:24:   try {
src/auth/jwt.ts:25:     const decoded = verify(token, SECRET)
... (195 more lines)

✅ After (micro-compact — 5 lines, ~100 tokens):
Grep results for "jwt": Found 8 files, 42 matches.
Key files: src/auth/jwt.ts (main JWT logic), src/middleware/auth.ts (middleware),
src/api/login.ts (token creation). Token validation at jwt.ts:23-40.
Error handling at jwt.ts:42-55. Secret loaded from env at jwt.ts:8.

レベル2：フェーズの要約

完了した作業フェーズを要約に置き換えます。

❌ Before (full research transcript — ~3,000 tokens):
[turn 1] Read package.json...
[turn 2] Read src/index.ts...
[turn 3] Grep for "auth"...
[turn 4] Found 8 files related to auth...
[turn 5] Read src/auth/jwt.ts...
... (10 more turns of exploration)

✅ After (phase summary — ~200 tokens):
## Research Phase Complete
- Project: Next.js 15 app with JWT auth
- Auth files: 8 files in src/auth/, src/middleware/, src/api/
- Token flow: login → create JWT → store in httpOnly cookie → validate in middleware
- Bug location: src/auth/jwt.ts:45 — expiry check uses `<` instead of `<=`
- Decision: Fix the comparison operator, add edge case test

レベル3：セッションのチェックポイント

長時間にわたる作業のために、セッション全体を要約します。

## Session Checkpoint (Turn 35)

### Completed
- [x] Researched auth system (8 files, JWT flow mapped)
- [x] Fixed token expiry bug in jwt.ts:45
- [x] Added edge case test in jwt.test.ts
- [x] Verified: all 42 tests passing

### In Progress
- [ ] Update API documentation
- [ ] Review related middleware

### Key Decisions
1. Keep httpOnly cookies (not localStorage) for token storage
2. Use `<=` for expiry check to include exact-moment expiry
3. Add 5-minute grace period for clock skew

### Files Modified
- src/auth/jwt.ts (line 45: comparison fix)
- tests/auth/jwt.test.ts (added 3 edge case tests)

---

圧縮プロトコル

ステップ1：完了したフェーズを特定する

What work is DONE and won't be revisited?
→ Research findings already synthesized
→ Implementation already verified
→ Decisions already made and applied

ステップ2：重要な情報を抽出する

From the completed phase, preserve:
✅ Decisions made and WHY
✅ File paths and line numbers of changes
✅ Key findings that inform ongoing work
✅ Error messages or test results (summarized)

Discard:
❌ Step-by-step tool invocation details
❌ Full file contents that were read
❌ Exploratory dead-ends that didn't lead anywhere
❌ Verbose error stack traces (keep the message only)

ステップ3：要約を書く

Use the Phase Summary format above.
Keep to 100-300 tokens per completed phase.
Include enough detail to resume work without re-reading.

---

ベストプラクティス

1. 事実ではなくフェーズを圧縮する — 個々の決定事項は残し、会話の全文記録は削除します
2. 「何を」より「なぜ」を残す — 実行したコマンドそのものより、決定に至った理由が重要です
3. 自動で圧縮しない — 必ずユーザーに「コンテキストを集中させるため、完了した調査フェーズを要約しています」と伝えます
4. ファイルへの参照を残す — 要約ではファイルパスと行番号を必ず保持します
5. フェーズの移行時にチェックポイントを作成する — 調査から実装に移るときは、自然な圧縮のタイミングです