Context crafting for GitHub Copilot means giving Copilot persistent repository knowledge, path-specific rules, task-specific prompt templates and curated project references so it spends less time guessing how a codebase works. Current GitHub Copilot supports repository-wide custom instructions in .github/copilot-instructions.md, path-specific .github/instructions/*.instructions.md files, AGENTS.md instructions, prompt files, custom agents, Copilot Spaces and MCP integrations. The right mix depends on whether the information should apply always, only to certain files, or only to one reusable task.
Within Microsoft AI Agents, context crafting is an engineering discipline: decide what project knowledge should be automatic, what should be retrieved on demand, and what belongs in source-controlled instructions rather than repeated in every prompt.
Put stable repository facts in custom instructions
Repository-wide instructions should capture build/test commands, architecture conventions, formatting rules, dependency constraints and non-obvious workflow expectations.
Keep them concise enough that they remain relevant to most requests.
Do not turn the file into a full repository dump.
Use path-specific instructions for local conventions
Current GitHub docs support .instructions.md files with applyTo glob patterns.
Use these for frontend/backend, language-specific, infrastructure or test-folder rules that should not burden unrelated tasks.
Keep overlapping instruction sets consistent to avoid contradictory guidance.
AGENTS.md can express agent-oriented local guidance
GitHub Copilot supports agent instructions using AGENTS.md, with nearer files taking precedence in supported agent contexts.
This is useful in monorepos where different services have different build or validation steps.
Use it to tell agents what commands are known-good and what must be verified before a change is considered complete.
Prompt files are for repeatable tasks
Prompt files live under .github/prompts and can encode a reusable task template.
Use them for activities such as security review, migration checklist, test-plan generation or pull-request preparation.
Do not put task-specific wording into always-on repository instructions.
Curate context instead of telling Copilot to read everything
Large repositories contain generated files, vendored dependencies, archives and obsolete experiments.
Point Copilot toward architecture docs, build scripts, tests, configuration and the source directories that actually define behavior.
This reduces noise and makes code search more intentional.
Document commands that really work
Repository instructions should specify exact build, lint, test and validation commands—and known order/dependencies.
If a command fails in the normal environment and requires a workaround, document that too.
This can prevent coding agents from spending most of their budget rediscovering setup errors.
Keep instructions in the same review process as code
Instruction files affect how agents change the repository.
Review them through pull requests, test them on representative tasks and update them when build systems or conventions change.
Stale instructions can be worse than no instructions because the agent follows outdated commands confidently.
Use Copilot Spaces for curated multi-resource context
Current GitHub Copilot offers Spaces for organizing project context that can ground responses.
Use a Space for cross-repository or project material that should be discoverable but does not belong in one code repository’s permanent instruction file.
Keep source ownership and freshness visible so curated context does not become an undocumented copy of old policy.
MCP should add tools/data, not replace repository context
MCP servers can expose external services or data to Copilot agents.
Use them when the agent must query issue trackers, documentation, deployment systems or other live resources.
Keep repository build/test conventions in source-controlled instructions even if external tools are available.
Measure whether context reduces failure
Track CI failures, rejected pull requests, repeated setup errors, unnecessary file exploration and time to first successful test before and after context improvements.
Good context should reduce wrong assumptions and command failures.
More instruction tokens are not automatically better.
Context crafting succeeds when the repository teaches the agent how to work safely
The mature codebase uses concise repo-wide instructions, targeted path instructions, AGENTS.md where useful, prompt files for recurring tasks, curated Spaces, and MCP only for external capabilities.
The goal is to give Copilot the smallest reliable context that lets it build, test and validate changes correctly without rediscovering the project from scratch every session.
Instructions should explain architecture decisions, not restate obvious syntax. Telling Copilot that the repository uses TypeScript is less valuable than explaining which package owns domain logic, where migrations live, which test command is authoritative, and which generated directories must never be edited manually.
Repository-wide instructions should be short enough to remain high-signal. If the file becomes a hundred-page handbook, the agent must sift through the same irrelevant detail on every task. Link or point to deeper documents and tell Copilot when to consult them rather than copying everything into always-on context.
Path-specific instructions are particularly useful in monorepos. A database directory can specify migration rules, a frontend tree can specify design/test conventions, and infrastructure directories can prohibit direct production edits. This keeps local rules close to the code they affect.
AGENTS.md hierarchy should be tested so the nearest instruction file really produces the intended behavior. Nested services can inherit and override guidance; conflicting files create unpredictable agent choices. Keep one clear precedence model and avoid duplicating the same rule in several places.
Prompt files should be treated like reusable automation assets. Add variables/placeholders, examples and explicit completion criteria. A good prompt file can standardize security review or refactoring across the team without forcing those task-specific instructions into every ordinary chat.
Copilot Spaces can hold cross-repository design docs, plans and references, but curation has a lifecycle. Assign owners, remove obsolete documents and prefer authoritative source links. A Space full of stale ADRs can confidently steer the agent toward architecture the team already abandoned.
MCP servers should expose only the tools/data needed for the task. A broad MCP integration with write access to issue tracking, cloud resources or databases can create unnecessary risk. Keep read and write tools separate where possible and require approval for consequential actions.
Context should include validation commands with expected outcomes. Tell Copilot not only `npm test`, but whether integration tests require Docker, which command targets one package, how long the suite takes, and what known warnings are acceptable. This reduces false ‘done’ states where the agent ran an irrelevant subset.
Measure instruction effectiveness through pull-request outcomes. Count failed CI, reviewer corrections, wrong-file edits, setup-command failures and agent exploration time. Use those failures to improve the instructions instead of adding generic prose after every bad result.
Context crafting should remain vendor-agnostic where possible. Build scripts, architecture decisions and test rules are repository facts that can help Copilot, Claude Code or another coding agent. Store durable project truth in ordinary Markdown/configuration rather than burying it only inside one tool’s settings UI.
Context files should explain non-obvious repository boundaries such as generated code, vendored code, migrations, public APIs and backward-compatibility contracts. This prevents an agent from ‘fixing’ generated output or making a breaking change in an interface that looks internal from one file alone.
Examples are useful when rules are abstract. One short correct command sequence or a small example of the preferred testing pattern can teach Copilot more than several paragraphs of policy language. Keep examples current and remove obsolete workarounds after the underlying tooling is fixed.
Custom instructions should state when the agent must stop and ask or escalate. Examples include destructive database migrations, security-policy changes, missing secrets or ambiguous product requirements. Good context is not only about doing more autonomously; it also defines the boundaries of safe autonomy.
Organization-wide instructions should contain genuinely universal standards, while repository instructions should remain project-specific. Duplicating the same rule at personal, org and repository levels makes conflicts harder to diagnose and wastes context. Use the narrowest scope that matches the rule.
Context-maintenance ownership should be assigned. A repository can have excellent custom instructions at launch and stale ones six months later after a build-system migration. Add instruction files to architecture/build change checklists so the agent guidance evolves with the codebase.
Repository context should point to tests that encode behavior, not only prose docs. Copilot can infer important invariants from existing test suites when the instructions tell it which tests are authoritative. This is especially useful when documentation and code have diverged.
Use Claude Code for Large Repositories as a cross-agent comparison point: large codebases benefit from curated project maps, known commands and scoped exploration regardless of which coding agent is used. The durable asset is the repository knowledge, not one vendor-specific prompt.
Instruction files should identify files that must not be edited, such as generated lockfiles, vendor code, production secrets or migration history. Negative boundaries often prevent more failures than long style guidance because an agent otherwise treats every writable file as fair game.
Pull-request review should inspect instruction changes with the same care as code. A malicious or accidental instruction can direct future coding agents to skip tests or expose data. Code owners for build/security areas can review changes to `.github/copilot-instructions.md`, `AGENTS.md`, and related context files.
Context effectiveness should be revisited after major repository reorganizations. Moving directories can break path-specific `applyTo` patterns or change which AGENTS.md file is nearest. Add a small validation task after structural changes to confirm Copilot still receives the intended guidance.
Repository context should be treated as maintained product documentation. Instructions, examples, architectural notes, and generated metadata need owners and review dates so Copilot receives current constraints rather than confidently following conventions the codebase abandoned months earlier.
