context-engineering

Context Engineering

Apply the four context engineering strategies -- Write, Select, Compress, Isolate -- to maximize agent effectiveness while minimizing token costs.

When to Use

• Designing what context an agent receives before execution
• Optimizing a system prompt that is too long or unfocused
• Reducing token costs on expensive LLM calls
• Setting up context isolation between agents in a multi-agent system
• Debugging an agent that "forgets" instructions or loses focus

Available Operations

1. Write persistent context (CLAUDE.md, agents.md, skills)
2. Select relevant context via retrieval
3. Compress context to reduce token usage
4. Isolate context per agent scope
5. Budget context allocation across the window

Multi-Step Workflow

Step 1: Write Context -- Persistent Memory

Define what the agent "knows" before any task begins. This is your baseline context layer.

CLAUDE.md          -> Project standards, architecture, decisions
agents.md          -> Agent-specific behavior and role definition
skills/SKILL.md    -> On-demand capabilities loaded when needed
memory/            -> Learnings from previous executions

Check your CLAUDE.md token count:

wc -w CLAUDE.md  # Should be under ~1500 words (~2000 tokens)

Rule: CLAUDE.md must stay under 2000 tokens. If it grows beyond that, move details into skills that are loaded on-demand.

Step 2: Select Context -- Retrieval for the Current Task

Inject only the context relevant to the current task. Never dump everything.

def select_context(task: Task, retriever) -> str:
    # Retrieve skills relevant to the task
    relevant_skills = retriever.invoke(task.description)

    # Search for related code in the repository
    related_code = code_search(task.description, worktree_path)

    # Find similar past decisions
    past_decisions = memory_store.search(task.description, k=3)

    return format_context(relevant_skills, related_code, past_decisions)

Rule: Never inject more than 30% of the context window with selected context. Leave space for the agent to reason.