| name | context-engineering |
| description | Feed agents the right information at the right time — rules files, context packing, MCP integrations. Use when starting a session, switching tasks, or when agent output quality drops due to missing context. |
Context Engineering
Overview
Agent output quality is bounded by input context quality. Context engineering is the practice of feeding agents the right information at the right time — not everything, but exactly what's needed for the current task. Too little context produces hallucinations. Too much dilutes attention.
When to Use
- Starting a new coding session with an AI agent
- Switching between tasks or repositories
- Agent output quality drops (wrong assumptions, missing patterns)
- Setting up a repository for first-time agent use
- Onboarding a team to agent-assisted workflows
When NOT to use: The agent already has the right context and is producing good output.
The Context Stack
Agents consume context from multiple layers. Each layer has a different scope and persistence:
┌─────────────────────────────────────┐
│ Layer 5: Conversation │ ← Ephemeral (this session)
│ Pasted code, error messages, URLs │
├─────────────────────────────────────┤
│ Layer 4: Skills │ ← On-demand (loaded when relevant)
│ SKILL.md files, reference docs │
├─────────────────────────────────────┤
│ Layer 3: Instructions │ ← Auto-attached per file type
│ .instructions.md with applyTo │
├─────────────────────────────────────┤
│ Layer 2: Project Rules │ ← Always loaded
│ copilot-instructions.md, CLAUDE.md │
├─────────────────────────────────────┤
│ Layer 1: Agent Definition │ ← Set once per agent
│ .agent.md persona and constraints │
└─────────────────────────────────────┘
Context Engineering Patterns
Pattern 1: Rules Files
Place conventions and boundaries in rules files so agents follow them automatically:
| File | Tool | Scope |
|---|
.github/copilot-instructions.md | GitHub Copilot | All sessions in this repo |
CLAUDE.md | Claude Code | All sessions in this repo |
AGENTS.md | Codex, multi-agent | All agents in this repo |
.cursorrules | Cursor | All sessions in this repo |
.windsurfrules | Windsurf | All sessions in this repo |
Keep rules files concise. They're loaded into every session — bloated rules waste context window on every interaction.
Pattern 2: Progressive Disclosure
Don't dump everything upfront. Structure context so it loads when needed:
Always loaded: Project conventions, tech stack, boundaries
On file open: Language-specific rules (.instructions.md with applyTo)
On demand: Skills (loaded when task matches description)
On request: Reference checklists, supporting docs
Pattern 3: Context Packing
When starting a task, pack the relevant context into the first message:
## Task
[What you're building]
## Relevant Files
- `src/auth/middleware.ts` — Current auth implementation
- `src/types/user.ts` — User type definitions
- `tests/auth/` — Existing auth tests
## Constraints
- Must maintain backward compatibility with v2 API
- Auth tokens expire after 24 hours
- Rate limit: 100 requests/minute per user
## Spec
[Link or paste the relevant spec section]
Pattern 4: MCP Integrations
Model Context Protocol servers extend what agents can access:
| MCP Server | Provides |
|---|
| GitHub MCP | Issues, PRs, repo metadata, file contents |
| Filesystem MCP | Read/write access to local files |
| Fetch MCP | Web page content, API responses |
| Memory MCP | Persistent notes across sessions |
| Database MCP | Schema inspection, query execution |
Configure MCP servers in .vscode/settings.json or the tool's config file. Only enable servers the project actually needs — each server adds to the context window.
Pattern 5: Session Priming
Start each session with a brief orientation:
I'm working on [project]. The stack is [tech stack].
Today I'm implementing [task] from [spec/issue link].
The relevant code is in [directory].
Run tests with [command]. Build with [command].
This gives the agent enough context to make good decisions without reading the entire codebase.
Context Anti-Patterns
| Anti-Pattern | Fix |
|---|
| Dumping the entire codebase into context | Reference specific files. Use search to locate relevant code. |
| Rules file over 200 lines | Split into separate instruction files with applyTo globs. |
| Repeating the same context every message | Put it in a rules file or instruction file — load it once. |
| No project rules at all | Agent guesses conventions. Create a minimal rules file. |
| Skills that are 1000+ lines | Split into SKILL.md (entry point) + supporting reference files. |
| Ignoring agent mistakes | Mistakes often signal missing context. Add the missing info to rules. |
Setting Up a New Repository
Minimum context setup for any repository:
- Create
.github/copilot-instructions.md — Tech stack, conventions, build/test commands
- Add
.instructions.md files — Per-language rules with applyTo globs
- Add relevant skills — Copy the skills your workflow uses
- Configure MCP servers — GitHub, Filesystem at minimum
- Test the setup — Ask the agent a question about the project. If it gets the tech stack wrong, your context is insufficient.
Common Rationalizations
| Rationalization | Reality |
|---|
| "The agent should figure out the context itself" | Agents can explore, but cold-start exploration wastes tokens and time. Provide the starting point. |
| "I don't need rules files, I'll just tell it each time" | You'll forget. Teammates won't know. Rules files make context persistent and shared. |
| "More context is always better" | Context windows are finite. Irrelevant context dilutes attention and increases hallucination. |
| "Setting this up takes too long" | A 15-minute setup saves hours of correcting agent mistakes across every session. |
Red Flags
- Agent consistently misidentifies the tech stack or patterns
- Agent suggests deprecated APIs or wrong conventions
- You're copy-pasting the same context into every session
- Rules files are so long that agents ignore parts of them
- Skills are never activated because descriptions don't match tasks
- No MCP servers configured for a project that needs external data
Verification
After setting up context for a repository:
