Como adicionar instruções personalizadas de repositório no GitHub Copilot

Crie um arquivo em um repositório que fornece contexto adicional ao Copilot para o trabalho que ele faz nesse repositório.

Neste artigo

Observação

Atualmente, esse recurso está em versão prévia pública e sujeito a alterações.

Esta versão deste artigo destina-se ao uso de instruções personalizadas de repositório no site do GitHub. Clique nas guias acima para obter informações sobre como usar instruções personalizadas em outros ambientes.

Sobre as instruções personalizadas de repositório para o Copilot

Repository custom instructions are currently supported for:

  • Copilot Chat in VS Code
  • Agente de codificação do Copilot
  • Copilot Chat in Visual Studio, JetBrains IDEs, Xcode, and on the GitHub website (copilot-instructions.md file only)
  • Revisão de código do Copilot (copilot-instructions.md file only)
  • Agente de codificação do Copilot
  • Revisão de código do Copilot

Você pode fazer isso criando um arquivo em seu repositório que fornece ao Copilot as informações contextuais necessárias para gerar respostas de maior qualidade.

O arquivo de instruções personalizadas é usado para respostas de chat, para revisão de código e também pelo Copilot quando você o atribui a um problema ou solicita que ele crie uma solicitação de pull. As instruções incluídas neste arquivo podem ajudar Copilot a trabalhar em arquivos de um modo que corresponda às práticas de trabalho da sua equipe e esteja em conformidade com os padrões de codificação do seu projeto. Confira Sobre o agente de codificação do Copilot.

Exemplo

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

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.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

For examples of repository custom instructions used to configure Revisão de código do Copilot, see Como usar a revisão de código do GitHub Copilot.

Esta versão deste artigo destina-se ao uso de instruções personalizadas de repositório no VS Code. Clique nas guias acima para saber como usar instruções personalizadas em outros ambientes.

Sobre as instruções personalizadas e os arquivos de prompt de repositório para o Copilot

Repository custom instructions are currently supported for:

  • Copilot Chat in VS Code
  • Agente de codificação do Copilot
  • Copilot Chat in Visual Studio, JetBrains IDEs, Xcode, and on the GitHub website (copilot-instructions.md file only)
  • Revisão de código do Copilot (copilot-instructions.md file only)
  • Revisão de código do Copilot

Você pode fazer isso criando um arquivo em seus repositórios que fornece ao Copilot as informações contextuais necessárias para gerar respostas de maior qualidade.

Você pode usar dois tipos de arquivos para fornecer contexto e instruções para o Copilot no VS Code:

  • As instruções personalizadas do repositório permitem especificar instruções e preferências em todo o repositório, em um único arquivo, que o Copilot usará ao trabalhar neste repositório.
  • Os arquivos de prompt (visualização pública) permitem que você salve instruções de prompt comuns e o contexto relevante em arquivos Markdown (*.prompt.md) que pode reutilizar em seus prompts do Copilot Chat. Arquivos de prompt estão disponíveis somente no VS Code.

Embora as instruções personalizadas ajudem a adicionar contexto de toda a base de código a cada fluxo de trabalho de IA, os arquivos de prompt permitem que você adicione instruções a uma interação específica do Copilot.

Exemplo de instruções personalizadas de repositório

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

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.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

For examples of repository custom instructions used to configure Revisão de código do Copilot, see Como usar a revisão de código do GitHub Copilot.

Exemplos de arquivo de prompt

Os exemplos a seguir demonstram como usar esses arquivos de prompt.

  • New React form.prompt.md – contém instruções para uma tarefa reutilizável para gerar um formulário usando o React.

    Your goal is to generate a new React form component.

Ask for the form name and fields if not provided.

Requirements for the form:
- Use form design system components: [design-system/Form.md](../docs/design-system/Form.md)
- Use `react-hook-form` for form state management:
  - Always define TypeScript types for your form data
  - Prefer *uncontrolled* components using register
  - Use `defaultValues` to prevent unnecessary rerenders
- Use `yup` for validation:
  - Create reusable validation schemas in separate files
  - Use TypeScript types to ensure type safety
  - Customize UX-friendly validation rules

  • API security review.prompt.md – contém informações reutilizáveis sobre práticas de segurança para APIs REST, que podem ser usadas para fazer revisões de segurança das APIs REST.

    Secure REST API review:
- Ensure all endpoints are protected by authentication and authorization
- Validate all user inputs and sanitize data
- Implement rate limiting and throttling
- Implement logging and monitoring for security events
…

Observação

Atualmente, esse recurso está em versão prévia pública e sujeito a alterações.

Esta versão deste artigo destina-se ao uso de instruções personalizadas de repositório no Visual Studio. Clique nas guias acima para saber como usar instruções personalizadas em outros ambientes.

Sobre as instruções personalizadas de repositório para o Copilot

Repository custom instructions are currently supported for:

  • Copilot Chat in VS Code
  • Agente de codificação do Copilot
  • Copilot Chat in Visual Studio, JetBrains IDEs, Xcode, and on the GitHub website (copilot-instructions.md file only)
  • Revisão de código do Copilot (copilot-instructions.md file only)
  • Revisão de código do Copilot

Você pode fazer isso criando um arquivo em seus repositórios que fornece ao Copilot as informações contextuais necessárias para gerar respostas de maior qualidade.

Exemplo

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

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.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

For examples of repository custom instructions used to configure Revisão de código do Copilot, see Como usar a revisão de código do GitHub Copilot.

Pré-requisitos para instruções personalizadas de repositório

  • Você deve ter um arquivo de instruções personalizado (confira as instruções abaixo).

Criando um arquivo de instruções personalizadas de repositório

  1. No diretório do repositório, crie um arquivo chamado .github/copilot-instructions.md.

    Crie o diretório .github se ele ainda não existir.

  2. Adicione instruções em linguagem natural ao arquivo, no formato Markdown.

    O espaço em branco entre as instruções é ignorado, de modo que elas podem ser escritas como um só parágrafo, cada uma em uma nova linha ou separadas por linhas em branco para facilitar a leitura.

Para ver as instruções em ação, vá para https://github.com/copilot, anexe o repositório que contém o arquivo de instruções e inicie uma conversa.

Adicionou com êxito um arquivo de instruções personalizado ao repositório?

Sim Não

Escrevendo instruções personalizadas de repositório eficazes

As instruções que você adiciona ao arquivo .github/copilot-instructions.md devem ser curtas e independentes para fornecer ao Copilot informações relevantes para ajudá-lo a trabalhar neste repositório.

Considere também o tamanho e a complexidade do repositório. Os seguintes tipos de instruções podem funcionar para um pequeno repositório com apenas alguns colaboradores, mas para um repositório grande e diversificado, isso pode causar problemas:

  • Solicitações para referência a recursos externos ao formular uma resposta
  • Instruções para resposta em um estilo específico
  • Solicitações para sempre responder com determinado nível de detalhes

Por exemplo, as seguintes instruções podem não ter os resultados pretendidos:

Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code.

Use @terminal when answering questions about Git.

Answer all questions in the style of a friendly colleague, using informal language.

Answer all questions in less than 1000 characters, and words of no more than 12 characters.

Instruções personalizadas de repositório em uso

As instruções contidas no arquivo .github/copilot-instructions.md ficam disponíveis para uso pelo Copilot Chat assim que você salva o arquivo. O conjunto completo de instruções será adicionado automaticamente às solicitações enviadas ao Copilot no contexto desse repositório. Por exemplo, elas são adicionadas ao prompt que você envia ao Copilot Chat.

Na exibição imersiva do Copilot Chat (github.com/copilot), você pode iniciar uma conversa que usa instruções personalizadas de repositório adicionando, como anexo, o repositório que contém o arquivo de instruções.

Sempre que instruções personalizadas de repositório são usadas pelo Copilot Chat, o arquivo de instruções é adicionado como uma referência para a resposta gerada. Para descobrir se instruções personalizadas de repositório foram usadas, expanda a lista de referências na parte superior de uma resposta de chat no painel Chat e verifique se o arquivo .github/copilot-instructions.md está listado.

Captura de tela de uma lista de Referências expandida, mostrando o arquivo "copilot-instructions.md" realçado com um contorno laranja escuro.

Selecione a referência para abrir o arquivo.

Observação

  • É possível que vários tipos de instruções personalizadas se apliquem a uma conversa. Instruções pessoais assumem a prioridade mais alta, seguidas pelas instruções do repositório, com as instruções da organização priorizadas por último. No entanto, todos os conjuntos de instruções relevantes ainda são combinados e fornecidos ao Copilot Chat.
  • Sempre que possível, você deve evitar fornecer conjuntos conflitantes de instruções. Se estiver preocupado com a qualidade da resposta, você também poderá optar por desabilitar temporariamente as instruções do repositório. Confira Como adicionar instruções personalizadas de repositório no GitHub Copilot.

As instruções personalizadas não ficam visíveis na exibição do Chat ou no chat embutido, mas você pode verificar se elas estão sendo usadas pelo Copilot observando a lista Referências de uma resposta na exibição do Chat. Se foram adicionadas instruções personalizadas à solicitação que foi enviada para o modelo, o arquivo .github/copilot-instructions.md será listado como uma referência. Selecione a referência para abrir o arquivo.

Captura de tela de uma lista de Referências expandida, mostrando o arquivo "copilot-instructions.md" realçado com um contorno laranja escuro.

As instruções personalizadas não ficam visíveis na exibição do Chat ou no chat embutido, mas você pode verificar se elas estão sendo usadas pelo Copilot observando a lista Referências de uma resposta na exibição do Chat. Se foram adicionadas instruções personalizadas à solicitação que foi enviada para o modelo, o arquivo .github/copilot-instructions.md será listado como uma referência. Selecione a referência para abrir o arquivo.

Captura de tela do pop-up Referências, mostrando o arquivo "copilot-instructions.md" realçado com um contorno laranja escuro.

Habilitando ou desabilitando instruções personalizadas de repositório

Você pode escolher se quer ou não que o Copilot use instruções personalizadas baseadas em repositório.

Habilitar ou desabilitar instruções personalizadas para o Copilot Chat

As instruções personalizadas são habilitadas para o Copilot Chat por padrão, mas você pode desabilitá-las ou reabilitá-las a qualquer momento. Isso se aplica ao seu próprio uso do Copilot Chat e não afeta outros usuários.

  1. No GitHub.com, siga um destes procedimentos:

    • Vá para um repositório com um arquivo de instruções personalizado e abra o painel de chat assistencial.
    • Vá para a exibição imersiva do Copilot Chat (github.com/copilot) e anexe um repositório que contém um arquivo de instruções personalizado.

  2. Clique no botão na parte superior do painel do Chat ou no canto superior direito da página imersiva.

  3. Clique em Desabilitar instruções personalizadas ou Habilitar instruções personalizadas.

    Observação

    Você só verá essas opções no contexto de um repositório que contém um arquivo de instruções personalizado.

Sua escolha persiste para todos os repositórios que contêm um arquivo de instruções personalizado até que você a altere.

  1. Abra o editor de Configurações usando o atalho de teclado Command+, (Mac)/CTRL+, (Linux/Windows).
  2. Digite instruction file na caixa de pesquisa.
  3. Marque ou desmarque a caixa de seleção em Geração de Código: Usar Arquivos de Instrução.

  1. Na barra de menus do Visual Studio, em Ferramentas, clique em Opções.

    Captura de tela da barra de menus do Visual Studio. O menu "Ferramentas" está expandido e o item "Opções" está realçado com um contorno em laranja.

  2. Na caixa de diálogo "Options", digite custom instructions na caixa de pesquisa e clique em Copilot.

  3. Marque ou desmarque a caixa de seleção de (Versão prévia) Habilitar instruções personalizadas a serem carregadas dos arquivos .github/copilot-instructions.md e adicionadas às solicitações.

Como habilitar ou desabilitar instruções personalizadas do repositório para o Revisão de código do Copilot

As instruções personalizadas são habilitadas para o Revisão de código do Copilot por padrão, mas você pode desabilitá-las ou reabilitá-los nas configurações do repositório em GitHub.com. Isso se aplica ao uso do Copilot de instruções personalizadas para todas as revisões de código executadas neste repositório.

  1. Em GitHub, acesse a página principal do repositório. 1. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  2. Na seção "Code & automation" da barra lateral, clique em Copilot e em Code review.

  3. Ative ou desative a opção "Use custom instructions when reviewing pull requests".

Habilitando e usando arquivos de prompt

Observação

Os arquivos de prompt estão em versão prévia pública e estão sujeitos a alterações.

Os arquivos de prompt permitem que você crie e compartilhe instruções de prompt reutilizáveis com contexto adicional. Um arquivo de prompt é um arquivo markdown armazenado em seu workspace que imita o formato existente de escrita de prompts no Copilot Chat (por exemplo, Rewrite #file:x.ts). Você pode ter vários arquivos de prompt em seu workspace, cada um deles define um prompt para uma finalidade diferente.

Como habilitar arquivos de prompt

Para habilitar arquivos de prompt, defina as configurações do workspace.

  1. Abra a paleta de comandos pressionando Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac).
  2. Digite "Abrir Configurações do Workspace (JSON)" e selecione a opção exibida.
  3. No arquivo settings.json, adicione "chat.promptFiles": true para habilitar a pasta .github/prompts como o local para arquivos de prompt. Essa pasta será criada se ainda não existir.

Como criar arquivos de prompt

  1. Abra a paleta de comandos pressionando Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac).

  2. Digite "prompt" e selecione Chat: Criar Prompt.

  3. Insira um nome para o arquivo de prompt, excluindo a extensão de nome de arquivo .prompt.md. O nome pode conter caracteres alfanuméricos e espaços e deve descrever a finalidade das informações do prompt que o arquivo conterá.

  4. Escreva as instruções do prompt usando formatação de Markdown.

    Você pode referenciar outros arquivos no workspace usando links markdown, por exemplo, [index](../../web/index.ts), ou usando a sintaxe #file:../../web/index.ts. Os caminhos são relativos ao arquivo de prompt. Fazer referência a outros arquivos permite que você forneça contexto adicional, como especificações de API ou a documentação do produto.

Usando arquivos de prompt

  1. Na parte inferior da exibição do Copilot Chat, clique no ícone Attach context ().

  2. No menu suspenso, clique em Prompt... e escolha o arquivo de prompt que você deseja usar.

  3. Opcionalmente, anexe mais arquivos, incluindo arquivos de prompt, para fornecer mais contexto.

  4. Você também pode digitar informações adicionais na caixa de prompt de chat.

    A necessidade de fazer isso dependerá do conteúdo do prompt que você está usando.

  5. Envie o prompt de chat.

Para obter mais informações sobre arquivos de prompt, consulte Instruções personalizadas para o GitHub Copilot no VS Code na documentação do Visual Studio Code.