- **Use concise, structured instructions** - Keep files short and to the point to avoid inconsistent behavior. - Organize with headings, bullet points, and imperative rules. - **Differentiate between repo-wide and path-specific instructions** - `copilot-instructions.md`: General, team-wide, and repository-level guidelines. - `*.instructions.md`: Language or topic-specific rules with `applyTo` filters. - **Include actionable and explicit guidance** - Provide naming conventions, code style rules, and task-specific instructions. - Add sample code blocks to illustrate best and bad practices. - **Avoid unsupported directives** - Do not try to change Copilot comment formatting, PR behavior, or include external links. - **Recommended structure improves clarity** - Titles, purpose statement, sections for conventions, style, error handling, testing, and optional advanced tips. ## Code Snippets ### Basic Instructions File Template A starting structure for creating a `copilot-instructions.md` file. ````markdown # [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.] ```` ### Example: TypeScript Path-Specific Instructions File Demonstrates a complete `typescript.instructions.md` configuration with targeted rules. ````markdown --- 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 } ``` ```` ### Prompt for Copilot Coding Agent: Revise My Instructions File Use this prompt to have Copilot automatically improve your instruction files. ````markdown Review and revise my existing `NAME-OF-INSTRUCTION-FILES` files. Preserve my file's meaning and intention—do NOT make unnecessary changes or edits. Only make improvements where needed, specifically: - Remove unsupported or redundant content. Unsupported content includes: - instructions to change Copilot code review comment formatting (font, font size, adding headers, etc) - instructions to change "PR Overview" comment content - instructions for product behavior changes outside of existing code review functionality (like trying to block a pull request from merging) - Vague, non-specific directives like “be more accurate”, "identify all issues" or similar - Directives to “follow links” or inclusion of any external links - Reformat sections for clarity if they do not have any structure. - If my file does not have any structure, reformat into the structure below or similar, depending on the topics covered in the file. - Do not change the intent or substance of the original content unless the content is not supported. - Organize content with section headings and bullet points or numbered lists. - Add sample code blocks if clarification is needed and they are missing. - When applicable, separate language-specific rules into path-specific instructions files with the format `NAME.instructions.md`, with the `applyTo` property, if not already done. - If the file is over 4000 characters long, prioritize shortening the file by identifying redundant instructions, instructions that could be summarized, and instructions that can be removed due to being unsupported. **Example Structure:** # Python Coding Standards Guidelines for Python code reviews with Copilot. ## Naming Conventions - Use `snake_case` for functions and variables. - Use `PascalCase` for class names. ## Code Style - Prefer list comprehensions for simple loops. - Limit lines to 80 characters. ## Error Handling - Catch specific exceptions, not bare `except:`. - Add error messages when raising exceptions. ## Testing - Name test files as `test_*.py`. - Use `pytest` for tests. ## Example ```python # Good def calculate_total(items): return sum(items) # Bad def CalculateTotal(Items): total = 0 for item in Items: total += item return total ``` ### Framework-Specific Rules - For Django, use class-based views when possible. ### Advanced Tips & Edge Cases - Use type hints for function signatures. ```` ## Resources - [Original Article](https://github.com/blog/copilot-code-review-instructions) - [GitHub Docs: Copilot code review custom instructions](https://docs.github.com/en/copilot) - [awesome-copilot repository](https://github.com/github/awesome-copilot)