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.

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

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.

Observação

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

A versão deste artigo destina-se ao uso de instruções personalizadas de repositório nos IDEs do JetBrains. Clique nas guias acima para saber como usar instruções personalizadas em outros ambientes.

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 Xcode. 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

As instruções personalizadas de repositório permitem fornecer orientações e preferências específicas do repositório ao Copilot.

No momento, há suporte para instruções personalizadas do repositório para:

  • Copilot Chat no Visual Studio, no VS Code e no site do GitHub

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

  • Você deve ter um arquivo de instruções personalizado (confira as instruções abaixo).
  • A versão mais recente da extensão do Copilot deve estar instalada no IDE do JetBrains.
  • A versão mais recente da extensão do Copilot deve estar instalada no Xcode.

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

Os IDEs do JetBrains dão suporte a um único arquivo de instruções personalizado .github/copilot-instructions.md armazenado no repositório.

Você pode criar um arquivo de instruções personalizado em seu repositório usando a página de configurações do Copilot ou criar o arquivo manualmente.

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

Usar a página de configurações

  1. No seu IDE JetBrains, clique no menu Arquivo (Windows) ou no nome do aplicativo na barra de menus (macOS) e clique em Configurações.
  2. Em Linguagens e Estruturas, clique em GitHub Copilot .
  3. Em "Instruções do Copilot", clique em Workspace ou Global para escolher se as instruções personalizadas se aplicam ao workspace atual ou a todos os workspaces.

Criar manualmente um arquivo de instruções personalizadas do workspace

  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.

Depois de salvas, essas instruções serão aplicadas ao workspace atual em IDEs do JetBrains que você abrir com o Copilot habilitado.

Criar manualmente um arquivo de instruções personalizadas global

Para aplicar as mesmas instruções em todos os workspaces em IDEs do JetBrains, você pode criar um arquivo de instruções personalizadas global em seu computador local.

  1. Abra o explorador de arquivos ou o terminal.

  2. Navegue até o local de acordo com seu sistema operacional:

    • macOS: /Users/YOUR-USERNAME/.config/github-copilot/intellij/
    • Windows: C:\Users\YOUR-USERNAME\AppData\Local\github-copilot\intellij\

  3. Crie um arquivo chamado global-copilot-instructions.md nesse diretório.

  4. Adicione suas instruções personalizadas em linguagem natural usando o formato Markdown.

Depois de salvas, essas instruções serão aplicadas globalmente a todos os workspaces em IDEs do JetBrains que você abrir com o Copilot habilitado.

O Xcode dá suporte a um único arquivo de instruções personalizado .github/copilot-instructions.md armazenado no repositório.

Você pode criar um arquivo de instruções personalizado em seu repositório por meio da página de configurações do Copilot.

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

  1. Abra o aplicativo GitHub Copilot para Xcode.
  2. Na parte superior da janela do aplicativo, em Configurações, clique em Avançado.
  3. À direita de "Instruções Personalizadas", clique em Workspace Atual ou Global para escolher se as instruções personalizadas se aplicam ao workspace atual ou a todos os workspaces.

O VS Code é compatível com:

  • Um único arquivo de instruções personalizado .github/copilot-instructions.md armazenado no repositório
  • Um ou mais arquivos .instructions.md armazenados em .github/instructions no repositório. Cada arquivo pode especificar o frontmatter applyTo para definir a quais arquivos ou diretórios suas instruções se aplicam.

Usando um único arquivo .github/copilot-instructions.md

  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 as instruções podem ser escritas como um só parágrafo, cada uma em uma nova linha ou separadas por linhas em branco para facilitar a leitura.

Usando um ou mais arquivos .instructions.md

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

  2. Crie um ou mais arquivos .instructions.md, adicionando instruções de linguagem natural aos arquivos.

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

  3. Especifique a quais arquivos ou diretórios as instruções se aplicam adicionando o frontmatter applyTo aos arquivos Markdown usando a sintaxe glob.

    ---
applyTo: "app/models/**/*.rb"
---

Add custom instructions here

    Para aplicar as instruções a todos os arquivos, use o padrão **.

O Visual Studio dá suporte a um único arquivo de instruções personalizado .github/copilot-instructions.md armazenado no 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 as instruções podem ser escritas como um só parágrafo, cada uma em uma nova linha ou separadas por linhas em branco para facilitar a leitura.

O Copilot Chat no site do GitHub e o Revisão de código do Copilot dão suporte a um único arquivo de instruções personalizado .github/copilot-instructions.md armazenado no repositório.

Além disso, o Agente de codificação do Copilot dá suporte a um ou mais arquivos .instructions.md armazenados em .github/instructions no repositório. Cada arquivo pode especificar o frontmatter applyTo para definir a quais arquivos ou diretórios suas instruções se aplicam.

Usando um único arquivo .github/copilot-instructions.md

  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 as instruções podem ser escritas como um só parágrafo, cada uma em uma nova linha ou separadas por linhas em branco para facilitar a leitura.

Usando um ou mais arquivos .instructions.md

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

  2. Crie um ou mais arquivos .instructions.md, adicionando instruções de linguagem natural aos arquivos.

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

  3. Especifique a quais arquivos ou diretórios as instruções se aplicam adicionando o frontmatter applyTo aos arquivos Markdown usando a sintaxe glob.

    ---
applyTo: "app/models/**/*.rb"
---

Add custom instructions here

    Para aplicar as instruções a todos os arquivos, use o padrão **.

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 instruções personalizadas devem ser curtas e independentes para fornecer ao Copilot informações relevantes para ajudar a funcionar neste repositório. Como as instruções são enviadas com cada mensagem de chat, elas devem ser amplamente aplicáveis à maioria das solicitações que você fará no contexto do repositório.

A estrutura exata usada para seus arquivos de instruções variará de acordo com o projeto e a necessidade, mas as diretrizes a seguir fornecem um bom ponto de partida:

  • Forneça uma visão geral do projeto no qual você está trabalhando, incluindo a finalidade, as metas e demais informações contextuais relevantes.
  • Inclua a estrutura de pastas do repositório, incluindo diretórios ou arquivos importantes relevantes para o projeto.
  • Especifique os padrões de codificação e as convenções que devem ser seguidas, como convenções de nomenclatura, regras de formatação e práticas recomendadas.
  • Inclua outras ferramentas, bibliotecas ou estruturas específicas usadas no projeto, juntamente com números de versão ou configurações relevantes.

Os seguintes arquivos de instruções são um exemplo dessas práticas em ação:

# Project Overview

This project is a web application that allows users to manage their tasks and to-do lists. It is built using React and Node.js, and uses MongoDB for data storage.

## Folder Structure

- `/src`: Contains the source code for the frontend.
- `/server`: Contains the source code for the Node.js backend.
- `/docs`: Contains documentation for the project, including API specifications and user guides.

## Libraries and Frameworks

- React and Tailwind CSS for the frontend.
- Node.js and Express for the backend.
- MongoDB for data storage.

## Coding Standards

- Use semicolons at the end of each statement.
- Use single quotes for strings.
- Use function based components in React.
- Use arrow functions for callbacks.

## UI guidelines

- A toggle is provided to switch between light and dark mode.
- Application should have a modern and clean design.

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

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.

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.

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.

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.

  2. 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.

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

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

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

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.

  2. 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.

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

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

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

  2. 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.

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

  4. 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.