# Context Optimization > [Utilities] Use when managing context window usage, compressing long sessions, or optimizing token usage. - Skill: `duc01226/context-optimization-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/context-optimization-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/context-optimization-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/duc01226/context-optimization-3 --- ## Quick Summary **Goal:** Manage context window efficiently to maintain productivity in long Claude Code sessions. **Workflow:** 1. **Compress** — Create context anchors every 10 operations summarizing progress 2. **Isolate** — Delegate exploration tasks to sub-agents to reduce context usage > Cross-session persistence (saving findings to survive a new session) is out of scope here — use file checkpoints via `/checkpoint` and restore with `/recover` (see the `memory-management` skill). **Key Rules:** - Write context anchor every 10 operations (re-read task, verify alignment, summarize) - Use offset/limit and grep before reading large files - Combine search patterns with OR instead of sequential searches - At 100K tokens: required compression; at 150K: critical save and summarize **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** # Context Optimization & Management Manage context window efficiently to maintain productivity in long sessions. --- ## Context Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Context Window (~200K tokens) │ ├─────────────────────────────────────────────────────────────┤ │ System Prompt (CLAUDE.md excerpts) ~2,000 tokens │ │ ─────────────────────────────────────────────────────────── │ │ Working Memory (current task state) ~10,000 tokens │ │ ─────────────────────────────────────────────────────────── │ │ Retrieved Context (RAG from codebase) ~20,000 tokens │ │ ─────────────────────────────────────────────────────────── │ │ Episodic Memory (past session learnings) ~5,000 tokens │ │ ─────────────────────────────────────────────────────────── │ │ Tool Descriptions (relevant tools only) ~3,000 tokens │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Two Context Strategies ### 1. Compressing (Summarize Long Trajectories) Create context anchors every 10 operations: ```markdown === CONTEXT ANCHOR === Current Task: Implement order return request feature Completed: - Created Return entity with validation - Added SaveReturnCommand with handler - Implemented entity event handler for notifications Remaining: - Create GetReturnListQuery - Add controller endpoint - Write unit tests Key Findings: - Returns use service-specific repository - Notifications via entity event handlers, not direct calls - Validation uses validation framework fluent .AndAsync() # Next Action: Create query handler with GetQueryBuilder pattern ``` #### Pre-Compaction Preservation Checklist (canonical for `/compact`) Before a manual `/compact` (or any context compaction), confirm these are saved so they survive the cut — this is the canonical checklist the user-facing `/compact` alias delegates to: - [ ] Current branch + uncommitted-changes status - [ ] Active file paths being modified - [ ] Any error messages / stack traces (preserve verbatim when mid-bug) - [ ] Key decisions and their rationale - [ ] Pending items from the todo list **Preserve** decisions, files modified, current task state. **Drop** redundant tool outputs, repeated searches, verbose logs. Compact at natural breakpoints (after commits/PR), not mid-task; after compacting, restate the current objective. ### 2. Isolating (Use Sub-Agents) Delegate specialized tasks to sub-agents: ```javascript // Explore codebase (reduced context) Task({ subagent_type: 'Explore', prompt: 'Find all entity event handlers in the target service' }); // Plan implementation (focused context) Task({ subagent_type: 'Plan', prompt: 'Plan return approval workflow' }); ``` **When to Isolate:** - Broad codebase exploration - Independent research tasks - Parallel investigations --- ## Context Anchor Protocol **Every 10 operations, write a context anchor:** 1. **Re-read original task** from todo list or initial prompt 2. **Verify alignment** with current work 3. **Write anchor** summarizing progress 4. **Persist to a checkpoint** (`/checkpoint`) if discovering important patterns ```markdown === CONTEXT ANCHOR [10] === Task: [Original task description] Phase: [Current phase number] Progress: [What's been completed] Findings: [Key discoveries] Next: [Specific next step] Confidence: [High/Medium/Low] =========================== ``` --- ## Token-Efficient Patterns ### File Reading ```javascript // ❌ Reading entire files Read({ file_path: 'large-file.cs' }); // ✅ Read specific sections Read({ file_path: 'large-file.cs', offset: 100, limit: 50 }); // ✅ Use grep to find specific content first Grep({ pattern: 'class SaveOrderCommand', path: '/' }); ``` ### Search Optimization ```javascript // ❌ Multiple sequential searches Grep({ pattern: 'CreateAsync' }); Grep({ pattern: 'UpdateAsync' }); Grep({ pattern: 'DeleteAsync' }); // ✅ Combined pattern Grep({ pattern: 'CreateAsync|UpdateAsync|DeleteAsync', output_mode: 'files_with_matches' }); ``` ### Parallel Operations ```javascript // ✅ Parallel reads for independent files [Read({ file_path: 'file1.cs' }), Read({ file_path: 'file2.cs' }), Read({ file_path: 'file3.cs' })]; ``` --- ## Anti-Patterns | Anti-Pattern | Better Approach | | -------------------------- | ------------------------------ | | Reading entire large files | Use offset/limit or grep first | | Sequential searches | Combine with OR patterns | | Repeating same searches | Reuse earlier results | | No context anchors | Write anchor every 10 ops | | Not using sub-agents | Isolate exploration tasks | | Forgetting discoveries | Save findings to a checkpoint | --- ## Quick Reference **Token Estimation:** - 1 line of code ≈ 10-15 tokens - 1 page of text ≈ 500 tokens - Average file ≈ 1,000-3,000 tokens **Context Thresholds:** - 50K tokens: Consider compression - 100K tokens: Required compression - 150K tokens: Critical - save and summarize ## Related - `memory-management` --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip. > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting. > **Parallel Sub-Agent Dispatch** — Plan parallelism the moment a task breakdown exists, BEFORE executing it — running provably independent tasks sequentially wastes wall-clock. Applies to every multi-step job: workflow steps, planning, batch updates, investigation, research, scans, reviews, doc sync. **Plan execution is metadata-gated, NEVER default-parallel** — fan-out follows ONLY what the plan declares (`PAR`/`SEQ` tags + per-phase write set); an untagged plan runs sequentially — why: a derived write set cannot see cascade or generated writes. > > 1. **Tag every task `PAR` or `SEQ`.** `PAR` = inputs exclude every pending task's output AND write set disjoint from every other `PAR`. Else `SEQ` — MUST ATTENTION name the dependency forcing it. > 2. **Group `PAR` into waves.** No edge between members. Two writers of one file NEVER share a wave. Read-only work (search, investigation, review, research) parallelizes freely. > 3. **Declare before dispatch:** `Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)`. > 4. **Spawn each wave in ONE message** — every `Agent` call in one response, NEVER dripped per turn. Route each task to its specialist (`.claude/skills/shared/sub-agent-selection-guide.md`); NEVER `code-reviewer` as catch-all. > 5. **Brief each sub-agent self-contained:** goal · scope + owned files · reference docs · return contract (summary + `Full report:` path, per SYNC:subagent-return-contract) · incremental persistence to `plans/reports/` (per SYNC:incremental-persistence). > 6. **Barrier per wave.** Advance ONLY after EVERY member returns (a skipped conditional counts as returned). Merge, mark each task completed/skipped, THEN dispatch the next wave. Mutating steps wait for the barrier. > 7. **One level deep.** A dispatched sub-agent executes its own brief; further fan-out stays the orchestrator's job unless that agent's `.claude/agents/*.md` definition authorizes it. > > **NEVER parallelize:** tasks sharing a write target · a task consuming a pending task's output · trivial single-file work (dispatch overhead > gain) · an order a skill or workflow explicitly fixes · gates awaiting user approval. > > **Blocked until:** MUST ATTENTION every task tagged PAR/SEQ with a named reason per SEQ · waves declared + write-set disjointness checked · each wave spawned in ONE message · barrier honored before the next wave. - **MANDATORY** After planning tasks, tag each PAR/SEQ and spawn every PAR wave as parallel sub-agents in ONE message — default parallel for workflows, batch updates, investigation, research, reviews; plan execution fans out ONLY on what the plan declares. - **MANDATORY** Disjoint write sets per wave · all-return barrier before the next wave · specialist routing · sub-agents NEVER fan out further unless their own agent definition authorizes it. > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **IMPORTANT MUST ATTENTION — Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. - **Critical Thinking:** traced `file:line` proof per claim, confidence >80% to act, never guess. - **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting - **MANDATORY IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code - **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) - **MANDATORY IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality - **Parallel Sub-Agent Dispatch:** Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing. **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.