Skip to main content

Context Management

Overview​

Context Management is vital for several key reasons: it ensures accurate and relevant outputs, controls costs by limiting token usage, maintains predictability and prevents "context drift" where irrelevant information confuses the AI, and enhances safety by preventing the accidental leakage of sensitive data.

AGENTS.md support

While we favor CLAUDE.md files, we also support AGENTS.md files as the emerging standard for AI tooling. AGENTS.md is supported by GitHub Copilot, opencode, CodeRabbit, and Cursor. We implement this compatibility through symlinks to the CLAUDE.md files (see PR)

Core Strategies​

1. Strategic Context Loading​

Start with essentials:

  1. Project overview: "Review CLAUDE.md to understand the project"
  2. Load relevant files: "Read the current implementation in src/components/CallInterface.tsx"
  3. Get recent context: "Show me recent PRs related to call functionality"

Avoid overload:

  • Don't load entire directories at once
  • Focus on files relevant to your current task
  • Use targeted searches rather than broad exploration

2. Context Lifecycle Management​

Clear context between phases:

  • Planning → Implementation: Start fresh after creating your plan
  • Implementation → Review: Clear context before code review
  • Feature → Feature: Reset context when switching between unrelated tasks

Save important context:

  • Document key decisions in files that can be referenced later
  • Use project documentation (like CLAUDE.md) as persistent context

3. Context Refresh Patterns​

When to refresh context:

  • After 20+ interactions with the AI agent
  • When responses become less relevant or focused
  • When switching between different parts of the codebase
  • After completing a major task phase

How to refresh context in Claude Code:

  • Use /clear to completely clear the conversation history
  • Use /compact to compress the conversation while preserving key context
  • See Claude Code documentation for more commands

Signs of Context Pollution​

Performance indicators:

  • Slower response times from AI agents
  • Less relevant suggestions or recommendations
  • Repetitive questions about information already provided
  • Inconsistent coding patterns in generated code

Quality indicators:

  • Generic responses that don't align with your specific codebase
  • Outdated patterns that don't match current architecture
  • Missing context about recent changes or decisions

Best Practices​

Do's ✅​

  • Start fresh for each major task or phase
  • Use persistent documentation for stable project information
  • Load context incrementally based on immediate needs
  • Reference specific files rather than loading entire directories
  • Clear context when switching between unrelated tasks

Don'ts ❌​

  • Accumulate context across multiple unrelated tasks
  • Load excessive information "just in case"
  • Ignore performance degradation signs
  • Mix contexts from different projects or time periods
  • Skip context refresh when responses become unfocused

Creating Module CLAUDE.md Files​

For specific modules or directories, create local CLAUDE.md files to provide targeted guidance:

  1. Open the target directory (for example, modules/interop/ or app/jobs/)
  2. Run /init in your AI assistant while focused on that directory
  3. This creates a starter CLAUDE.md alongside the code
  4. Iterate in the same file as the module evolves

Module CLAUDE file guidelines:

  • Keep them short and high-signal (1–2 screens)
  • Include: purpose, 4–6 rules, 2–4 patterns/conventions, and references to key paths
  • Prefer identifiers in examples; avoid PHI/PII or secrets in samples
  • Link back to the root CLAUDE.md for global guidance