Context Engineering

Context Engineering

Design effective prompts and optimize the full context window for AI models and agents to produce consistently high-quality output.

Quick Start

Recipe 1: Improve a vague prompt

Before: Review this code and give feedback.

After:

<task>Review the provided code for correctness, performance, and maintainability.</task>
<output-format>
For each issue: file/line, severity (critical|warning|suggestion), problem (one sentence), fix (concrete code change).
If no issues, state "No issues found" and list one strength.
</output-format>
<code>{{code_to_review}}</code>

Why it works: Specifies evaluation criteria, defines output structure, separates instructions from data with XML tags.

Recipe 2: Design a system prompt

Use the altitude concept -- not so high it's useless ("be helpful"), not so low it's brittle ("always use 4 spaces").

1. Define the role in one sentence: what the agent IS and IS NOT
2. Set altitude -- right level: "Follow the project's existing naming conventions. When none exists, prefer descriptive names over short ones."
3. Add constraints using RFC 2119 language (MUST, SHOULD, MAY)
4. Include 1-2 canonical examples of ideal output
5. Define non-goals to prevent scope creep

See references/system-prompt-design.md for full anatomy and templates.

Recipe 3: Structure agent context with the 4 strategies

When your agent produces inconsistent or degraded output, apply the four strategies:

1. Start with Write: define a clear system prompt
2. Apply Select: give the agent only the tools and context it needs
3. Add Compress: implement compaction for long sessions
4. Use Isolate: move large reference material behind retrieval

See references/context-engineering-framework.md for the full framework.

The Evolution: Prompt to Context Engineering

Context engineering manages everything the model sees -- system prompt, tools, retrieved documents, conversation history, and memory. Every token either helps or hurts. The entire context window is a design surface.

Prompt Engineering Foundations

These eight techniques form the foundation. Master them before moving to context engineering.

Combining techniques: Most effective prompts use 3-5 techniques together. A code review prompt might combine clarity (#1), XML structure (#4), role (#5), and examples (#2).

See references/prompt-foundations.md for detailed explanations, examples, and anti-patterns for each technique.

Context Engineering Framework (4 Strategies)

Write: Craft the persistent context

The Write strategy covers everything you author in advance: system prompts, tool descriptions, and instruction files. This is the context you control completely.

The altitude concept is the most important principle. Your instructions need to be at the right level of abstraction:

Canonical examples are powerful -- a single well-chosen example communicates more than paragraphs of rules:

<system>
You generate API documentation from source code.
<example>
<input>
def calculate_tax(amount: float, rate: float = 0.08) -> float:
    """Calculate sales tax for a given amount."""
    return round(amount * rate, 2)
</input>
<output>
### `calculate_tax(amount, rate=0.08)`
Calculate sales tax for a given amount.
- `amount` (float): The pre-tax amount
- `rate` (float, optional): Tax rate as decimal. Default: 0.08
- **Returns:** float -- Tax amount, rounded to 2 decimal places.
</output>
</example>
</system>

Project-level Write strategy: Use the /project-governance skill to create a constitution (oak/constitution.md) and agent instruction files. Your constitution IS your project-level system prompt. The altitude concept applies directly: "write good code" is useless; "copy src/features/auth/service.py for new services" is actionable.

See references/context-engineering-framework.md for the full Write strategy guide.

Select: Choose what enters the context window

Select the right information to include; keep everything else out.

For tools: Provide the minimal viable toolset (unused tools cause confusion), write unambiguous descriptions (the model uses these to decide when to call), and prefer specific tools over general-purpose ones.

For retrieved context: Quality over quantity (3 relevant snippets beat 20 loose ones), recency matters, and always include source attribution (file paths, line numbers).

Anti-pattern -- context stuffing:

# Bad: dumping everything "just in case"
context = all_docs + all_code + all_history + all_memories
# Good: selecting what's relevant
context = search_relevant_code(task) + get_recent_decisions(task)

Compress: Reduce tokens while preserving information

Compress rather than truncate. Preserve signal while reducing cost.

Strategies: Conversation summarization (replace old turns with structured summary), note-taking scratchpad (running notes vs. re-reading history), sub-agent delegation (offload research, return only findings), and tool result cleanup (extract then clear verbose output).

When to compress: Context exceeds 50% capacity, agent forgets earlier instructions, responses repeat or lose focus, or tool results contain mostly irrelevant data.

Isolate: Move information out of the main context

Store information externally and load just-in-time, rather than keeping it in context at all times.

Patterns: Just-in-time retrieval (load docs only when needed), progressive disclosure (summary first, details on demand), hybrid context loading (rules in system prompt, reference material behind search), and memory-as-a-tool (store externally, retrieve on demand).

Progressive disclosure example: Agent sees summary ("Auth uses JWT") -> needs details (retrieves auth docs) -> needs code (retrieves auth service file). Each step loads only what's needed.

See references/context-engineering-framework.md for the complete framework with extended examples.

Agent Context Patterns

Sessions vs memory

The common mistake: keeping everything in the session instead of writing important things to persistent memory.

Context rot

Output quality degrades as conversations grow longer due to: dilution (instructions buried under tool results), position bias (models attend more to beginning/end, losing middle), contradiction accumulation, and working memory overflow.

Signs: Agent forgets earlier constraints, responses become generic/repetitive, re-asks answered questions, quality drops vs. early turns.

Mitigation: Apply Compress (summarize and compact) and Isolate (move reference material behind retrieval). For long-running agents, implement periodic compaction checkpoints.

Memory types

Memory-as-a-tool pattern

Store externally, retrieve on demand -- instead of accumulating in context:

1. Discover → oak_remember("auth tokens expire after 1 hour", type="discovery")
2. Later   → oak_search("auth token expiry") retrieves just-in-time
3. Stale   → oak_resolve_memory(id, status="resolved") cleans up

This implements both Compress (don't hold everything) and Isolate (retrieve when needed).

Compaction strategies

See references/agent-context-patterns.md and references/memory-and-sessions.md for detailed patterns and implementation guidance.

CI Integration: Context Engineering in Practice

OAK's Codebase Intelligence tools directly implement the four context engineering strategies:

Example workflow

# WRITE: Store a discovery for future sessions
oak ci remember "Payment service retries 3x with exponential backoff" --type discovery
# SELECT: Find relevant code for a task
oak ci search "payment retry logic" --type code -n 5
# ISOLATE: Assemble just-in-time context
oak ci context "fix payment timeout bug" -f src/services/payment.py
# CONSOLIDATE: Clean up after fixing
oak ci resolve <memory-id>

Before/After Gallery

Vague prompt to structured prompt

Before: Write tests for the user service.

After:

<task>Write unit tests for UserService: create_user, get_user_by_email, delete_user.</task>
<constraints>
- pytest with fixtures for setup/teardown
- Test success and error paths for each method
- Mock external API calls (email verification)
- Descriptive test names: test_create_user_with_duplicate_email_raises_conflict
</constraints>

Bloated system prompt to altitude-optimized

Before (micromanaging): "Always use f-strings. Always use pathlib. Always use type hints. Use black with line length 88. Use dataclasses for DTOs. Never use print()..."

After (right altitude):

<role>You are a Python developer working in this project.</role>
<principles>
- Follow existing patterns. Find the closest implementation and mirror its style.
- Prefer modern Python (3.10+). When in doubt, check what the codebase uses.
- Write code that reads clearly without comments. Comment only non-obvious "why" decisions.
</principles>
<quality>Run `make check` before considering any change complete.</quality>

Context-stuffed agent to compress + isolate

Before: 40,000 tokens (2K rules + 3K README + 8K tool descriptions + 12K API docs + 15K conversation = half irrelevant)

After: 8,000 tokens (800 altitude-optimized prompt + 1,200 for 5 relevant tools + 2,000 retrieved context + 4,000 compressed conversation = all relevant)

See references/before-after-examples.md for the full gallery with additional transformations.

When to Use What

Deep Dives

For detailed guidance on specific topics, consult the reference documents:

• references/prompt-foundations.md -- Core prompt engineering techniques with examples and anti-patterns
• references/context-engineering-framework.md -- The four strategies (Write, Select, Compress, Isolate) in depth
• references/agent-context-patterns.md -- Sessions, memory types, context rot, and compaction strategies
• references/system-prompt-design.md -- System prompt anatomy, the altitude concept, and reusable templates
• references/memory-and-sessions.md -- Memory types, the memory-as-a-tool pattern, and OAK CI integration
• references/before-after-examples.md -- Extended gallery of prompt and context transformations
• references/evaluation-and-testing.md -- Measuring prompt quality, A/B testing, and iterative improvement