| name | context-discipline |
| description | Token budget management for Claude Code sessions. Teaches how to minimize context consumption using MCP-first navigation, lazy loading, subagent isolation, and strategic file reading. Keeps Claude effective throughout long sessions by treating the 200k token window as a budget, not a dumping ground. Load this skill when context is running low, sessions feel sluggish, Claude starts forgetting earlier context, or when planning how to explore a large codebase efficiently. Keywords: "context", "tokens", "budget", "running out of context", "too many files", "large codebase", "memory".
|
Context Discipline
Core Principles
-
MCP tools first, file reads second — A Roslyn MCP query costs 30-150 tokens. Reading a file costs 500-2000+ tokens. For navigation and understanding, always try MCP tools before opening files. Only read files when you need to modify them or MCP tools don't provide enough detail.
-
Lazy load everything — Don't read files "just in case." Don't load all skills upfront. Don't explore directories you aren't about to modify. Load information at the moment you need it, not before.
-
Subagents are context isolation chambers — Every subagent gets its own context window. Offload exploration, research, and analysis to subagents. They process information and return a summary — your main context stays clean.
-
Summarize and discard — After exploring a subsystem, summarize what you learned in a few lines. The summary is what stays in context, not the raw file contents. Think of it as compressing information.
-
Know your budget — A 200k token window sounds large but fills fast. A typical .cs file is 500-2000 tokens. Loading 50 files can consume half your budget. Plan your reads like you plan your sprints — deliberately.
Patterns
MCP-First Navigation
Always prefer MCP tools for understanding code structure:
TASK: Understand how OrderService works
EXPENSIVE APPROACH (file reads):
1. Read src/Orders/OrderService.cs → ~1200 tokens
2. Read src/Orders/IOrderService.cs → ~300 tokens
3. Read src/Orders/OrderRepository.cs → ~800 tokens
4. Read src/Orders/Models/Order.cs → ~600 tokens
Total: ~2900 tokens consumed
TOKEN-EFFICIENT APPROACH (MCP-first):
1. find_symbol "OrderService" → ~50 tokens (file path + line)
2. get_public_api "OrderService" → ~120 tokens (method signatures)
3. find_references "OrderService" → ~80 tokens (who uses it)
4. get_type_hierarchy "OrderService" → ~60 tokens (inheritance chain)
Total: ~310 tokens consumed — 9x cheaper
Only THEN read the specific method you need to modify: ~200 tokens
Grand total: ~510 tokens vs 2900 — 5.7x savings
Subagent Offloading Decision Matrix
Decide when to offload to a subagent vs. handle in main context:
USE A SUBAGENT WHEN:
- Exploring an unfamiliar part of the codebase (> 3 files to read)
- Researching a question that requires reading docs or multiple files
- Running analysis that produces verbose output (test results, diagnostics)
- Comparing approaches that require loading multiple examples
- Any task where the journey is verbose but the answer is concise
STAY IN MAIN CONTEXT WHEN:
- Modifying a file you've already read
- Quick lookups (1-2 MCP queries)
- Tasks where you need to see prior conversation context
- Writing code that builds on discussion with the user
Example subagent delegation:
TASK: "Find all places where we handle authentication"
MAIN CONTEXT APPROACH (expensive):
- Read 8 files, consume ~8000 tokens
- All that content stays in context forever
SUBAGENT APPROACH (efficient):
- Spawn subagent: "Find all authentication handling in this codebase.
Use find_symbol and find_references for auth-related types.
Return: file paths, line numbers, and a 1-line summary per location."
- Subagent returns ~200 tokens of summarized findings
- Main context stays clean
Context Budget Planning
Before a complex task, estimate token spend per phase:
UNDERSTAND (~5k): MCP queries (~300) + subagent exploration (~500) + reserve
PLAN (~2k): Discussion + plan documentation
IMPLEMENT (~15k): Read files to modify (~3k) + write code (~5k) + iteration (~7k)
VERIFY (~3k): Build + test + diagnostics + format check
REMAINING: ~175k for conversation — comfortable
File Reading Prioritization
When you must read files, prioritize by impact:
PRIORITY 1 — Files you will modify
Read fully. You need exact content to make correct edits.
PRIORITY 2 — Files with interfaces/contracts you must satisfy
Read the interface/base class. Skip implementation details.
PRIORITY 3 — Files for reference patterns
Use get_public_api first. Only read if the API surface isn't enough.
PRIORITY 4 — Files for general context
Use subagent to summarize. Don't read in main context.
NEVER READ:
- Entire directories "to understand the project" — use get_project_graph
- Test files for context (unless modifying tests) — use get_test_coverage_map
- Generated files (.designer.cs, migrations) — use get_diagnostics for issues
- Package/config files unless specifically needed
Context Pruning & Large Codebase Strategy
WARNING SIGNS (take action if any apply):
- Read 10+ files, 50+ exchanges, forgetting earlier details, re-reading files
RECOVERY: Summarize in 5-10 lines → subagents for remaining exploration →
MCP-only for new lookups → reference prior line numbers → suggest new session if needed
LARGE CODEBASES (50+ projects):
get_project_graph → identify 2-3 relevant projects → find_symbol for key types →
get_public_api for interfaces → read ONLY files you'll modify → subagents for cross-cutting
NEVER: Read every file to "understand" a project, load all skills upfront,
open a file to find one function (use find_symbol)
Anti-patterns
Reading Entire Files for One Function
// BAD — read 1500 tokens to find one 10-line method
Read: src/Orders/OrderService.cs (full file, 80 lines)
*Only needed the ProcessOrder method on line 42*
// GOOD — targeted approach
MCP: find_symbol "ProcessOrder" → "src/Orders/OrderService.cs:42"
Read: src/Orders/OrderService.cs lines 42-55 → ~200 tokens
Loading All Skills Upfront
// BAD — dump 15 skills into context at session start
"Load: modern-csharp, ef-core, minimal-api, testing, docker,
authentication, logging, caching, messaging, resilience..."
*15 skills × ~300 tokens each = ~4500 tokens before any work starts*
// GOOD — load skills as topics arise
Session start: modern-csharp (always relevant)
User asks about EF: load ef-core
User asks about tests: load testing
*Only pay for what you use*
Not Using Subagents for Exploration
// BAD — explore in main context, polluting the window
Read 12 files across 4 projects to understand auth flow
*~15,000 tokens consumed, all staying in context*
// GOOD — subagent explores, returns summary
Subagent: "Trace the authentication flow from login to token validation.
Return: the flow as numbered steps with file:line references."
*~300 tokens in main context*
Loading Everything Because the Window Is Large
// BAD — "200k tokens is huge, let's load everything"
Read all 30 files in the Orders module
Read all 15 test files
Read the entire docker-compose.yml
Read all migration files
*80k tokens consumed before writing a single line of code*
// GOOD — minimum viable context
MCP: get_project_graph (solution shape)
MCP: find_symbol (locate target types)
Read: 2-3 files you'll actually modify
Subagent: summarize anything else you need
*~3k tokens consumed, 197k remaining for actual work*
Decision Guide
| Scenario | Recommendation |
|---|
| Need to find where a type is defined | find_symbol — never grep |
| Need to understand a type's API | get_public_api — don't read the file |
| Need to modify a file | Read it fully — you need exact content |
| Need to understand project structure | get_project_graph — don't browse directories |
| Need to explore unfamiliar code | Spawn a subagent — keep main context clean |
| Read more than 10 files in a session | Pause — switch to MCP + subagents |
| Context feels heavy or sluggish | Summarize what you know, use subagents going forward |
| Large codebase (50+ projects) | MCP-first, subagent-heavy, read only files you modify |
| User asks about a new topic mid-session | Load the relevant skill on demand, not in advance |
| Need to compare two approaches | Subagent per approach, compare summaries |
