{"meta":{"title":"Using custom instructions to unlock the power of Copilot code review","intro":"Learn how to write effective custom instructions that help GitHub Copilot provide more relevant and actionable code reviews.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/tutorials","title":"Tutorials"},{"href":"/en/copilot/tutorials/customize-code-review","title":"Customize code review"}],"documentType":"article"},"body":"# Using custom instructions to unlock the power of Copilot code review\n\nLearn how to write effective custom instructions that help GitHub Copilot provide more relevant and actionable code reviews.\n\n## Introduction\n\nGitHub Copilot code review can be customized using instruction files to tailor the review experience to your team's needs and coding standards. However, writing effective custom instructions requires understanding how Copilot processes these instructions and what approaches work best.\n\nIn this tutorial, you'll learn how to write clear, effective custom instructions that help Copilot provide more relevant code reviews. You'll discover best practices for structuring your instructions, common pitfalls to avoid, and strategies for organizing instructions across different files.\n\nThis tutorial is about using custom instructions for Copilot code review. For a more general introduction to using custom instructions, see [Configure custom instructions for GitHub Copilot](/en/copilot/how-tos/configure-custom-instructions).\n\n### What you'll learn\n\nBy the end of this tutorial, you'll understand:\n\n* How to write concise, effective custom instructions for code review.\n* The difference between repository-wide and path-specific instructions.\n* Common patterns that work well with Copilot code review.\n* What types of instructions are not currently supported.\n* How to structure and organize your instructions for best results.\n\n### Prerequisites\n\n* Access to Copilot code review.\n* A GitHub repository where you can create custom instruction files.\n* Basic familiarity with Markdown syntax.\n\n## Understanding how GitHub Copilot code review processes instructions\n\nBefore writing custom instructions, it's helpful to understand how Copilot code review uses them. When reviewing a pull request, Copilot reads your instruction files and uses them to guide its analysis. However, like any AI system, it has limitations:\n\n* **Non-deterministic behavior**: Copilot may not follow every instruction perfectly every time.\n* **Context limits**: Very long instruction files may result in some instructions being overlooked.\n* **Specificity matters**: Clear, specific instructions work better than vague directives.\n\nKeep these factors in mind as you write your instructions—they'll help you set realistic expectations and write more effective guidance.\n\n> \\[!NOTE]\n>\n> * Copilot code review only reads the first 4,000 characters of any custom instruction file. Any instructions beyond this limit will not affect the reviews generated by Copilot code review. This limit does not apply to Copilot Chat or Copilot cloud agent.\n> * When reviewing a pull request, Copilot uses the custom instructions in the base branch of the pull request. For example, if your pull request seeks to merge `my-feature-branch` into `main`, Copilot will use the custom instructions in `main`.\n\n## Writing effective custom instructions\n\nThe key to successful custom instructions is to be clear, concise, and specific. Here are the core principles to follow:\n\n### Keep instructions short and focused\n\nShorter instruction files are more likely to be fully processed by Copilot. Start with a minimal set of instructions and add more iteratively based on what works.\n\n**Best practice**: Limit any single instruction file to a maximum of about 1,000 lines. Beyond this, the quality of responses may deteriorate.\n\n### Use clear structure and formatting\n\nCopilot benefits from well-structured instructions with:\n\n* **Distinct headings** that separate different topics.\n* **Bullet points** for easy scanning and reference.\n* **Short, imperative directives** rather than long narrative paragraphs.\n\nFor example, instead of writing:\n\n```markdown\nWhen you're reviewing code, it would be good if you could try to look for\nsituations where developers might have accidentally left in sensitive\ninformation like passwords or API keys, and also check for security issues.\n```\n\nWrite:\n\n```markdown\n## Security Critical Issues\n\n- Check for hardcoded secrets, API keys, or credentials\n- Look for SQL injection and XSS vulnerabilities\n- Verify proper input validation and sanitization\n```\n\n### Provide concrete examples\n\nJust like when you explain a concept to a colleague, examples help Copilot understand what you mean. Include code snippets showing both correct and incorrect patterns.\n\nFor example:\n\n````markdown\n## Naming Conventions\n\nUse descriptive, intention-revealing names.\n\n```javascript\n// Avoid\nconst d = new Date();\nconst x = users.filter(u => u.active);\n\n// Prefer\nconst currentDate = new Date();\nconst activeUsers = users.filter(user => user.isActive);\n```\n````\n\n## Organizing instructions across files\n\nCopilot code review supports two types of instruction files:\n\n1. **`copilot-instructions.md`**: Repository-wide instructions that apply to all files.\n2. **`*.instructions.md`**: Path-specific instructions that apply to certain files or directories.\n\nUse path-specific instructions to keep Copilot focused and prevent it from applying language-specific rules to the wrong files.\n\n### When to use repository-wide instructions\n\nUse `copilot-instructions.md` for:\n\n* General team standards and guidelines\n* Universal security requirements\n* Cross-cutting concerns like error handling philosophy\n* Documentation expectations\n\n**Example structure for `copilot-instructions.md`**:\n\n```markdown copy\n# General Code Review Standards\n\n## Code Quality Essentials\n\n- Functions should be focused and appropriately sized\n- Use clear, descriptive naming conventions\n- Ensure proper error handling throughout\n\n## Security Standards\n\n- Never hardcode credentials or API keys\n- Validate all user inputs\n- Use parameterized queries to prevent SQL injection\n\n## Documentation Expectations\n\n- All public functions must include doc comments\n- Complex algorithms should have explanatory comments\n- README files must be kept up to date\n```\n\n### When to use path-specific instructions\n\nUse `*.instructions.md` files with the `applyTo` frontmatter property for:\n\n* Language-specific coding standards\n* Framework-specific patterns\n* Technology-specific security concerns\n* Different rules for different parts of your codebase\n\n**Example: Python-specific instructions**\n\nCreate a file called `python.instructions.md` in the `.github/instructions` directory:\n\n````text copy\n---\napplyTo: \"**/*.py\"\n---\n\n# Python Coding Conventions\n\n## Naming Conventions\n\n- Use snake_case for variables and functions\n- Use PascalCase for class names\n- Use UPPERCASE for constants\n\n## Code Style\n\n- Follow PEP 8 style guidelines\n- Limit line length to 88 characters (Black formatter standard)\n- Use type hints for function signatures\n\n## Best Practices\n\n- Use list comprehensions for simple transformations\n- Prefer f-strings for string formatting\n- Use context managers (with statements) for resource management\n\n```python\n# Avoid\nfile = open('data.txt')\ncontent = file.read()\nfile.close()\n\n# Prefer\nwith open('data.txt') as file:\n    content = file.read()\n```\n````\n\n**Example: Frontend-specific instructions**\n\nCreate a file called `frontend.instructions.md` in the `.github/instructions` directory:\n\n```text copy\n---\napplyTo: \"src/components/**/*.{tsx,jsx}\"\n---\n\n# React Component Guidelines\n\n## Component Structure\n\n- Use functional components with hooks\n- Keep components small and focused (under 200 lines)\n- Extract reusable logic into custom hooks\n\n## State Management\n\n- Use useState for local component state\n- Use useContext for shared state across components\n- Avoid prop drilling beyond 2-3 levels\n\n## Accessibility\n\n- All interactive elements must be keyboard accessible\n- Include appropriate ARIA labels\n- Ensure color contrast meets WCAG AA standards\n```\n\n### Breaking up complex instruction sets\n\nFor large repositories with many concerns, break instructions into multiple focused files:\n\n```text\n.github/\n  copilot-instructions.md          # General standards\n\n.github/instructions/\n  python.instructions.md           # Python-specific\n  javascript.instructions.md       # JavaScript-specific\n  security.instructions.md         # Security-specific\n  api.instructions.md              # API-specific\n```\n\nEach file should have a clear, specific purpose and appropriate `applyTo` frontmatter when needed.\n\n## Recommended instruction file structure\n\nBased on what works well with Copilot code review, here's a recommended template for structuring your instructions:\n\n````text copy\n---\napplyTo: \"**/*.{js,ts}\"  # If this is a path-specific file\n---\n\n# [Title: Technology or Domain Name] Guidelines\n\n## Purpose\n\nBrief statement of what this file covers and when these instructions apply.\n\n## Naming Conventions\n\n- Rule 1\n- Rule 2\n- Rule 3\n\n## Code Style\n\n- Style rule 1\n- Style rule 2\n\n```javascript\n// Example showing correct pattern\n```\n\n## Error Handling\n\n- How to handle errors\n- What patterns to use\n- What to avoid\n\n## Security Considerations\n\n- Security rule 1\n- Security rule 2\n\n## Testing Guidelines\n\n- Testing expectation 1\n- Testing expectation 2\n\n## Performance\n\n- Performance consideration 1\n- Performance consideration 2\n````\n\nAdapt this structure to your specific needs, but maintain the clear sectioning and bullet-point format.\n\n## What not to include in custom instructions\n\nUnderstanding what Copilot code review currently doesn't support helps you avoid wasting time on instructions that won't work.\n\n### Unsupported instruction types\n\nCopilot code review currently does not support instructions that attempt to:\n\n**Change the user experience or formatting**:\n\n* `Use bold text for critical issues`\n* `Change the format of review comments`\n* `Add emoji to comments`\n\n**Modify the pull request overview comment**:\n\n* `Include a summary of security issues in the PR overview`\n* `Add a testing checklist to the overview comment`\n\n**Change GitHub Copilot's core function**:\n\n* `Block a PR from merging unless all Copilot code review comments are addressed`\n* `Generate a changelog entry for every PR`\n\n**Follow external links**:\n\n* `Review this code according to the standards at https://example.com/standards`\n\n  Workaround: Copy the relevant content directly into your instruction file instead\n\n**Vague quality improvements**:\n\n* `Be more accurate`\n* `Don't miss any issues`\n* `Be consistent in your feedback`\n\nThese types of instructions add noise without improving Copilot's effectiveness, as it's already optimized to provide accurate, consistent reviews.\n\n## Testing and iterating on your instructions\n\nThe best approach to creating effective custom instructions is to start small and iterate based on results.\n\n### Start with a minimal instruction set\n\nBegin with 10–20 specific instructions that address your most common review needs, then test whether these are influencing Copilot code review in the way you intended.\n\n### Test with real pull requests\n\nAfter creating your instructions:\n\n1. Open a pull request in your repository.\n2. Request a review from Copilot.\n3. Observe which instructions it follows effectively.\n4. Note any instructions that are consistently missed or misinterpreted.\n\n### Iterate based on results\n\nAdd new instructions one at a time or in small groups:\n\n1. Identify a pattern that Copilot could review better.\n2. Add a specific instruction for that pattern.\n3. Test with a new pull request.\n4. Refine the instruction based on results.\n\nThis iterative approach helps you understand what works and keeps your instruction files focused.\n\n## Example: Complete custom instructions for code review\n\nHere's a complete example that incorporates all the best practices from this tutorial:\n\n**File: `.github/copilot-instructions.md`**\n\n```markdown copy\n# General Code Review Standards\n\n## Purpose\n\nThese instructions guide Copilot code review across all files in this repository.\nLanguage-specific rules are in separate instruction files.\n\n## Security Critical Issues\n\n- Check for hardcoded secrets, API keys, or credentials\n- Look for SQL injection and XSS vulnerabilities\n- Verify proper input validation and sanitization\n- Review authentication and authorization logic\n\n## Performance Red Flags\n\n- Identify N+1 database query problems\n- Spot inefficient loops and algorithmic issues\n- Check for memory leaks and resource cleanup\n- Review caching opportunities for expensive operations\n\n## Code Quality Essentials\n\n- Functions should be focused and appropriately sized (under 50 lines)\n- Use clear, descriptive naming conventions\n- Ensure proper error handling throughout\n- Remove dead code and unused imports\n\n## Review Style\n\n- Be specific and actionable in feedback\n- Explain the \"why\" behind recommendations\n- Acknowledge good patterns when you see them\n- Ask clarifying questions when code intent is unclear\n\n## Testing Standards\n\n- New features require unit tests\n- Tests should cover edge cases and error conditions\n- Test names should clearly describe what they test\n\nAlways prioritize security vulnerabilities and performance issues that could impact users.\n```\n\n**File: `.github/instructions/typescript.instructions.md`**\n\n````text copy\n---\napplyTo: \"**/*.{ts,tsx}\"\n---\n\n# TypeScript Development Standards\n\n## Type Safety\n\n- Avoid using `any` type—use `unknown` or specific types instead\n- Use strict null checks (no `null` or `undefined` without explicit handling)\n- Define interfaces for all object shapes\n\n```typescript\n// Avoid\nfunction processData(data: any) {\n    return data.value;\n}\n\n// Prefer\ninterface DataShape {\n    value: string;\n}\n\nfunction processData(data: DataShape): string {\n    return data.value;\n}\n```\n\n## Naming Conventions\n\n- Use PascalCase for types, interfaces, and classes\n- Use camelCase for variables, functions, and methods\n- Use UPPER_CASE for constants\n\n## Modern TypeScript Patterns\n\n- Use optional chaining (`?.`) and nullish coalescing (`??`)\n- Prefer `const` over `let`; never use `var`\n- Use arrow functions for callbacks and short functions\n\n## React-Specific (for .tsx files)\n\n- Use functional components with TypeScript props interfaces\n- Type all props and state explicitly\n- Use proper event types (e.g., `React.ChangeEvent<HTMLInputElement>`)\n````\n\n## Troubleshooting common issues\n\nIf Copilot code review isn't following your instructions as expected, try these solutions:\n\n### Issue: Instructions are ignored\n\n**Possible causes**:\n\n* Instruction file is too long (over 1,000 lines).\n* Instructions are vague or ambiguous.\n* Instructions conflict with each other.\n\n**Solutions**:\n\n* Shorten the file by removing less important instructions.\n* Rewrite vague instructions to be more specific and actionable.\n* Review for conflicting instructions and prioritize the most important ones.\n\n### Issue: Language-specific rules applied to wrong files\n\n**Possible causes**:\n\n* Missing or incorrect `applyTo` frontmatter.\n* Rules in repository-wide file instead of path-specific file.\n\n**Solutions**:\n\n* Add `applyTo` frontmatter to path-specific instruction files.\n* Move language-specific rules from `copilot-instructions.md` to appropriate `*.instructions.md` files.\n\n### Issue: Inconsistent behavior across reviews\n\n**Possible causes**:\n\n* Instructions are too numerous.\n* Instructions lack specificity.\n* Natural variability in AI responses.\n\n**Solutions**:\n\n* Focus on your highest-priority instructions.\n* Add concrete examples to clarify intent.\n* Accept that some variability is normal for AI systems.\n\n## Conclusion\n\nEffective custom instructions help Copilot code review provide more relevant, actionable feedback tailored to your team's standards. By following the principles in this tutorial—keeping instructions concise, providing clear structure, using concrete examples, and organizing across multiple files—you can significantly improve your code review experience.\n\nRemember that creating effective instructions is an iterative process. Start with a small set of focused instructions, test them with real pull requests, and gradually expand based on what works well for your team.\n\n## Next steps\n\n* Take a look at some of the [example custom instructions](https://github.com/github/awesome-copilot/tree/main/instructions) in the Awesome GitHub Copilot repository for inspiration.\n* Read [About customizing GitHub Copilot responses](/en/copilot/concepts/prompting/response-customization) to learn about the full range of customization options.\n* Explore [Configure custom instructions for GitHub Copilot](/en/copilot/how-tos/configure-custom-instructions) for technical details on setting up instruction files."}