Context Engineering Field Guide

Most AI agent sessions don't fail because the model is bad. They fail because the context window is a mess: stale instructions competing with fresh ones, intermediate reasoning from three tasks ago still consuming budget, tool outputs no one needed after the first read. The model sees everything loaded into it and does its best. The problem is what you loaded.

This field guide names four failure modes that kill real production sessions: context rot (accumulated noise that degrades output quality without obvious errors), instruction drift (rules that worked at session start no longer matching behavior at turn 40), token bloat (budget consumed by content that stopped being load-bearing), and agent loop thrashing (the agent cycling through failed approaches without recognizing the repetition). Each has a named chapter and a repair procedure.

The guide is organized around five disciplines that together form a harness model for context management: Generate (what the agent always knows, from CLAUDE.md to hook-loaded rules), Retrieve (pulling the right context at the right moment, not everything always), Compress (shrinking what's already loaded without losing what matters), Route (matching instructions to context rather than broadcasting all rules to all tasks), and Evict (clearing what the session no longer needs). The five disciplines are not independent. They compose into a harness: a system that keeps the context window accurate, minimal, and current across the full arc of a session.

Worked examples throughout: a CLAUDE.md refactor that cut instruction noise by 60%, a retrieval pipeline that routes summaries and raw spans to the right agent tier, a subagent dispatch pattern that keeps the orchestrator context small, an on-disk hook that enforces dispatch discipline without relying on the model's memory, and a scored eval framework that measures context quality with numbers instead of intuition. Every pattern is deployable without a framework change.

contents

• Chapter 1: Context Is the New Code
• Chapter 2: Prompt Soup: The Four Failure Modes Killing Your AI Sessions
• Chapter 3: The Harness Model
• Chapter 4: Generate: Engineering What the Agent Always Knows
• Chapter 5: Retrieve: Pulling the Right Context at the Right Moment
• Chapter 6: Compress: Shrinking What You've Already Loaded
• Chapter 7: Route: The Rules That Actually Apply Right Now
• Chapter 8: Evict: Clearing What the Session No Longer Needs
• Chapter 9: Sandwich Architecture
• Chapter 10: Orchestrator and IC Roster
• Chapter 11: Hook-Enforced Discipline
• Chapter 12: Eval-Driven Context Tuning
• Worksheet 1: Context Budget Calculator
• Worksheet 2: Prompt-Soup Diagnostic (12 Questions)
• Worksheet 3: Rule-Router Cheat Sheet
• Worksheet 4: Subagent Dispatch/Return Template
• Worksheet 5: 30-Day Migration Plan
• Appendix: Glossary

Theoretical grounding: Context as Cognitive Substrate