Writing Effective Instructions Files for Copilot Code Review

Copilot code review now reads both repository-wide copilot-instructions.md files and path-specific *.instructions.md files, giving teams a way to shape automated reviews around their own standards. But as with any large language model–based tool, the output is non-deterministic. Crafting instructions that actually steer the review requires understanding what Copilot can and cannot act on, and being deliberate about how guidance is phrased.

Here is what works after reviewing many real-world instructions files, the questions teams frequently ask, and the feedback GitHub has collected.

Start with Structure

The most effective instructions files share a common shape. They tend to include clear titles, a stated purpose, lists of concrete rules rather than long paragraphs, and explicit directives written in the imperative ("Prefer X over Y"). Style conventions, sample code blocks, and context about the language or tooling all help anchor the review to your team's expectations.

Keep the file concise. Even a single line of guidance can shift behavior, while files over roughly 1,000 lines produce inconsistent results. Organize everything under headings and bullet points, and show examples the way you would explain a convention to a teammate. Short, direct rules beat descriptive paragraphs every time.

Repo-Wide versus Path-Specific Guidance

These two mechanisms serve different purposes, and mixing them up undermines both. The centralized copilot-instructions.md is for team-wide standards and general repository guidelines. Path-specific NAME.instructions.md files, placed in .github/instructions with an applyTo frontmatter property, are for rules tied to particular languages or directories.

Some practical splits:

  • Use the applyTo frontmatter in *.instructions.md files to target languages or paths, for example applyTo: **/*.py or applyTo: documentation/*.md.
  • Keep rules specific to Copilot code review or the Copilot coding agent in separate *.instructions.md files, and set the excludeAgent frontmatter property so neither agent reads guidance meant for the other.
  • Organize different topics—security, language conventions, testing—into their own *.instructions.md files.
  • Reserve copilot-instructions.md for what applies everywhere, such as "Flag use of deprecated libraries across the codebase."

What Instructions Cannot Do

A few categories of instruction simply will not work. Trying to change the user interface or formatting of Copilot comments, such as altering fonts, falls outside what the tool supports. The "Pull Request Overview" comment cannot be removed or repurposed. Asking Copilot to perform actions outside the review itself, like blocking a merge, is also out of scope.

External links are ignored entirely, so any relevant context must be copied directly into the instructions file. Finally, general pleas to "be more accurate" or "identify all issues" add noise. Copilot code review is already tuned for these behaviors, and vague language of that kind only obscures the specific rules that matter.

A Repeatable Template

If a blank Markdown file feels like a barrier, this structure is a solid starting point:

# [Your Title Here]
*Example: ReactJS Development Guidelines*

## Purpose & Scope
Briefly describe what this file covers and when to use it.

---

## Naming Conventions
- [Add rules here, e.g., "Use camelCase for variable names."]

## Code Style
- [Add rules here, e.g., "Indent using 2 spaces."]

## Error Handling
- [Add rules here.]

## Testing
- [Add rules here.]

## Security
- [Add rules here.]

---

## Code Examples
```js
// Correct pattern
function myFunction() { ... }

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

---

## [Optional] Task-Specific or Advanced Sections

### Framework-Specific Rules
- [Add any relevant rules for frameworks, libraries, or tooling.]

### Advanced Tips & Edge Cases
- [Document exceptions, advanced patterns, or important caveats.]

Path-Specific File in Practice

Combining those recommendations into a concrete example, here is what a working typescript.instructions.md file looks like:

---
applyTo: "**/*.ts"
---
# TypeScript Coding Standards
This file defines our TypeScript coding conventions for Copilot code review.

## Naming Conventions

- Use `camelCase` for variables and functions.
- Use `PascalCase` for class and interface names.
- Prefix private variables with `_`.

## Code Style

- Prefer `const` over `let` when variables are not reassigned.
- Use arrow functions for anonymous callbacks.
- Avoid using `any` type; specify more precise types whenever possible.
- Limit line length to 100 characters.

## Error Handling

- Always handle promise rejections with `try/catch` or `.catch()`.
- Use custom error classes for application-specific errors.

## Testing

- Write unit tests for all exported functions.
- Use [Jest](https://jestjs.io/) for all testing.
- Name test files as `<filename>.test.ts`.

## Example

```typescript
// Good
interface User {
  id: number;
  name: string;
}

const fetchUser = async (id: number): Promise<User> => {
  try {
    // ...fetch logic
  } catch (error) {
    // handle error
  }
};

// Bad
interface user {
  Id: number;
  Name: string;
}

async function FetchUser(Id) {
  // ...fetch logic, no error handling
}

Setting Up and Iterating

To get started, add Copilot as a reviewer on your pull requests. New custom instructions go in a copilot-instructions.md file inside the .github directory, or as *.instructions.md files within .github/instructions. The awesome-copilot repository has more examples for reference.

For files already in place that need refinement, the Copilot coding agent can do the editing. Navigate to github.com/copilot/agents, select the repository and branch from the dropdown menu in the prompt field, and run a prompt that specifies exactly which instruction files should be edited. Copilot then opens a session, creates a draft pull request with the modified instructions, and adds you as a reviewer when finished.

These prompts tailor instruction files specifically for Copilot code review, so they may make unwanted changes if applied to files meant for other agents.

Custom instruction files turn code review into a tool that reflects how your team actually works. Start small, iterate, and let the reviews improve alongside the instructions.