Microsoft AB-100: GitHub Copilot Context Engineering

GitHub Copilot performs better when it receives durable project context instead of being asked to rediscover the repository on every task. Context engineering is the practice of shaping that information deliberately: repository instructions, path-specific rules, agent guidance, build commands, architecture notes, task-specific prompts, and the files or symbols most relevant to the current work.

Current GitHub guidance supports several customization layers. Repository-wide instructions live in .github/copilot-instructions.md. Path-specific instructions live under .github/instructions/. Agent instructions can live in files such as AGENTS.md. Prompt files and skills can provide reusable task-specific context. Each layer solves a different problem.

This makes context engineering a practical part of business AI for software-development teams.

Start with repository-wide context

Repository instructions should explain durable information Copilot needs across many tasks: what the project does, major technologies, important architectural rules, build and test commands, and conventions that are easy to get wrong.

Copilot code review can use the same repository context when reviewing pull requests.

Keep repository guidance short enough that it remains relevant to most work in the repository.

Use path-specific instructions for local rules

A monorepo or large application often contains subsystems with different frameworks, validation steps, or style expectations.

Path-specific instruction files let teams apply rules only where they matter.

This reduces noise and prevents frontend, database, infrastructure, and test rules from being injected into every unrelated task.

Use AGENTS.md for agent-facing guidance

AGENTS.md can document standing instructions for AI coding agents and can be placed in the repository hierarchy so the nearest relevant file applies.

Use it for durable agent behavior such as how to build, test, validate, and navigate the project.

Do not fill it with task-specific instructions that belong in the current request.

Document build and validation paths

One of the most valuable forms of context is operational: the commands that actually work.

Tell Copilot how to install dependencies, run unit tests, execute integration tests, lint, format, generate code, and validate the project.

Context that prevents a failed build often creates more value than a long prose description of coding style.

Explain intentional architecture

AI tools can mistake unusual but intentional patterns for mistakes. Document important constraints, generated code boundaries, legacy compatibility requirements, and areas where changes need extra care.

This is especially helpful for code review and coding agents because it reduces “helpful” rewrites that violate design decisions the model cannot infer from one file.

Context should explain why a constraint exists when that reason affects implementation choices.

Avoid conflicting instruction layers

GitHub can provide several instruction sources at once. Conflicting guidance creates ambiguity and can reduce output quality.

Keep broad principles at repository or organization level and narrow exceptions in path-specific files.

Review the combined instruction set when Copilot behavior becomes inconsistent instead of assuming the model simply ignored one file.

Use task-specific context sparingly

The current task may require design documents, issue text, examples, logs, or files that do not belong in standing repository instructions.

Attach or reference that context only for the task that needs it.

This keeps durable instructions stable while still giving Copilot enough local evidence to complete specialized work.

Prefer concise authoritative sources

A short maintained architecture note is more useful than several stale documents that disagree.

Context quality matters more than context volume. Extra text can distract from the files and rules that actually govern the change.

Prompt management applies here too: reusable instructions should be curated, versioned, and retired when obsolete.

Measure context by outcomes

Good context reduces failed builds, rejected pull requests, repeated repository exploration, and corrections for known conventions.

Copilot metrics can show adoption and engagement, but teams should also track practical repository outcomes such as review rework and validation failures.

For current GitHub Copilot workflows, context engineering means giving AI tools the smallest reliable set of persistent project knowledge they need, scoped to the right repository or path, and keeping that context as maintainable as the code itself.

Context engineering should begin by observing where Copilot repeatedly wastes time. If every task starts with searching for the build command, architecture entry point, generated files, or test location, those facts belong in durable repository context.

Repository instructions should avoid restating information the codebase already makes obvious. The highest-value context explains relationships, constraints, and workflows that are difficult to infer from filenames alone.

Keep commands executable. If the instruction says “run tests,” include the actual command and any required working directory, environment setup, or prerequisite service. Context that is technically correct but incomplete still causes failed agent runs.

Path-specific instructions can encode local architecture. For example, one directory may prohibit direct database access, another may require generated clients, and a third may contain code that should never be edited manually. This information is far more useful when scoped to the path it governs.

Agent instructions should include recovery guidance for known repository quirks. If a test command commonly fails because a service must be started first, document the supported workaround. The point is to reduce repeated exploration and predictable failure, not to hide broken tooling permanently.

Prompt files can hold reusable task patterns such as creating a migration, preparing a release note, or reviewing a security-sensitive change. Keep those separate from always-on context so Copilot receives specialized instructions only when the task requires them.

Skills and MCP tools can add operational capability, but context should still explain when those tools are appropriate. Giving an agent more tools without decision guidance can increase exploration and side effects rather than improving results.

Review context files like code. Remove stale commands, update renamed paths, resolve contradictions, and test significant changes. The repository’s AI context becomes infrastructure for future work, so neglecting it creates the same kind of drift as an outdated build script.

Context should also identify files that are authoritative. If generated documentation, examples, and source code disagree, tell Copilot which layer controls behavior. Otherwise the agent may update a derived file while leaving the real source unchanged.

Large repositories benefit from navigation hints. Name the important entry points, package boundaries, ownership files, architecture directories, and common test locations. This reduces broad search and helps the agent form a correct mental model before editing.

Security-sensitive context should be useful without exposing secrets. Explain where credentials are injected, which APIs require special care, and which files must never contain tokens, but keep actual secret values outside instruction and prompt files.

Finally, evaluate context changes on representative tasks. If a new instruction file reduces exploration but causes overly rigid edits or conflicts with another layer, revise it. Context engineering is iterative: the best context is the smallest maintained set that consistently improves task success.

Context windows are finite, so always-on instructions should earn their space. Remove lengthy explanations that rarely affect implementation and replace them with links or short pointers when the agent can inspect the source only when needed. Concision improves the chance that critical rules remain salient.

Repositories with multiple languages should identify the supported runtime and validation path per area. A generic instruction to “run tests” is less useful than telling the agent which package manager, test runner, or build system applies to the files it is changing.

Generated artifacts need explicit handling. State whether Copilot should edit generated files, run the generator, or leave them untouched. This prevents patches that look correct in the diff but are overwritten the next time the build regenerates code.

Ownership context can help agents route work. CODEOWNERS, directory descriptions, and architecture notes can reveal which subsystem a change belongs to and which interfaces should remain stable. That helps avoid edits that cross boundaries simply because the model found a nearby implementation.

Context engineering should include failure lessons. If a previous agent repeatedly edited the wrong file, skipped a required validation step, or misunderstood a generated directory, capture the durable lesson in the appropriate instruction file instead of relying on future users to remember the correction.

Over time, repository context becomes an onboarding asset for humans as well as AI. Clear build commands, architecture boundaries, and validation rules reduce tribal knowledge. That dual value is a good signal that the context is explaining the project rather than merely gaming one AI tool.

Keep a short change history for important context files. When agent behavior improves or regresses after an instruction update, maintainers can connect the effect to the specific context change instead of guessing.

Review context when repository ownership changes.

Keep context current.