Instructions

# Custom Instructions File Guidelines

Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.

Project Context

- Target audience: Developers and GitHub Copilot working with domain-specific code

- File format: Markdown with YAML frontmatter

- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)

- Location: `.github/instructions/` directory

- Purpose: Provide context-aware guidance for code generation, review, and documentation

Required Frontmatter

Every instruction file must include YAML frontmatter with the following fields:

---
description: 'Brief description of the instruction purpose and scope'
applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
---

Frontmatter Guidelines

- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose

- **applyTo**: Glob pattern(s) specifying which files these instructions apply to

- Single pattern: `'**/*.ts'`

- Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`

- Specific files: `'src/**/*.py'`

- All files: `'**'`

File Structure

A well-structured instruction file should include the following sections:

1. Title and Overview

- Clear, descriptive title using `#` heading

- Brief introduction explaining the purpose and scope

- Optional: Project context section with key technologies and versions

2. Core Sections

Organize content into logical sections based on the domain:

- **General Instructions**: High-level guidelines and principles

- **Best Practices**: Recommended patterns and approaches

- **Code Standards**: Naming conventions, formatting, style rules

- **Architecture/Structure**: Project organization and design patterns

- **Common Patterns**: Frequently used implementations

- **Security**: Security considerations (if applicable)

- **Performance**: Optimization guidelines (if applicable)

- **Testing**: Testing standards and approaches (if applicable)

3. Examples and Code Snippets

Provide concrete examples with clear labels:

### Good Example
\`\`\`language
// Recommended approach
code example here
\`\`\`

### Bad Example
\`\`\`language
// Avoid this pattern
code example here
\`\`\`

4. Validation and Verification (Optional but Recommended)

- Build commands to verify code

- Linting and formatting tools

- Testing requirements

- Verification steps

Content Guidelines

Writing Style

- Use clear, concise language

- Write in imperative mood ("Use", "Implement", "Avoid")

- Be specific and actionable

- Avoid ambiguous terms like "should", "might", "possibly"

- Use bullet points and lists for readability

- Keep sections focused and scannable

Best Practices

- **Be Specific**: Provide concrete examples rather than abstract concepts

- **Show Why**: Explain the reasoning behind recommendations when it adds value

- **Use Tables**: For comparing options, listing rules, or showing patterns

- **Include Examples**: Real code snippets are more effective than descriptions

- **Stay Current**: Reference current versions and best practices

- **Link Resources**: Include official documentation and authoritative sources

Instruction Altitude (Goldilocks Zone)

- Start with the minimum rule set that fully defines expected outcomes

- Add constraints after observed failures, not hypothetical edge cases

- Prefer high-signal examples over exhaustive decision tables

| Altitude | Failure Mode | Result |

| --- | --- | --- |

| Over-specified | Brittle if-else prose | Breaks on unlisted cases |

| Under-specified | Assumes shared context | Generic outputs |

| Right altitude | Heuristics + examples | Stable, generalizable quality |

Common Patterns to Include

1. **Naming Conventions**: How to name variables, functions, classes, files

2. **Code Organization**: File structure, module organization, import order

3. **Error Handling**: