Mastering Copilot Code Review: How to Write Effective Instructions Files for Better Automation

Modern development teams increasingly rely on GitHub Copilot code review (CCR) to streamline their workflows, but the secret to unlocking its full potential lies in how you guide it. 

With robust support for both repo-wide and path-specific instructions, Copilot can enforce your team's unique standards if you communicate them clearly. Well-structured instructions not only boost review quality and consistency, but also save developers valuable time.

For me personally the instructions and agents.md files have been a game changer for development and creative workflows. By continuously updating these files with more concise instructions for your project you can steer the model to become exceptionally efficient at your workflow.

Understanding the Importance of Instructions

Copilot’s effectiveness hinges on its ability to interpret your instructions files. Its non-deterministic nature means results can vary, but actionable and specific guidance gets the best results. 

Remember, while Copilot strives to follow your directions, it may not always match them precisely. The more direct and thoughtful your instructions, the more value you’ll see in your automated reviews.

Best Practices for Writing Instructions

• Be concise: Use short, clear rules. Avoid overly long files—anything over about 1,000 lines can reduce consistency.
  
  
• Structure content: Headings and bullet points improve clarity and readability.
  
  
• Use actionable language: Write imperative, specific rules like “Use camelCase for variables.”
  
  
• Provide examples: Show code snippets or before/after fixes to clarify expectations, just like with a peer.

Repo-Wide vs. Path-Specific Guidance

Copilot now lets you tailor instructions for different scopes:

• copilot-instructions.md: Sets general, repo-wide standards such as naming conventions and deprecation rules.
  
  
• NAME.instructions.md: Targets specific languages or folders using the applyTo Copy frontmatter property (e.g., only *.py Copy files or particular directories).

Improving organization by topic or scope like security, language style, or tooling makes instructions more effective. The excludeAgent Copy property allows fine-tuning for particular Copilot agents as needed.

Recommended Structure for Maximum Clarity

A well-structured instructions file helps Copilot deliver better results. Consider including:

• Descriptive titles
• Clear purpose or scope statements
• Guidelines in lists, not dense paragraphs
• Best practices and style conventions
• Code samples for illustration
• Section headings for easy navigation
• Language or tooling-specific advice
• Directives such as “Prefer const over let”

The blog provides a ready-to-use template covering essential topics like naming, code style, error handling, testing, and security to jumpstart your process.

Pitfalls to Avoid When Writing Instructions

• Don’t attempt to change Copilot’s comment formatting or pull request overview style.
  
  
• Don’t ask Copilot to enforce actions outside code review (like blocking merges).
  
  
• Don’t include external links since Copilot ignores them. Consolidate all crucial information within the file.
  
  
• Don’t make vague requests (“be more accurate”); Copilot is already tuned for review quality.

Applying Best Practices: A TypeScript Example

The Github team highlights a typescript.instructions.md sample that demonstrates how to set naming conventions, code style preferences (e.g., favoring const Copy and arrow functions), error handling, and testing practices with concise code examples. This specificity clarifies expectations for both Copilot and contributors alike.

---
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
}

Getting Started and Continuous Improvement

• Add Copilot as a reviewer to automate code reviews on your pull requests.
  
  
• Create or edit instructions: Use copilot-instructions.md Copy for general standards, or path-specific files to target certain areas. Start with the provided template or leverage Copilot’s coding agent to draft and refine your files.
  
  
• Iterate your instructions: Have Copilot review your guidelines for unsupported content and optimal structure to maximize clarity and compliance.

Further Resources

• Consult GitHub Docs for detailed documentation and examples.
• Explore the awesome-copilot repository to see community-contributed instruction files for inspiration.

Takeaway

Customizing Copilot code review with thoughtfully crafted instructions files empowers your team to enforce coding standards at scale. Start small, iterate, and watch Copilot elevate your code quality, consistency, and developer productivity—one instruction at a time.

Source: GitHub Blog