microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/customization/instructions.md
193lines · modecode
| 1 | --- |
| 2 | title: Customizing with Instructions |
| 3 | description: Configure Copilot behavior using copilot-instructions.md and instruction files with applyTo targeting and stacking patterns |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-24 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - instructions |
| 9 | - copilot-instructions |
| 10 | - applyTo |
| 11 | - customization |
| 12 | estimated_reading_time: 8 |
| 13 | --- |
| 14 | |
| 15 | ## The Foundation: copilot-instructions.md |
| 16 | |
| 17 | The single most impactful customization point is `.github/copilot-instructions.md`. Copilot loads this file for every interaction in your repository, making it the global baseline for AI behavior. Every agent, prompt, and instruction file builds on top of whatever you define here. |
| 18 | |
| 19 | The file sits at the top of the artifact hierarchy. When Copilot processes a request, it merges guidance from four tiers: |
| 20 | |
| 21 | 1. **User settings** (VS Code profile) |
| 22 | 2. **Prompt or agent** invoked for the current task |
| 23 | 3. **Instruction files** matched by `applyTo` patterns |
| 24 | 4. **`copilot-instructions.md`** (always loaded) |
| 25 | |
| 26 | A minimal starter file establishes coding conventions and project context: |
| 27 | |
| 28 | ```markdown |
| 29 | # General Instructions |
| 30 | |
| 31 | * Use TypeScript for all new source files. |
| 32 | * Follow the existing module structure under `src/`. |
| 33 | * Prefer named exports over default exports. |
| 34 | ``` |
| 35 | |
| 36 | A more developed file adds priority rules, project structure guidance, and operational constraints: |
| 37 | |
| 38 | ```markdown |
| 39 | # General Instructions |
| 40 | |
| 41 | ## Priority Rules |
| 42 | |
| 43 | * Conventions and styling from the codebase take precedence for all changes. |
| 44 | * Breaking changes are acceptable. |
| 45 | * Tests are created or modified only when explicitly requested. |
| 46 | |
| 47 | ## Project Structure |
| 48 | |
| 49 | This repository contains a Node.js API with the following layout: |
| 50 | |
| 51 | * `src/routes/` for HTTP route handlers |
| 52 | * `src/services/` for business logic |
| 53 | * `src/models/` for data models and schemas |
| 54 | |
| 55 | ## Coding Conventions |
| 56 | |
| 57 | * Use `async`/`await` instead of raw promises. |
| 58 | * Variable names use camelCase; constants use UPPER_SNAKE_CASE. |
| 59 | * All public functions include JSDoc comments. |
| 60 | ``` |
| 61 | |
| 62 | > [!TIP] |
| 63 | > Start small. A few targeted rules produce better results than a sprawling document. Add guidance incrementally as you observe Copilot behavior in your codebase. |
| 64 | |
| 65 | ## Instruction Files |
| 66 | |
| 67 | Instruction files (`.instructions.md`) live in `.github/instructions/` and provide scoped guidance for specific file types, languages, or workflows. Unlike `copilot-instructions.md`, each instruction file declares which files it applies to through `applyTo` glob patterns. |
| 68 | |
| 69 | Organization follows a collection subdirectory convention: |
| 70 | |
| 71 | ```text |
| 72 | .github/instructions/ |
| 73 | ├── coding-standards/ |
| 74 | │ ├── python-script.instructions.md |
| 75 | │ └── typescript.instructions.md |
| 76 | ├── hve-core/ |
| 77 | │ ├── markdown.instructions.md |
| 78 | │ └── writing-style.instructions.md |
| 79 | └── shared/ |
| 80 | └── cross-collection.instructions.md |
| 81 | ``` |
| 82 | |
| 83 | Every instruction file requires YAML frontmatter with `description` and `applyTo` fields: |
| 84 | |
| 85 | ```yaml |
| 86 | --- |
| 87 | description: "Python coding conventions for data pipeline modules" |
| 88 | applyTo: '**/*.py' |
| 89 | --- |
| 90 | ``` |
| 91 | |
| 92 | The body contains the guidance Copilot follows when working with matched files: coding standards, naming conventions, framework-specific patterns, or operational constraints. |
| 93 | |
| 94 | ## Accelerating with Prompt Builder |
| 95 | |
| 96 | The Prompt Builder agent automates instruction file creation and evaluation. Use its commands to generate well-structured instruction files that follow repository conventions. |
| 97 | |
| 98 | Create a new instruction file or improve an existing one with `/prompt-build`: |
| 99 | |
| 100 | ```text |
| 101 | /prompt-build files=.github/instructions/coding-standards/typescript.instructions.md promptFiles=.github/instructions/coding-standards/python-script.instructions.md |
| 102 | ``` |
| 103 | |
| 104 | Provide `files` for reference context (existing instruction files to use as style templates, `copilot-instructions.md` for project conventions) and `promptFiles` for the instruction files to create or update. |
| 105 | |
| 106 | Evaluate an instruction file's quality with `/prompt-analyze`: |
| 107 | |
| 108 | ```text |
| 109 | /prompt-analyze promptFiles=.github/instructions/coding-standards/python-script.instructions.md |
| 110 | ``` |
| 111 | |
| 112 | The report identifies issues with structure, clarity, and consistency. Use it to validate `applyTo` patterns, frontmatter completeness, and instruction coherence before merging. |
| 113 | |
| 114 | Refactor related instruction files with `/prompt-refactor`: |
| 115 | |
| 116 | ```text |
| 117 | /prompt-refactor promptFiles=.github/instructions/coding-standards/*.instructions.md requirements="eliminate overlapping rules and consolidate shared patterns" |
| 118 | ``` |
| 119 | |
| 120 | > [!TIP] |
| 121 | > When creating instruction files, include existing instruction files in the `files` parameter. Prompt Builder uses them as style references and avoids generating rules that conflict with existing guidance. |
| 122 | |
| 123 | ## Targeting with applyTo |
| 124 | |
| 125 | The `applyTo` field uses glob patterns to determine when an instruction file activates. Copilot evaluates the pattern against the file you are editing or referencing in conversation. |
| 126 | |
| 127 | Common patterns: |
| 128 | |
| 129 | | Pattern | Matches | |
| 130 | |-------------------|-----------------------------------------| |
| 131 | | `'**/*.py'` | All Python files in the repository | |
| 132 | | `'**/*.md'` | All Markdown files | |
| 133 | | `'**/*.test.ts'` | TypeScript test files only | |
| 134 | | `'**/src/**'` | Everything under any `src/` directory | |
| 135 | | `'**'` | All files (global scope) | |
| 136 | | `'**/*.yml'` | All YAML files | |
| 137 | | `'**/Dockerfile'` | All Dockerfiles regardless of directory | |
| 138 | |
| 139 | Combine multiple patterns with commas for broader matching: |
| 140 | |
| 141 | ```yaml |
| 142 | applyTo: '**/*.py, **/*.ipynb' |
| 143 | ``` |
| 144 | |
| 145 | Narrow patterns produce more relevant guidance. Prefer `'**/*.test.ts'` over `'**/*.ts'` when the instructions apply only to tests. |
| 146 | |
| 147 | ## Instruction Stacking |
| 148 | |
| 149 | When you edit a file that matches multiple instruction files, Copilot loads all matching files and merges their guidance. The stacking order follows specificity: |
| 150 | |
| 151 | 1. **`copilot-instructions.md`** loads first as the global baseline. |
| 152 | 2. **Broad `applyTo` patterns** (like `'**'`) load next. |
| 153 | 3. **Specific `applyTo` patterns** (like `'**/*.test.py'`) layer on top. |
| 154 | |
| 155 | When instructions conflict, the more specific file takes precedence. For example, if a global instruction says "use tabs" but a Python-specific instruction says "use 4-space indentation," the Python rule wins when editing `.py` files. |
| 156 | |
| 157 | Practical stacking example: |
| 158 | |
| 159 | * `markdown.instructions.md` (`applyTo: '**/*.md'`) sets heading and list style rules |
| 160 | * `writing-style.instructions.md` (`applyTo: '**/*.md'`) adds voice and tone conventions |
| 161 | * Both activate when you edit any Markdown file, and their guidance combines |
| 162 | |
| 163 | > [!NOTE] |
| 164 | > Instruction stacking is additive. Avoid placing contradictory rules in files with overlapping `applyTo` patterns. When overlap is unavoidable, the more specific pattern prevails. |
| 165 | |
| 166 | ## Role Scenarios |
| 167 | |
| 168 | **Fabrikam's Tech Lead** ensures consistent test coverage across the team. She creates `.github/instructions/coding-standards/test-coverage.instructions.md` with `applyTo: '**/*.test.ts'` and includes rules for minimum assertion counts, mock isolation patterns, and snapshot testing conventions. Every engineer on the team gets these standards applied automatically when writing tests. |
| 169 | |
| 170 | **Contoso's Security Architect** enforces input validation requirements. He adds `.github/instructions/coding-standards/input-validation.instructions.md` with `applyTo: '**/*.py'` targeting the API layer. The file specifies schema validation requirements for all request handlers, parameterized query patterns, and logging conventions for rejected input. |
| 171 | |
| 172 | **Northwind Traders' Data Scientist** standardizes notebook conventions. She creates `.github/instructions/coding-standards/notebook-conventions.instructions.md` with `applyTo: '**/*.ipynb'` requiring cell documentation, reproducibility headers, and data source annotations in every notebook. |
| 173 | |
| 174 | **Adventure Works' SRE** establishes infrastructure-as-code standards. He authors `.github/instructions/coding-standards/terraform.instructions.md` with `applyTo: '**/*.tf'` enforcing module structure, naming conventions, and state backend patterns for all Terraform configurations. |
| 175 | |
| 176 | ## Common Patterns |
| 177 | |
| 178 | | Customization Goal | Instruction File Approach | |
| 179 | |--------------------------------|-------------------------------------------------------------------------| |
| 180 | | Enforce a language style guide | Create `{language}.instructions.md` with `applyTo: '**/*.{ext}'` | |
| 181 | | Standardize commit messages | Create `commit-message.instructions.md` with `applyTo: '**'` | |
| 182 | | Apply framework conventions | Create `{framework}.instructions.md` targeting framework file patterns | |
| 183 | | Set documentation standards | Create `writing-style.instructions.md` with `applyTo: '**/*.md'` | |
| 184 | | Enforce test patterns | Create `test-conventions.instructions.md` with `applyTo: '**/*.test.*'` | |
| 185 | | Add project-specific context | Add a `## Project Structure` section to `copilot-instructions.md` | |
| 186 | | Scope rules to a subdirectory | Use a path-specific glob like `applyTo: '**/src/api/**'` | |
| 187 | |
| 188 | For full frontmatter schema, field definitions, and validation rules, see [Contributing: Instructions](../contributing/instructions.md). |
| 189 | |
| 190 | <!-- markdownlint-disable MD036 --> |
| 191 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 192 | then carefully refined by our team of discerning human reviewers.* |
| 193 | <!-- markdownlint-enable MD036 --> |
| 194 | |