Config & Context Architecture for GitHub Copilot in VS CodeArquitetura de configuração e contexto para GitHub Copilot no VS CodeArquitectura de configuración y contexto para GitHub Copilot en VS Code

Most teams activate GitHub Copilot, write a single copilot-instructions.md, and consider the job done. In practice, that covers roughly 10% of the available configuration surface. The remaining 90% — scoped instructions, agents, chat modes, skills, prompt files, hooks, MCP connections, plugins, and VS Code settings — stays unconfigured, which means Copilot behavior remains tribal rather than auditable.

This piece maps all ten configuration layers, explains why a single-file approach breaks down at scale, and gives you the mental model to assign each rule to the right tier.

The empirical gap

Research on 2,303 real context files (Chatlatanagulchai et al., 2025, arXiv 2511.12884) shows a consistent pattern. Teams write what makes the agent functional — 62.3% of files cover build and run commands, 69.9% cover implementation details, 67.7% cover architecture. What they skip: security guardrails appear in only 14.5% of files; performance rules in another 14.5%. Error handling and degraded behavior are rare.

The result is an agent that generates productive code but not necessarily safe or predictable code. The problem is not the model. The problem is which rules were never codified anywhere.

A second data point reinforces the scaling argument. A documented project in C# with 108,000 lines built over 70 days and 283 sessions (Vasilopoulos, 2026, arXiv 2602.20478) found that single-file manifests collapse early. The project required a tiered approach — hot, warm, and cold memory — to maintain a knowledge-to-code ratio of 24.2% across a 14-package monorepo. A flat copilot-instructions.md growing past 3,000 tokens will be truncated by the model; everything after the cutoff drifts silently.

Ten layers, three tiers

Every Copilot response is assembled from a layered context window. The ten configuration surfaces map cleanly onto three tiers:

#	Surface	File location	When loaded
01	copilot-instructions.md	.github/copilot-instructions.md	Always
02	Scoped instructions	.github/instructions/*.instructions.md	Path match (applyTo glob)
03	Agents	.github/agents/*.agent.md	When invoked by name
04	Chat modes	.github/chatmodes/*	When selected
05	Skills	.github/skills/*/SKILL.md	Description match
06	Prompt files	.github/prompts/*.md	Slash command
07	Hooks	.github/hooks/*.json	On events
08	MCP connections	.mcp.json	Per session
09	Plugins	.plugin.json	When installed
10	VS Code settings	settings.json	Always

Hot tier (always loaded): Layers 01 and 02. These load on every request regardless of which file is open or which command is issued. Reserve hot tier for what is true on every line of code in the workspace — conventions, security policy, performance baselines. If a rule applies only to one task, it does not belong here.

Warm tier (invoked): Layers 03–06. These load when explicitly triggered — by name, selection, slash command, or description match. Agents handle whole classes of tasks (review, test, refactor). Chat modes switch persona and system prompt. Skills package reusable domain knowledge that auto-loads on description match. Prompt files encode known recipes behind slash commands like /release-notes or /pr-summary. The rule: if always needed, promote to hot. If bound to a specific task, keep it warm.

Cold tier (situational): Layers 07–10. Hooks, MCP connections, plugins, and VS Code settings configure the runtime environment around the agent. They do not carry prompt content. They control determinism, tool access, network reach, and model behavior. Set once, change rarely. The anti-pattern is editing cold-tier configuration per feature or per sprint.

Three architectural layers

The ten surfaces also map to three architectural responsibilities:

Workspace layer answers “what is always true.” The copilot-instructions.md at .github/ plus scoped instructions with applyTo globs are the team contract. They load on every request. Path-scoped subsets refine the global rules without overriding them — multiple matches merge, they do not replace each other. A file matching both react.instructions.md (applyTo: src/components/**/*.tsx) and the global workspace rules loads both simultaneously.

Authoring layer answers “what I invoke.” Agents, chat modes, skills, and prompts are reusable knowledge packaged as artifacts, bound to a task, not to a file. The selection rule is simple: pick by how it is triggered, not by what it contains. An agent is invoked by name for a class of tasks. A chat mode switches the persona for a conversation scope. A skill loads automatically on description match. A prompt file runs on slash command.

Runtime layer answers “what runs around the agent.” Hooks intercept every tool call — pre-tool-use, post-tool-use, on-error — to block, log, or rewrite. MCP connections extend the agent’s reach to external systems (GitHub, Postgres, observability platforms, internal APIs) through a single protocol, discovered dynamically at session start. Plugins bundle third-party capabilities. VS Code settings dial the model’s deterministic behavior. All four surfaces are owned by the platform team, not by feature work.

Assembly order for one request

When a user submits a prompt, Copilot assembles the context window in a deterministic nine-step sequence:

1. Steps 1–3 — Settings: default → user → workspace settings resolve in precedence order (most specific wins).
2. Step 4 — Hot memory: copilot-instructions.md loads unconditionally.
3. Step 5 — Scoped match: applyTo globs evaluate against open files; matching instruction sets merge.
4. Step 6 — Authoring primitive: the active agent, chat mode, skill, or prompt file attaches.
5. Step 7 — On-prompt-submit hooks: hooks evaluate and may deny, mutate, or annotate the request.
6. Step 8 — MCP discovery: connected servers expose their tool catalog.
7. Step 9 — Send to model: assembled system prompt + tool catalog + user message dispatches.

When Copilot ignores a rule, the bug is almost always in step 3 (wrong settings scope), step 5 (glob not matching the open file), or step 7 (a hook blocking or mutating the instruction). Walk the order top-down before concluding the model is at fault.

Inheritance and scope precedence

Settings precedence runs from least specific to most specific: Default (built into the product) → User (~/…/User/settings.json, never committed) → Workspace (.vscode/settings.json, committed to repo) → Folder ({folder}/.vscode/settings.json, overrides workspace for multi-root setups). The outer scope cannot override the inner. The inner cannot leak outward.

At the organizational level, GitHub Enterprise policy sets floors — content exclusion, telemetry, model lock — that cannot be overridden at workspace or user scope. The workspace contract flows down to every contributor. User settings never commit to the repo. Session context (pinned files, open tabs, conversation history) is the innermost and most ephemeral layer.

The operational principle: enforce at the outer scope, do not police per-user. Lock policy at the organization or workspace level and let inner scopes add ergonomic preferences without undermining the contract.

What to do Monday morning

Three symptoms indicate an underused configuration surface:

• Duplicate instructions: the same rule lives in three files and Copilot follows the wrong one depending on which file is open.
• Silent drift: the model generates useful code that does not follow team conventions, because those conventions exist only in someone’s head.
• Tribal knowledge: a strong prompt for creating API endpoints exists, but only one person on the team knows it.

The fix is structural, not conversational. Map each rule to the correct tier: what is always true goes into the workspace layer (hot), what is task-specific goes into the authoring layer (warm), and what configures the runtime environment goes into the cold tier. Scoped instructions replace the monolithic copilot-instructions.md for stack-specific rules. Skills and prompt files make reusable knowledge addressable by anyone on the team.

The goal is not more configuration — it is configuration that is auditable, versioned, and unambiguous about who owns each layer.