|
| 1 | +--- |
| 2 | +description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot' |
| 3 | +applyTo: '**/*.instructions.md' |
| 4 | +--- |
| 5 | + |
| 6 | +# Custom Instructions File Guidelines |
| 7 | + |
| 8 | +Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions. |
| 9 | + |
| 10 | +## Project Context |
| 11 | + |
| 12 | +- Target audience: Developers and GitHub Copilot working with domain-specific code |
| 13 | +- File format: Markdown with YAML frontmatter |
| 14 | +- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`) |
| 15 | +- Location: `.github/instructions/` directory |
| 16 | +- Purpose: Provide context-aware guidance for code generation, review, and documentation |
| 17 | + |
| 18 | +## Required Frontmatter |
| 19 | + |
| 20 | +Every instruction file must include YAML frontmatter with the following fields: |
| 21 | + |
| 22 | +```yaml |
| 23 | +--- |
| 24 | +description: 'Brief description of the instruction purpose and scope' |
| 25 | +applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)' |
| 26 | +--- |
| 27 | +``` |
| 28 | + |
| 29 | +### Frontmatter Guidelines |
| 30 | + |
| 31 | +- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose |
| 32 | +- **applyTo**: Glob pattern(s) specifying which files these instructions apply to |
| 33 | + - Single pattern: `'**/*.ts'` |
| 34 | + - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'` |
| 35 | + - Specific files: `'src/**/*.py'` |
| 36 | + - All files: `'**'` |
| 37 | + |
| 38 | +## File Structure |
| 39 | + |
| 40 | +A well-structured instruction file should include the following sections: |
| 41 | + |
| 42 | +### 1. Title and Overview |
| 43 | + |
| 44 | +- Clear, descriptive title using `#` heading |
| 45 | +- Brief introduction explaining the purpose and scope |
| 46 | +- Optional: Project context section with key technologies and versions |
| 47 | + |
| 48 | +### 2. Core Sections |
| 49 | + |
| 50 | +Organize content into logical sections based on the domain: |
| 51 | + |
| 52 | +- **General Instructions**: High-level guidelines and principles |
| 53 | +- **Best Practices**: Recommended patterns and approaches |
| 54 | +- **Code Standards**: Naming conventions, formatting, style rules |
| 55 | +- **Architecture/Structure**: Project organization and design patterns |
| 56 | +- **Common Patterns**: Frequently used implementations |
| 57 | +- **Security**: Security considerations (if applicable) |
| 58 | +- **Performance**: Optimization guidelines (if applicable) |
| 59 | +- **Testing**: Testing standards and approaches (if applicable) |
| 60 | + |
| 61 | +### 3. Examples and Code Snippets |
| 62 | + |
| 63 | +Provide concrete examples with clear labels: |
| 64 | + |
| 65 | +```markdown |
| 66 | +### Good Example |
| 67 | +\`\`\`language |
| 68 | +// Recommended approach |
| 69 | +code example here |
| 70 | +\`\`\` |
| 71 | + |
| 72 | +### Bad Example |
| 73 | +\`\`\`language |
| 74 | +// Avoid this pattern |
| 75 | +code example here |
| 76 | +\`\`\` |
| 77 | +``` |
| 78 | + |
| 79 | +### 4. Validation and Verification (Optional but Recommended) |
| 80 | + |
| 81 | +- Build commands to verify code |
| 82 | +- Linting and formatting tools |
| 83 | +- Testing requirements |
| 84 | +- Verification steps |
| 85 | + |
| 86 | +## Content Guidelines |
| 87 | + |
| 88 | +### Writing Style |
| 89 | + |
| 90 | +- Use clear, concise language |
| 91 | +- Write in imperative mood ("Use", "Implement", "Avoid") |
| 92 | +- Be specific and actionable |
| 93 | +- Avoid ambiguous terms like "should", "might", "possibly" |
| 94 | +- Use bullet points and lists for readability |
| 95 | +- Keep sections focused and scannable |
| 96 | + |
| 97 | +### Best Practices |
| 98 | + |
| 99 | +- **Be Specific**: Provide concrete examples rather than abstract concepts |
| 100 | +- **Show Why**: Explain the reasoning behind recommendations when it adds value |
| 101 | +- **Use Tables**: For comparing options, listing rules, or showing patterns |
| 102 | +- **Include Examples**: Real code snippets are more effective than descriptions |
| 103 | +- **Stay Current**: Reference current versions and best practices |
| 104 | +- **Link Resources**: Include official documentation and authoritative sources |
| 105 | + |
| 106 | +### Common Patterns to Include |
| 107 | + |
| 108 | +1. **Naming Conventions**: How to name variables, functions, classes, files |
| 109 | +2. **Code Organization**: File structure, module organization, import order |
| 110 | +3. **Error Handling**: Preferred error handling patterns |
| 111 | +4. **Dependencies**: How to manage and document dependencies |
| 112 | +5. **Comments and Documentation**: When and how to document code |
| 113 | +6. **Version Information**: Target language/framework versions |
| 114 | + |
| 115 | +## Patterns to Follow |
| 116 | + |
| 117 | +### Bullet Points and Lists |
| 118 | + |
| 119 | +```markdown |
| 120 | +## Security Best Practices |
| 121 | + |
| 122 | +- Always validate user input before processing |
| 123 | +- Use parameterized queries to prevent SQL injection |
| 124 | +- Store secrets in environment variables, never in code |
| 125 | +- Implement proper authentication and authorization |
| 126 | +- Enable HTTPS for all production endpoints |
| 127 | +``` |
| 128 | + |
| 129 | +### Tables for Structured Information |
| 130 | + |
| 131 | +```markdown |
| 132 | +## Common Issues |
| 133 | + |
| 134 | +| Issue | Solution | Example | |
| 135 | +| ---------------- | ------------------- | ----------------------------- | |
| 136 | +| Magic numbers | Use named constants | `const MAX_RETRIES = 3` | |
| 137 | +| Deep nesting | Extract functions | Refactor nested if statements | |
| 138 | +| Hardcoded values | Use configuration | Store API URLs in config | |
| 139 | +``` |
| 140 | + |
| 141 | +### Code Comparison |
| 142 | + |
| 143 | +```markdown |
| 144 | +### Good Example - Using TypeScript interfaces |
| 145 | +\`\`\`typescript |
| 146 | +interface User { |
| 147 | + id: string; |
| 148 | + name: string; |
| 149 | + email: string; |
| 150 | +} |
| 151 | + |
| 152 | +function getUser(id: string): User { |
| 153 | + // Implementation |
| 154 | +} |
| 155 | +\`\`\` |
| 156 | + |
| 157 | +### Bad Example - Using any type |
| 158 | +\`\`\`typescript |
| 159 | +function getUser(id: any): any { |
| 160 | + // Loses type safety |
| 161 | +} |
| 162 | +\`\`\` |
| 163 | +``` |
| 164 | + |
| 165 | +### Conditional Guidance |
| 166 | + |
| 167 | +```markdown |
| 168 | +## Framework Selection |
| 169 | + |
| 170 | +- **For small projects**: Use Minimal API approach |
| 171 | +- **For large projects**: Use controller-based architecture with clear separation |
| 172 | +- **For microservices**: Consider domain-driven design patterns |
| 173 | +``` |
| 174 | + |
| 175 | +## Patterns to Avoid |
| 176 | + |
| 177 | +- **Overly verbose explanations**: Keep it concise and scannable |
| 178 | +- **Outdated information**: Always reference current versions and practices |
| 179 | +- **Ambiguous guidelines**: Be specific about what to do or avoid |
| 180 | +- **Missing examples**: Abstract rules without concrete code examples |
| 181 | +- **Contradictory advice**: Ensure consistency throughout the file |
| 182 | +- **Copy-paste from documentation**: Add value by distilling and contextualizing |
| 183 | + |
| 184 | +## Testing Your Instructions |
| 185 | + |
| 186 | +Before finalizing instruction files: |
| 187 | + |
| 188 | +1. **Test with Copilot**: Try the instructions with actual prompts in VS Code |
| 189 | +2. **Verify Examples**: Ensure code examples are correct and run without errors |
| 190 | +3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files |
| 191 | + |
| 192 | +## Example Structure |
| 193 | + |
| 194 | +Here's a minimal example structure for a new instruction file: |
| 195 | + |
| 196 | +```markdown |
| 197 | +--- |
| 198 | +description: 'Brief description of purpose' |
| 199 | +applyTo: '**/*.ext' |
| 200 | +--- |
| 201 | + |
| 202 | +# Technology Name Development |
| 203 | + |
| 204 | +Brief introduction and context. |
| 205 | + |
| 206 | +## General Instructions |
| 207 | + |
| 208 | +- High-level guideline 1 |
| 209 | +- High-level guideline 2 |
| 210 | + |
| 211 | +## Best Practices |
| 212 | + |
| 213 | +- Specific practice 1 |
| 214 | +- Specific practice 2 |
| 215 | + |
| 216 | +## Code Standards |
| 217 | + |
| 218 | +### Naming Conventions |
| 219 | +- Rule 1 |
| 220 | +- Rule 2 |
| 221 | + |
| 222 | +### File Organization |
| 223 | +- Structure 1 |
| 224 | +- Structure 2 |
| 225 | + |
| 226 | +## Common Patterns |
| 227 | + |
| 228 | +### Pattern 1 |
| 229 | +Description and example |
| 230 | + |
| 231 | +\`\`\`language |
| 232 | +code example |
| 233 | +\`\`\` |
| 234 | + |
| 235 | +### Pattern 2 |
| 236 | +Description and example |
| 237 | + |
| 238 | +## Validation |
| 239 | + |
| 240 | +- Build command: `command to verify` |
| 241 | +- Linting: `command to lint` |
| 242 | +- Testing: `command to test` |
| 243 | +``` |
| 244 | + |
| 245 | +## Maintenance |
| 246 | + |
| 247 | +- Review instructions when dependencies or frameworks are updated |
| 248 | +- Update examples to reflect current best practices |
| 249 | +- Remove outdated patterns or deprecated features |
| 250 | +- Add new patterns as they emerge in the community |
| 251 | +- Keep glob patterns accurate as project structure evolves |
| 252 | + |
| 253 | +## Additional Resources |
| 254 | + |
| 255 | +- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) |
| 256 | +- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions) |
0 commit comments