The Context Hierarchy

The three-layer model (project → conversation → prompt); what belongs at each level; how layers interact

The previous page introduced context engineering as the deliberate structuring of information for optimal agent performance. This page examines the architecture that makes systematic context engineering possible: a three-layer hierarchy that organizes information by persistence, scope, and purpose.

The three-layer model

Context in agentic development operates at three distinct levels, each with different lifespans and functions:

Project context persists across all conversations. It includes documentation files, code organization, naming conventions, and architectural decisions embedded in the codebase itself. This layer exists before any conversation begins and remains constant regardless of what tasks an agent performs.

Conversation context persists within a single session. It accumulates as dialogue progresses the questions asked, the code explored, the decisions made. When the session ends or resets, this context disappears.

Prompt context exists only for the current turn. It includes the immediate instruction, any task-specific data, and output format requirements. After the agent responds, this context merges into conversation history or vanishes entirely.

┌─────────────────────────────────────────────────────────────┐
│  PROJECT CONTEXT                                             │
│  • CLAUDE.md, AGENTS.md files                               │
│  • Code structure and naming conventions                     │
│  • Architecture documentation                                │
│  • Persistent across all sessions                            │
└──────────────────────────────────────────────────────────────┘
        ▼
┌─────────────────────────────────────────────────────────────┐
│  CONVERSATION CONTEXT                                        │
│  • Session history and files explored                        │
│  • Decisions made this session                               │
│  • Persists until session ends/resets                        │
└──────────────────────────────────────────────────────────────┘
        ▼
┌─────────────────────────────────────────────────────────────┐
│  PROMPT CONTEXT                                              │
│  • Immediate instruction                                     │
│  • Task-specific data and output requirements                │
│  • Exists only for current turn                              │
└──────────────────────────────────────────────────────────────┘

The hierarchy reflects how agents process information and where failures most commonly originate.

What belongs at each level

Project level

Project context should contain information that remains stable across sessions:

Architecture and technology stack How the system is organized, what frameworks it uses, how components communicate
Development commands Build steps, test commands, linting configurations
Code conventions Naming patterns, file organization, import ordering
Constraints Files that should not be modified, security boundaries
Workflow preferences Branching strategies, commit formats, PR conventions

Studies of CLAUDE.md files across thousands of repositories show effective files average 485-535 words. Brevity correlates with effectiveness 150 focused lines outperform 300 verbose lines.

Project context is the most cost-effective form of context engineering. Information placed here loads automatically into every conversation, eliminating repetitive explanation.

Conversation level

Conversation context accumulates during sessions. Different information types have different effective lifespans:

High persistence Explicit decisions, validated code changes, error solutions. These concrete outcomes anchor subsequent work.

Medium persistence Exploratory discussions, alternative approaches, troubleshooting sequences. These may compress during context management.

Low persistence Repetitive explanations, verbose descriptions already acted upon. These compress heavily when context approaches limits.

Research shows multi-turn conversation performance drops an average of 39% compared to single-turn interactions. Code generation tasks show particular vulnerability to this degradation.

Understanding what persists helps structure conversations for maximum retained context.

Prompt level

Effective prompts provide what the agent needs for the immediate task but cannot obtain from project or conversation context:

The specific request Clear, actionable language
Task-specific data Input values, file paths, edge cases unique to this request
Output requirements Format constraints, structure expectations
Temporal constraints Urgency indicators, priority signals

Information that persists across tasks belongs at higher layers. Project conventions restated in every prompt waste tokens and risk inconsistency. Agents perform best when prompt context is precisely scoped to the current need.

How the layers interact

The three layers form a cascade where each level builds on those below.

Loading order

Project context loads first CLAUDE.md files, code structure, naming patterns establish baseline knowledge.
Conversation context accumulates Each exchange adds to session history that the agent references.
Prompt context arrives last The immediate instruction combines with existing context to generate a response.

Project context shapes interpretation of everything that follows. Architectural decisions documented at the project level influence how the agent understands conversation history and interprets prompts.

More specific layers can override guidance from broader layers.

A project-level CLAUDE.md might specify "use TypeScript for all new files." A conversation might establish an exception: "this legacy module uses JavaScript." A prompt might further specify: "create this file in JavaScript to match adjacent files."

The cascade flows from general to specific. Project context sets defaults; conversation context establishes adjustments; prompt context provides final instruction.

Context budget allocation

The three layers compete for space in the same context window.

Project context consumes tokens on every request. Keep this layer focused essential information only.

Conversation context grows during sessions. Long conversations may require compaction or reset to prevent crowding.

Prompt context is controllable per-request. Complex tasks can allocate more budget here; simple tasks should be concise.

Context editing can reduce token consumption by 84% while enabling workflows that would otherwise fail from context exhaustion.

The practical guideline: treat context like memory in a constrained system. Every token spent in one place is unavailable elsewhere.

Designing for the hierarchy

Understanding the hierarchy transforms how developers structure work with agents.

Project setup becomes investment. A well-crafted CLAUDE.md eliminates thousands of repeated explanations. The effort is front-loaded; subsequent sessions benefit automatically.

Conversation strategy becomes deliberate. Clear opening statements establish context. Natural breakpoints trigger resets. Active monitoring catches degradation before it compounds.

Prompts become precise. With project and conversation context established, prompts focus on the immediate task. The hierarchy enables concise prompts that would otherwise require extensive explanation.

The foundation for practice

The context hierarchy is the organizing principle for everything that follows in this module.

The next pages examine each layer in detail: project context through documentation patterns, conversation context through session management, and prompt context through construction patterns.

Understanding where information belongs enables placing it correctly. Correct placement enables consistent results. Consistent results transform agent interaction from art into engineering.