Copilot: Custom Instructions & Context

Influencing Copilot's Behavior

Copilot primarily learns from the context of your current file, open tabs, and your overall project structure. Here's how you can guide it:

• Clear Code and Comments: Well-structured, readable code with clear, descriptive comments (including JSDoc, TSDoc, Python docstrings, etc.) provides strong hints to Copilot about intent, style, and expected behavior.
• File and Project Structure: A logically organized project helps Copilot understand relationships between different parts of your code.
• Open Tabs as Context: Copilot often uses your currently open files in the IDE as a primary source of context. Keeping relevant files open can improve suggestion quality.
• Prompt Engineering: Explicitly state your requirements, preferred libraries, or coding standards directly in your prompts when using Copilot Chat or generating code blocks. (Covered in Section 2).
• Editor/IDE Settings:
  • Language-Specific Settings: Configure your IDE's formatters, linters (e.g., ESLint, Prettier, Pylint, Checkstyle) and code style settings (.editorconfig). Copilot often tries to adhere to these established styles.
  • .vscode/settings.json (for VS Code): Project-specific settings in VS Code can define formatting rules, linter configurations, and other preferences that Copilot may pick up on.

Leveraging Comments and Examples

You can embed "custom instructions" or preferences within comments, especially when starting a new block of code or asking Copilot Chat for assistance.

Example: Guiding Copilot with Comments:

// Task: Create a function to fetch user data from '/api/users/{id}'
// Requirements:
// - Use the 'axios' library for the GET request.
// - Implement error handling for network issues and non-200 responses.
// - Return the user data object on success, or null on failure.
// - Adhere to async/await syntax.

async function fetchUserData(userId) {
  // Copilot will attempt to generate code based on the comments above
  // and the function signature.
}
                  

In Copilot Chat, you can be more explicit:

Write a Python function called `process_data`.
It should take a list of dictionaries as input.
For each dictionary, extract the 'value' key and multiply it by 2.
Return a new list containing these modified values.
Please ensure the function includes a docstring explaining its purpose, arguments, and return value.
Only use standard Python libraries.
                  

Tips for Effective Context with Copilot

• Be Explicit in Prompts: When using Copilot Chat or asking for specific code generation, clearly state your requirements, preferred libraries, and any constraints.
• Provide Examples: If you want code in a very specific style or format, provide a small example in a comment or your prompt.
• Keep Relevant Files Open: This is a key way Copilot gathers context. If working on a feature that spans multiple files, having them open can lead to more relevant suggestions.
• Use Your IDE's Features: Leverage your IDE's code formatting, linting, and project-specific settings. Copilot often tries to match the existing style and conventions.
• Iterate: If the first suggestion isn't perfect, refine your prompt or the surrounding code and try again.

Repository Custom Instructions

GitHub Copilot can provide chat responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context. Instead of repeatedly adding this contextual detail to your chat questions, you can create a file in your repository that automatically adds this information for you.

The additional information is not displayed in the chat, but is available to Copilot to allow it to generate higher quality responses.

Prerequisites

• Custom instructions file: You need to create a special file (see below)
• Personal setting: Your personal choice of whether to use custom instructions must be set to enabled. This is enabled by default.
• For Copilot Business plans: During the public preview, if you're using a Copilot Business plan, the organization that provides your plan must have the "opt in to preview features" setting enabled.

Creating a Repository Custom Instructions File

Follow these steps to add custom instructions to your repository:

1. In the root of your repository, create a file named .github/copilot-instructions.md
2. Create the .github directory if it does not already exist.
3. Add natural language instructions to the file, in Markdown format.
4. White space between instructions is ignored, so the instructions can be written as a single paragraph or separated into multiple paragraphs.

Example of a custom instructions file:

We use Bazel for managing our Java dependencies, not Maven, so when talking about Java packages, always give me instructions and code samples that use Bazel.

Please format all code examples according to Google Java Style Guide.

When responding to questions about our API, note that we're in the process of migrating from v1 to v2, and you should recommend v2 endpoints where available.

Writing Effective Repository Custom Instructions

The instructions you add to the .github/copilot-instructions.md file should be short, self-contained statements that add context or relevant information to supplement users' chat questions.

Consider the size and complexity of your repository. The following types of instructions may work for a small repository with only a few contributors, but for a large and diverse repository, they may cause problems with other areas of Copilot:

• Requests to refer to external resources when formulating a response
• Instructions to answer in a particular style
• Requests to always respond with a certain level of detail

Examples of effective instructions:

• Specific technology preferences: "We use TypeScript for all new frontend code."
• Project-specific conventions: "All React components should use functional style with hooks, not class components."
• Code style guidelines: "Follow AirBnB JavaScript style guide for all JS code."
• Architecture notes: "Our backend follows a microservices architecture with API Gateway pattern."

Using Repository Custom Instructions

The instructions in the .github/copilot-instructions.md file are available for use by Copilot Chat as soon as you save the file. The complete set of instructions will be automatically added to chat prompts that relate to the repository containing the instructions file.

In Copilot Chat's immersive view, you can start a conversation that uses repository custom instructions by adding, as an attachment, the repository that contains the instructions file.

Whenever repository custom instructions are used by Copilot Chat, the instructions file is added as a reference for the response that's generated. To find out whether repository custom instructions were used, expand the list of references at the top of a chat response in the Chat panel and check whether the .github/copilot-instructions.md file is listed.