Context Engineering

When to Use

• Delegating a complex task to an AI agent
• An agent keeps repeating the wrong approach
• Agent quality drops as the context grows longer
• Designing a pipeline where multiple agents collaborate

Difference from context-prime (Copilot-specific):

• context-prime: loads live project context at session start
• context-engineering: structures the best possible information for a specific task

Prerequisites

• The delegated task has a clear goal and scope
• You know the relevant files or domain area

Workflow

1. Analyze signal vs. noise

Classify the information you plan to give the agent:

Information type	Include?	Why
Directly relevant code files	✅ Yes	The agent must edit or reason about them
Interface/type definitions	✅ Yes	Essential for understanding contracts
Unrelated files	❌ No	Waste tokens and reduce focus
Entire README	❌ No (summarize instead)	Low information density for the size
Information the agent already has	❌ No	Duplicate token cost

2. Progressive Disclosure

Do not provide everything at once. Reveal only what each phase needs:

Phase 1: Task definition + interface contract
Phase 2: Implementation starts -> add relevant files
Phase 3: Testing -> add test patterns and references

3. Use a structured context template

Use this shape when instructing an agent:

## Task
[one clear objective]

## Given (what is already known)
- [file path]: [role]
- [interface contract]

## Constraints (what must not happen)
- [prohibited action]
- [files that must not be changed]

## Done When
- [ ] [specific, testable criterion]

4. Manage the context-window budget

Use context size intentionally. For exact model choice, see multi-model-strategy:

Task complexity	Context size	Example
Short task (fast response first)	2-3 files, clear goal	small bug fix, type addition
Medium task (balanced)	5-10 files, interface contract	new API endpoint, component addition
Long task (deep reasoning first)	10-20 files, module-level context	architecture refactor, complex bug

5. Run a result-verification loop

If the agent output is off-target:

1. Find ambiguity in the supplied context
2. Add explicit constraints
3. Make the "Done When" criteria more concrete
4. Repeat and rerun the agent

Common Rationalizations

Rationalization	Reality
"More context is always better"	Irrelevant information distracts the agent. Signal-to-noise ratio matters more than volume.
"I'll just give the whole codebase"	That wastes tokens and often lowers agent quality. Include only the files that matter.
"Natural language is enough; the agent will figure it out"	Without explicit completion criteria, the agent does not know where to stop.

Red Flags

• The agent repeats the same mistake
• The response drifts far from the actual request
• The task prompt has no "Done When" criteria
• You pasted the entire README or whole directories into context

Verification

• The task prompt contains one clear objective
• Unrelated files were excluded from context
• Completion criteria are explicit and testable
• The agent output satisfies the stated completion criteria

Examples

Before (bad)

"Look through the project, find a bug, and fix it."

After (good)

## Task
Fix the JWT expiry-validation bug in `src/auth/token.ts`.

## Given
- `src/auth/token.ts`: target file to change
- `src/auth/token.test.ts`: existing tests
- Bug: the `exp` claim is a Unix timestamp, but the code compares it as milliseconds

## Constraints
- Do not modify files outside `src/auth/`
- Do not change existing function signatures

## Done When
- [ ] All existing tests pass
- [ ] The `exp` comparison uses seconds
- [ ] New edge-case tests cover just-before and just-after expiry

Tips

• Pair this with spec-driven-development: a good spec becomes a reusable context template
• Use multi-model-strategy to pick a model that matches task complexity
• If the agent misses twice in a row, revisit the context structure instead of only rewording the ask

Advanced Techniques

Full-Repo Context Loading with rendergit

rendergit renders an entire Git repository into a browser-based HTML view with an LLM-friendly text export. Useful when you need the AI to understand the whole codebase at once (e.g., cross-cutting refactors, architecture analysis).

# Install (Python required)
pip install git+https://github.com/karpathy/rendergit

# Open browser view of the entire repo
rendergit .
# In the browser, switch to "LLM View" to copy the CXML-formatted codebase text.
# Paste into your session context or save to a file to attach as context.

When to use rendergit:

• Architecture analysis requiring understanding of all modules
• Finding all usages of a pattern across the entire codebase
• Onboarding a new AI agent to a large, unfamiliar project

When NOT to use:

• Single-file tasks (wasteful — just include the relevant files)
• Repos > 200k tokens (exceeds most model limits; use selective inclusion instead)

KV-Cache Optimization

LLMs recompute the KV-cache for every token in context. For repeated agent invocations on the same context (e.g., analyzing multiple files with the same system prompt), cache-aware context structuring reduces cost significantly.

Principle: Place stable content (system prompt, shared context) before variable content (the specific task or file). This enables KV-cache reuse.

✅ Cache-friendly structure (stable content first):
[System prompt + project rules]           ← cached across requests
[Shared context: types, interfaces]       ← cached if unchanged
[Variable: specific file to analyze]      ← changes per request

❌ Cache-unfriendly structure (variable content first):
[Variable: today's date, run ID]          ← busts cache on every call
[System prompt]
[Context]

Practical application in agent instructions:

## Context (stable — appears in every call)
Project: everything-copilot-cli
Rules: follow existing SKILL.md conventions
Output format: Markdown with frontmatter

## Task (variable — changes per call)
Analyze: skills/development/tdd-workflow/SKILL.md
Find: missing edge cases in the Verification checklist

Token budget estimation:

Context type	Typical size	Cache reuse potential
System prompt	500-2000 tokens	High (same across session)
Project conventions	1000-5000 tokens	High
Specific file to analyze	500-3000 tokens	Low (changes per task)
Task instruction	100-500 tokens	Low

For multi-model pipelines with the same shared context, pass context by reference (file path + MCP view tool) rather than inline copy-pasting.

Latent Briefing

When work spans multiple agent turns or session boundaries, preserve only the durable state the next agent actually needs. Treat the handoff as a compact briefing, not a full transcript dump.

Pattern:

1. Capture findings, decisions, and open questions at the end of an agent step
2. Store them in a durable medium the next step can actually read (sql, task notes, or a checked-in doc when appropriate)
3. Inject only that briefing into the next agent's context, then add fresh task-specific files or constraints

When to use:

Scenario	Use latent briefing?
Parallel agents analyze different subsystems, then a synthesizer combines the results	✅ Yes
A later session resumes a partially completed task	✅ Yes
One agent keeps iterating inside the same short-lived context window	❌ No — keep the live context focused instead

Briefing shape (minimal):

Task: [current objective]
Done so far:
- [finding]
- [decision]

Open questions:
- [question]

Next constraints:
- [what must not change]

For Copilot CLI specifically, pair this with cross-session-memory when the handoff must survive across sessions rather than just across turns.