Context engineering for AI coding agents means designing the information environment around a task: what the agent sees first, what it can discover later, which facts are authoritative, and how stale assumptions lose priority.
The goal is not maximum context. It is the smallest reliable path from the user's outcome to current evidence.
Four layers of useful context
- Task: the current outcome, scope, completion evidence, and stop conditions.
- Project: stable product boundaries, build commands, conventions, and document map.
- History: verified decisions, failed paths, recent handoff, and exact identities.
- External: current contracts, documentation, market evidence, or runtime state needed for this task.
Put the task first. Make the other layers discoverable. A giant prompt that mixes all four forces the agent to decide what matters before it even understands the job.
What belongs in repository instructions?
Use AGENTS.md, CLAUDE.md, or equivalent files for rules that apply broadly across the repository:
- how to build and test;
- code and module conventions;
- public boundaries that must not drift;
- safe defaults for editing and verification;
- pointers to focused documents.
GitHub supports repository-wide, path-specific, and agent instruction files across several Copilot surfaces: custom instructions support.
Keep instructions concise. OpenAI describes learning that one huge AGENTS.md consumed scarce context and diluted guidance; a navigable repository map worked better: Harness engineering.
What belongs in the task brief?
Task-specific facts should not become permanent rules:
- the user's request;
- the first broken link;
- files currently implicated;
- exact version or deployment being examined;
- expected checks;
- temporary exclusions.
The brief expires with the task. Promoting it to global instructions creates stale rules.
What belongs in project memory?
Memory should preserve facts a future session is likely to reuse:
- a confirmed product decision and its reason;
- a verified integration entry point;
- a failure pattern that repeated;
- a stable user preference;
- the last handoff for unfinished work.
Do not save raw logs, every command, or an unverified diagnosis as stable memory. Keep evidence references so a new agent can check the current system.
Use progressive retrieval
A reliable startup sequence is:
- Read the current task and hard boundaries.
- Inspect the smallest relevant code and runtime state.
- Query the document or memory index with a concrete problem.
- Open only high-relevance sources.
- Expand the search when new evidence shows a shared dependency.
VS Code's own guidance separates automatically selected workspace context from explicitly attached files, folders, symbols, terminal output, and source-control changes: Add context to chat.
Test the context, not just the answer
Good context should change execution quality. Check whether a fresh session can:
- locate the current authority quickly;
- avoid a known failed path;
- name the correct verification;
- preserve the product boundary;
- produce a smaller, more relevant diff.
If the session still needs the full old chat, the durable context is incomplete. If every task receives pages of irrelevant rules, the context is too broad.
Common failure modes
- Transcript dumping: preserves conversation order, not current truth.
- Everything is permanent: turns one incident into a universal rule.
- Search by generic words: retrieves “project” and “task” instead of the actual problem.
- Memory outranks code: lets old notes override current behavior.
- No evidence pointer: makes a future agent trust prose it cannot verify.
A practical context brief
Outcome
What the user can do afterward.
Current evidence
Files, tests, logs, pages, and exact identities.
Invariants
Product behavior, data authority, privacy, and public contracts.
Retrieval index
Which focused documents or memory queries may be needed.
Verification
What the final consumer must show.
Handoff
Verified state, remaining gap, and next safe action.
The core principle
Context engineering is information architecture for action. Give the agent a clear task, a trustworthy map, and permission to retrieve detail when evidence requires it.