---
title: "Context engineering principles for GitHub Copilot"
description: "Consolidated best practices for crafting effective instructions, prompts, and agent personas — single source of truth for context engineering principles across all file types"
version: "2.2.0"
last_updated: "2026-03-19"
domain: "prompt-engineering"
authoritative_sources:
  - url: "https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview"
    description: "Anthropic prompt engineering best practices — clear instructions, context, structured output"
  - url: "https://platform.openai.com/docs/guides/prompt-engineering"
    description: "OpenAI prompt engineering guide — tactics for better results"
  - url: "https://code.visualstudio.com/docs/copilot/copilot-customization"
    description: "VS Code Copilot customization — custom instructions and prompt files"
---

# Context Engineering Principles for GitHub Copilot

**Purpose**: Consolidated best practices for crafting effective instructions, prompts, and agent personas for GitHub Copilot. This document serves as the single source of truth for context engineering principles across all file types.

**Referenced by**: `.github/instructions/prompts.instructions.md`, `.github/instructions/agents.instructions.md`, all prompt and agent files

---

## Core Principles

### 1. Narrow Scope, Specific Purpose

**Principle**: Each prompt, agent, or instruction file MUST have a single, well-defined responsibility. One primary user goal per file. Related sub-tasks OK if they serve the primary goal. Use handoffs for sequential workflows.

### 2. Early Commands, Clear Structure

**Principle**: Place the most important instructions and commands at the beginning of your content.

**Why it matters**: AI models give more weight to earlier content. Critical constraints must be established before detailed instructions.

**Priority order**: Core objective → Critical constraints (NEVER/ALWAYS) → Workflow/process → Tool config → Handoffs → Examples → Checklists → Background context.

**YAML Frontmatter**: Always place `description`, `tools`, and `agent` in YAML frontmatter — not buried in Markdown body.

### 3. Imperative Language

**Principle**: Use direct, commanding language that leaves no room for interpretation.

**Why it matters**:
- Reduces probabilistic behavior in AI responses
- Creates enforceable boundaries
- Establishes clear expectations

**Command Hierarchy**:

| Strength | Phrase | Use Case | Example |
|----------|--------|----------|---------|
| **Absolute** | `NEVER`, `MUST NOT` | Hard boundaries, safety rules | "NEVER modify files outside .github/prompts/" |
| **Required** | `MUST`, `ALWAYS`, `WILL` | Core requirements | "You MUST validate YAML syntax before saving" |
| **Expected** | `SHOULD`, `PREFER` | Best practices, soft preferences | "You SHOULD use handoffs for multi-step workflows" |
| **Optional** | `CAN`, `MAY`, `CONSIDER` | Suggestions, alternatives | "You MAY ask for clarification if requirements are vague" |

**Examples**:

❌ **Weak** (probabilistic):
```markdown
It would be helpful if you could check for syntax errors.
Try to keep the file under 200 lines.
Consider using semantic search to find similar patterns.
```

✅ **Strong** (imperative):
```markdown
You MUST validate YAML syntax before saving any changes.
You WILL keep the file under 200 lines; factor into multiple files if needed.
You MUST use semantic_search to analyze at least 3 similar prompts before building.
```

### 4. Three-Tier Boundary System

**Principle**: Every agent MUST define three tiers: Always Do (no approval), Ask First (requires approval), Never Do (hard refusal). Minimum items: ≥3/≥1/≥2.

**📖 Boundary minimums:** [01.06-system-parameters.md](01.06-system-parameters.md) → Agent Boundaries

### 5. Context Minimization

**Principle**: Include only the context necessary for the specific task; reference external sources for additional details.

**Why it matters**: Reduces token usage, improves AI focus, enables single source of truth, enables better composition.

**Key techniques**:
- **Reference, don't duplicate**: Link to context files instead of embedding 100+ lines inline
- **Prefer group references**: Use folder-level refs (`📖 .copilot/context/00.00-prompt-engineering/`) over individual file refs — files can evolve without breaking references
- **Use individual refs only** when linking to a specific section/concept or cross-referencing within a folder
- **Selective reads**: Use `semantic_search` to find relevant files, not "read all files before starting"
- **Lazy loading**: Gather requirements first (Phase 1), then search/read only what's needed (Phase 2)

1. **Gather Requirements** - Minimal context, user interaction only
2. **Research Phase** - NOW use semantic_search, read_file, grep_search
3. **Build Phase** - Access templates and examples
4. **Validate Phase** - Load validation rules and checklists


### 6. Tool Scoping and Security

**Principle**: Grant only the minimum tools necessary for the agent's role; use `agent: plan` for read-only operations.

**Why it matters**:
- Prevents accidental file modifications
- Reduces risk of cascading errors
- Makes agent behavior more predictable
- Aligns with principle of least privilege

**📖 Complete tool reference:** [01.04-tool-composition-guide.md](01.04-tool-composition-guide.md) — tool categories, costs, composition patterns, role-based selection

**Key rules:**
- `agent: plan` + read-only tools ONLY (read_file, grep_search, semantic_search, file_search, list_dir, get_errors)
- `agent: agent` + read + write tools (create_file, replace_string_in_file, multi_replace_string_in_file)
- **NEVER** mix `agent: plan` with write tools — this is a CRITICAL validation failure
- Limit agents to 3–7 tools; >7 causes tool clash
- Always-available tools (manage_todo_list, ask_questions, runSubagent, tool_search_tool_regex) MUST NOT be listed in `tools:` frontmatter

---

### 7. Explicit Uncertainty Management

**Principle**: Define professional "I don't know" responses and data gap handling patterns that prevent hallucination.

**Three-part template**: "I couldn't find [X] in [Y]. I did find [Z]. Recommendation: [escalation]."

**📖 Production-readiness patterns**: [04.03-production-readiness-patterns.md](04.03-production-readiness-patterns.md)

---

### 8. Template-First Authoring (Token Efficiency)

**Principle**: Any inline content block exceeding 10 lines MUST be externalized to a template file in `.github/templates/`.

**Why it matters**: Token efficiency (load only when needed), consistency (single source), maintainability.

**Naming pattern**: `output-{purpose}.template.md`, `guidance-{purpose}.template.md`

**When to keep inline**: < 10 lines, unique to the prompt, or requires heavy dynamic interpolation.

**Existing templates**: See `.github/templates/` (26+ reusable templates available)

---

## Application by File Type

Each file type applies these principles with different priorities. See the relevant instruction file for type-specific rules:

**📖** [prompts.instructions.md](../../.github/instructions/prompts.instructions.md) | [agents.instructions.md](../../.github/instructions/agents.instructions.md) | [context-files.instructions.md](../../.github/instructions/context-files.instructions.md) | [skills.instructions.md](../../.github/instructions/skills.instructions.md)

**📖 Token budgets per file type:** [01.06-system-parameters.md](01.06-system-parameters.md)

---

## Common Anti-Patterns

| Anti-Pattern | Fix |
|-------------|-----|
| **Vague/Weak Language** | Use imperative: MUST, WILL, NEVER — never "try to" or "consider" |
| **Scope Creep** (4+ responsibilities) | Split into specialized agents with handoffs |
| **Embedded Documentation** (100+ lines inline) | Reference context files instead |
| **Late Critical Info** | Place constraints at top (YAML + first 20%) |

---

## Rule Precedence Across Layers

When the same rule appears at multiple artifact layers with different strengths, the **higher-authority layer wins**. Lower layers may specialize (narrow scope) but MUST NOT weaken (relax constraints).

| Priority | Layer | Authority |
|---|---|---|
| 1 (highest) | **Governance baseline** (`00.01`) | Absolute — never overridden |
| 2 | **Context files** (`.copilot/context/`) | Canonical rules — single source of truth |
| 3 | **Instruction files** (`.github/instructions/`) | Enforcement — applies rules to file-type scope |
| 4 | **Agent/Skill files** | Specialization — may narrow scope; MUST NOT weaken layers 1–3 |
| 5 (lowest) | **Prompt files** | Per-execution override; overrides don't persist |

**Conflict resolution**: Higher layer wins. Lower layers may narrow ("3–5 tools" within "3–7") but MUST NOT relax ("SHOULD" when context says "MUST"). Agent contradicts governance = CRITICAL violation.

**📖 Rule enforcement by severity:** [01.07-critical-rules-priority-matrix.md](01.07-critical-rules-priority-matrix.md)

---

## Validation Checklist

When creating or reviewing prompts, agents, or instructions, verify:
- [ ] Single responsibility; purpose in first sentence/YAML
- [ ] YAML frontmatter has critical config; important instructions in first 20%
- [ ] Imperative verbs (MUST/WILL/NEVER); no weak phrases
- [ ] Three-tier boundaries defined; file access scope clear
- [ ] References context files (no embedded content); lazy loading
- [ ] Tool list matches role; `agent: plan` for read-only agents

---

## Version History

| Version | Date | Changes |
|---------|------|--------|
| 1.0.0 | 2025-12-10 | Initial consolidated version |
| 1.3.0 | 2026-03-11 | Added Rule Precedence Across Layers |
| 2.1.0 | 2026-03-19 | Compressed: removed duplicates, embedded examples, token budget section; streamlined all principles |

---

## References

- **External**: [VS Code Copilot Customization](https://code.visualstudio.com/docs/copilot/copilot-customization)
- **Internal**: [01.02-prompt-assembly-architecture.md](./01.02-prompt-assembly-architecture.md), [01.04-tool-composition-guide.md](./01.04-tool-composition-guide.md), [02.01-handoffs-pattern.md](./02.01-handoffs-pattern.md), [04.01-validation-caching-pattern.md](./04.01-validation-caching-pattern.md)
- **Source articles**: `03.00-tech/05.02-prompt-engineering/04-howto/03.00-*` (prompt structure), `04.00-*` (agent structure)