Ria Gopu delivers a detailed guide to creating and optimizing instructions files for GitHub Copilot code review, complete with structure templates, practical tips, and prompts for developers.

Mastering Copilot Code Review: Writing Effective Instructions Files

Author: Ria Gopu

GitHub Copilot code review (CCR) can automate and enhance your code review workflows, helping your team consistently meet software standards. Getting the most out of Copilot code review depends heavily on your ability to provide clear, actionable, and well-structured instructions. This guide provides practical advice, examples, and best practices for crafting instructions files that align Copilot’s automation with your team’s needs.

Why Custom Copilot Instructions Matter

  • Copilot code review reads instructions files to determine how to assess your repositories.
  • Recent updates support both a central copilot-instructions.md and path/language-specific *.instructions.md files with applyTo frontmatter.
  • These files enable you to customize rules and guidance for Copilot’s review process.

Getting Started: General Tips

  • Be concise: Use focused and short instructions. Large files (over 1,000 lines) may cause inconsistent results.
  • Structure: Organize with headings and bullet points for clarity.
  • Directness: Short, imperative guidelines are more effective than long paragraphs.
  • Examples: Include sample code or example explanations.

Repo-Wide vs Path-Specific Instructions

  • Repo-wide (copilot-instructions.md): General guidelines, team standards, and rules that apply across your repository (e.g., “Flag deprecated libraries anywhere in the codebase”).
  • Path- or Language-specific (*.instructions.md in .github/instructions): Target rules to files by language (e.g., applyTo: **/*.py) or directory. Use excludeAgent to restrict which Copilot agent reads the file. Organize content by topic (e.g., security or language guidelines).

Rules of Thumb for Effective Instructions Files

  1. Clear, descriptive titles
  2. Purpose/scope statement
  3. Bullet lists for readability
  4. Best practices and recommendations
  5. Style conventions (indentation, organization)
  6. Example code blocks
  7. Section headings
  8. Task or feature-specific instructions
  9. Language/tool context
  10. Focus on readability and consistency
  11. Explicit, actionable directives to Copilot

What Not To Do

  • Don’t try to change the UI/format of Copilot comments
  • Don’t attempt to modify the “Pull Request Overview” comment
  • Don’t ask Copilot to perform product behavior outside of code review (e.g., block merges)
  • Don’t include external links (Copilot won’t read them)
  • Don’t insert vague requests (“be more accurate”, “identify all issues”)

Below is a template for a new instructions file:

# [Your Title Here] (e.g., ReactJS Development Guidelines)

## Purpose & Scope

Brief description of what this file addresses.

---

## Naming Conventions

- [e.g., Use camelCase for variable names.]

## Code Style

- [e.g., Indent using 2 spaces.]

## Error Handling

- [Add rules.]

## Testing

- [Add rules.]

## Security

- [Add rules.]

---

## Code Examples
```js

// Correct pattern
function myFunction() { ... }

// Incorrect pattern
function My_function() { ... }

[Optional] Advanced Sections

Framework-Specific Rules

  • [Add tooling/framework-specific rules.]

Advanced Tips & Edge Cases

  • [Document important exceptions/caveats.] ```

Example: typescript.instructions.md

--- applyTo: "**/*.ts" ---

# TypeScript Coding Standards

## Naming Conventions

- Use camelCase for variables/functions.
- Use PascalCase for classes/interfaces.
- Prefix private variables with _.

## Code Style

- Prefer const over let.
- Use arrow functions for callbacks.
- Avoid any type; use precise types.
- Limit lines to 100 characters.

## Error Handling

- Always handle promise rejections.
- Use custom error classes.

## Testing

- Write unit tests for exported functions.
- Use Jest for testing.
- Name test files as <filename>.test.ts.

Getting Started and Editing Instructions

  • Add Copilot as a reviewer via GitHub’s pull request settings.
  • Create .github/copilot-instructions.md or path-specific files like .github/instructions/typescript.instructions.md.
  • Use Copilot coding agent to automatically generate or revise instructions.
  • Use the provided prompt to help Copilot improve or restructure existing instruction files for clarity and compliance with best practices.

Resources

Customizing Copilot review instructions aligns automation with your coding standards—start leveling up your reviews today!

This post appeared first on “The GitHub Blog”. Read the entire article here