Fluxo de trabalho de IA confiável com GitHub Copilot: guia completo com exemplos

Olá! Hoje compartilho um guia rápido sobre como configurar um projeto para trabalhar com o GitHub Copilot.

Fluxo de trabalho de IA confiável com GitHub Copilot: guia completo com exemplos

Este guia mostra como criar processos (fluxos de trabalho) de IA previsíveis e reproduzíveis em seu repositório e IDE/CLI usando primitivas de agente e engenharia de contexto. Aqui você encontrará estrutura de arquivos, modelos prontos, regras de segurança e comandos.

⚠️ Observação: a funcionalidade dos arquivos de prompt e do modo agente na IDE/CLI pode mudar — adapte o guia às versões específicas do Copilot e VS Code que você está usando.

1) Visão Geral: do que é composto o fluxo de trabalho

O objetivo principal é dividir o trabalho do agente em etapas transparentes e torná-las controláveis. Para isso, existem as seguintes ferramentas:

• Instruções Personalizadas (.github/copilot-instructions.md) — regras globais do projeto (como compilar, como testar, estilo de código, políticas de PR).
• Instruções Específicas de Caminho (.github/instructions/*.instructions.md) — regras para áreas específicas, aplicadas via applyTo (padrões glob).
• Modos de Chat (.github/chatmodes/*.chatmode.md) — modos de chat especializados (por exemplo, Planejamento/Frontend/DBA) com ferramentas e modelo fixos.
• Arquivos de Prompt (.github/prompts/*.prompt.md) — cenários/"programas" reutilizáveis para tarefas típicas (revisão, refatoração, geração).
• Auxiliares de Contexto (docs/*.spec.md, docs/*.context.md, docs/*.memory.md) — especificações, referências e memória do projeto para contexto preciso.
• Servidores MCP (.vscode/mcp.json ou via UI) — ferramentas e recursos externos que o agente pode usar.

2) Estrutura de Arquivos do Projeto

A seguinte estrutura corresponde às ferramentas descritas acima e ajuda a construir um fluxo de trabalho completo para agentes.

1.github/
2  copilot-instructions.md
3  instructions/
4    backend.instructions.md
5    frontend.instructions.md
6    actions.instructions.md
7  prompts/
8    implement-from-spec.prompt.md
9    security-review.prompt.md
10    refactor-slice.prompt.md
11    test-gen.prompt.md
12  chatmodes/
13    plan.chatmode.md
14    frontend.chatmode.md
15.vscode/
16  mcp.json
17docs/
18  feature.spec.md
19  project.context.md
20  project.memory.md

3) Arquivos e suas Funções — Explicação Técnica

Agora, vamos analisar cada ferramenta separadamente e seu papel. Abaixo, é explicado como tudo isso funciona nos bastidores: o que esses arquivos representam, por que existem, como afetam a compreensão da tarefa pelo agente e em que ordem eles são combinados / substituídos. Os exemplos de código abaixo correspondem à especificação.

Ordem de combinação de regras e configurações: Frontmatter do prompt → Modo de chat → Instruções do Repo/Caminho → Padrões.

E agora, vamos analisar cada ferramenta individualmente.

3.1. Regras Globais — .github/copilot-instructions.md

O que é: Arquivo Markdown com regras curtas e verificáveis: como compilar, como testar, estilo de código e políticas de PR.

Por quê: Para que todas as respostas se baseiem em um conjunto unificado de padrões (sem duplicação em cada prompt).

Como funciona: O arquivo se torna automaticamente parte do contexto do sistema para todas as perguntas dentro do repositório. Não há applyTo (disso falaremos abaixo) — ele é aplicado em todos os lugares.

Exemplo mínimo:

1# Padrões de codificação do repositório
2- Compilar: `npm ci && npm run build`
3- Testes: `npm run test` (cobertura ≥ 80%)
4- Lint/Verificação de Tipo: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; mantenha os PRs pequenos e focados
6- Docs: atualize `CHANGELOG.md` em cada PR de release

Dicas.

1. Mantenha os itens curtos.
2. Evite frases genéricas.
3. Inclua apenas o que pode afetar o resultado (build/test/lint/type/política de PR).

3.2. Instruções para Caminhos Específicos — .github/instructions/*.instructions.md

O que é: Regras modulares com applyTo no frontmatter YAML — padrões glob de arquivos para os quais elas se aplicam.

Por quê: Para diferenciar padrões em diferentes áreas (frontend/backend/CI). Permite controlar o contexto dependendo do tipo de tarefa.

Como funciona: Ao processar uma tarefa, o Copilot encontra todos os *.instructions.md cujos applyTo correspondem ao contexto atual (arquivos que você está discutindo/editando). As regras aplicáveis são adicionadas às globais.

Exemplo:

1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: componentes de função e hooks
5- Estado: Zustand; busca de dados com TanStack Query
6- Estilo: Tailwind CSS; evite estilos inline, exceto em casos dinâmicos
7- Testes: Vitest + Testing Library; evite snapshots instáveis

Observação.

1. Evite duplicar regras globais já existentes.
2. Certifique-se de que o glob realmente aponta para os caminhos corretos.

3.3. Modos de Chat — .github/chatmodes/*.chatmode.md

O que é: Arquivos de configuração que definem o modo de operação do agente para o diálogo: uma descrição curta, modelo (se necessário) e uma lista de ferramentas permitidas.

Por quê: Para separar fases de trabalho (planejamento/frontend/DBA/segurança) e limitar as ferramentas em cada etapa. Isso torna os resultados mais previsíveis.

Estrutura do arquivo:

1---
2description: "Planejar - analisar código/especificações e propor um plano; ferramentas somente leitura"
3model: GPT-4o
4tools:[ "search/codebase"]
5---
6Neste modo:
7- Produza um plano estruturado com riscos e desconhecidos
8- Não edite arquivos; em vez disso, gere uma lista concisa de tarefas

Como funciona:

• O modo de chat é aplicado ao chat atual na IDE.
• Se você ativar um arquivo de prompt, seu frontmatter tem prioridade sobre o modo de chat (pode alterar o modelo e restringir as tools).
• A lista efetiva de ferramentas permitidas: ferramentas do modo de chat, restritas pelas ferramentas do prompt e pelos flags da CLI --allow/--deny.

Gerenciamento e Troca:

• Na IDE (VS Code):

1. Abra o painel Copilot Chat.
2. Na linha superior, selecione o modo de chat desejado na lista suspensa (a lista é construída a partir de .github/chatmodes/*.chatmode.md + modos embutidos).
3. O modo é aplicado apenas a este branch de diálogo. Para trocar — selecione outro ou crie um novo branch com o modo desejado.
4. Verifique o modo ativo no cabeçalho/painel de conversas; em Referências você verá o arquivo *.chatmode.md.

• Na CLI: (um pouco hacky, melhor via prompts)

  • Geralmente não há um flag CLI especial para trocar de modo; codifique as restrições desejadas no frontmatter do arquivo de prompt e/ou através dos flags --allow-tool/--deny-tool.
  • Você pode indicar na primeira linha: «Use o modo de chat i18n.» — se a versão suportar, o agente pode trocar; se não, o frontmatter do prompt ainda aplicará as restrições de ferramentas.

• Sem trocar de modo: execute um prompt com as tools: desejadas no frontmatter — isso restringirá as ferramentas independentemente do modo de chat.

Diagnóstico: se o agente usar ferramentas "extras" ou não enxergar as necessárias — verifique: (1) qual modo de chat está selecionado; (2) tools no frontmatter do prompt; (3) flags CLI --allow/--deny; (4) Referências na resposta (arquivos *.chatmode.md/*.prompt.md visíveis).

3.4. Arquivos de Prompt — .github/prompts/*.prompt.md

O que é: Arquivos de cenário para tarefas reutilizáveis. Consistem em frontmatter YAML (configuração) e corpo (instruções/etapas/critérios de aceitação). São chamados no chat via /nome ou via CLI.

Quando usar: Quando um processo previsível e automatizável é necessário: revisão de PR, geração de testes, implementação de uma função conforme especificação, etc.

Estrutura do Frontmatter

• description — objetivo curto do cenário.
• mode — ask (Q&A, sem edição de arquivos) · edit (edição local de arquivos abertos) · agent (processo multi-etapas com ferramentas).
• model — perfil de modelo desejado.
• tools — lista de ferramentas permitidas para o cenário (restringe até o que o modo de chat permitiu).

Algoritmo de Execução (sequência)

1. Onde executar:

• No chat: digite /nome-do-prompt e os argumentos no campo de mensagem.
• Na CLI: chame copilot e passe a string /nome-do-prompt … (interativamente ou via heredoc / flag -p).

2. Coleta de Contexto: O Copilot constrói o contexto de execução na seguinte ordem: instruções-repo → instruções-caminho (applyTo) → modo-chat → frontmatter-prompt (o frontmatter do prompt tem a prioridade mais alta e pode restringir ferramentas/alterar o modelo).

3. Análise de Parâmetros (onde e como):

   • No chat: os parâmetros vêm na mesma mensagem após o nome, por exemplo: /revisao-seguranca numeroPr=123 alvo=apps/web.
   • Na CLI: os parâmetros vêm na mesma linha /… no stdin ou após o flag -p.
   • Dentro do arquivo de prompt, eles estão disponíveis como ${input:nome}. Se um parâmetro obrigatório estiver faltando, o prompt pode solicitá-lo por texto no diálogo.

4. Resolução de Permissões de Ferramentas:

• Lista efetiva de ferramentas permitidas: ferramentas do modo de chat, restritas pelas ferramentas do prompt e pelos flags CLI --allow/--deny.
• Se uma ferramenta for proibida, a etapa correspondente é ignorada ou requer confirmação / alteração de política.

5. Execução de Etapas do Corpo do Prompt: o agente segue estritamente a ordem das etapas, executando apenas o que é permitido pelas políticas/ferramentas (busca na base de código, geração de diff, execução de testes, etc.). Para ações potencialmente arriscadas, ele solicita confirmação.

6. Portões de Validação: no final, o prompt executa verificações (build/tests/lint/typecheck). Se uma verificação falhar — o agente retorna uma lista de problemas e propõe próximos passos (sem mesclagem automática/salvamento de alterações).

7. Onde o Resultado Aparece (o que e onde é visível):

• Resposta Principal — no painel de chat (IDE) ou no stdout (CLI): tabelas, listas, relatórios de texto, blocos de código com diff.
• Alterações de Arquivos — em sua árvore de trabalho: na IDE, diff/patches sugeridos são visíveis; na CLI, os arquivos são alterados localmente (se permitido pelas ferramentas).
• Artefatos Adicionais — por exemplo, um comentário para o PR, se as ferramentas do GitHub forem permitidas e o prompt indicar isso.

Formato de Saída e Verificações (recomendações)

• Sempre especifique o formato de saída (por exemplo, tabela "issue | file | line | severity | fix").
• Adicione portões de validação: build/tests/lint/typecheck; exija unified-diff para alterações propostas; lista de TODOs para questões não resolvidas.

Exemplo de Arquivo de Prompt Completo

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implementar um recurso a partir de uma especificação'
6---
7Objetivo: Implementar o recurso descrito em @docs/feature.spec.md.
8
9Etapas:
101) Ler @docs/feature.spec.md e produzir um breve plano de implementação (tópicos)
112) Listar arquivos a serem adicionados/modificados com caminhos
123) Propor patches de código como diff unificado; perguntar antes de instalar novas dependências
134) Gerar testes mínimos e executá-los (reportar resultados)
14
15Portões de Validação:
16- Build, testes, lint/typecheck devem passar
17- A saída inclui o diff final e uma lista de TODOs para qualquer coisa adiada
18- Se qualquer portão falhar, retorne um plano de remediação em vez de "concluído"

Antipadrões

• Descrições vagas: mantenha o description em 1–2 linhas.
• Falta de formato de saída.
• Muitas ferramentas: permita apenas as necessárias (tools).

Início Rápido

• Chat: /implement-from-spec
• CLI: copilot <<<'/implement-from-spec' ou copilot -p "Executar /implement-from-spec"

3.5. Arquivos de Contexto — specs/context/memory

O que é: Arquivos Markdown auxiliares (não tipos especiais) que você menciona via @ no diálogo/prompt. Geralmente armazenados como documentação.

• docs/*.spec.md — definições exatas de tarefas (objetivo, critérios de aceitação, casos extremos, não-objetivos).
• docs/*.context.md — referências curtas (políticas de API, segurança, guia de estilo de UI, SLA).
• docs/*.memory.md — "log de decisões" com datas e justificativas, para que o agente não volte a questões há muito resolvidas.

Exemplo:

1# Recurso: Exportar relatório para CSV
2Objetivo: Os usuários podem exportar a tabela filtrada para CSV.
3Critérios de Aceitação:
4- Botão "Exportar CSV" em /relatórios
5- Servidor gera arquivo ≤ 5s para 10.000 linhas
6- Ordem/cabeçalhos das colunas correspondem à UI; valores independentes de localidade
7Casos Extremos: valores vazios, números grandes, caracteres especiais
8Não-Objetivos: XLSX, filtros simultâneos de múltiplas colunas

3.6. MCP — .vscode/mcp.json

O que é: Configuração de servidores do Model Context Protocol (por exemplo, GitHub MCP), que fornecem ferramentas ao agente.

Por quê: Para que o agente possa ler PRs/issues, executar testes, interagir com banco de dados/navegador — dentro das permissões permitidas.

Exemplo:

1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Segurança. Conecte apenas servidores confiáveis; use listas de allow/deny de ferramentas em prompts/modos de chat/CLI.

3.7. Ordem Geral de Combinação de Contexto e Prioridades (Regras & Ferramentas)

1. Instruções: copilot-instructions + todos os *.instructions.md com applyTo que correspondem aos caminhos atuais. A instrução específica é adicionada ao contexto geral.
2. Modo de Chat: restringe o conjunto de ferramentas e (se necessário) o modelo para a sessão.
3. Frontmatter do Prompt: tem a prioridade mais alta; pode restringir ferramentas e substituir o modelo.
4. Contexto: tudo o que você menciona via @, é garantidamente levado em consideração pelo modelo.

Diagnóstico. Verifique a seção Referências nas saídas — ela indica quais arquivos de instrução foram levados em consideração e qual prompt foi executado.

3.8. Exemplo: Ciclo i18n Completo com Goman MCP (Criação/Atualização/Exclusão)

Abaixo está o processo exato e os modelos para garantir o seguinte: (a) ao criar componentes de UI, as chaves de localização são criadas/atualizadas no Goman; (b) ao excluir componentes, as entradas não utilizadas são detectadas e (após confirmação) excluídas.

Fragmentos de código e frontmatter — em inglês.

3.8.1. Configuração do MCP — Conectando Goman

/.vscode/mcp.json

1{
2  "servers": {
3    "goman-mcp": {
4      "type": "http",
5      "url": "https://mcp.goman.live/mcp",
6      "headers": {
7        "apiKey": "<SUA_CHAVE_API>",
8        "applicationid": "<SEU_ID_APLICATIVO>"
9      }
10    }
11  }
12}

3.8.2. Regras Repo/Caminho — Impondo i18n por padrão

/.github/instructions/frontend.instructions.md (adendo)

1---
2applyTo: "apps/web/**/*.{ts,tsx}"
3---
4- Todas as strings voltadas para o usuário **devem** usar chaves i18n (sem texto codificado em JSX/TSX)
5- Nomenclatura de chaves: `<area_do_componente_ui>.<n>` (por exemplo, `ui_button_primary.label`)
6- Ao criar componentes, execute `/i18n-component-scaffold` e comite tanto o código quanto as chaves criadas
7- Ao excluir componentes, execute `/i18n-prune` e confirme a remoção de chaves não utilizadas

3.8.3. Modo de Chat — Ferramentas i18n Restritas

/.github/chatmodes/i18n.chatmode.md

1---
2description: "i18n - gerenciar chaves de localização via Goman MCP; impor ausência de strings codificadas"
3model: GPT-4o
4tools:
5  - "files"
6  - "goman-mcp:*"
7---
8Neste modo, prefira:
9- Criar/atualizar chaves no Goman antes de escrever código
10- Verificar chaves existentes e reutilizá-las
11- Gerar uma tabela de alterações (criadas/atualizadas/ignoradas)

3.8.4. Prompt — Scaffolding de componente + chaves no Goman

/.github/prompts/i18n-component-scaffold.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Scaffold de um componente React com chaves i18n sincronizadas com Goman'
6---
7Entradas: nomeDoComponente, namespace (por exemplo, `ui.button`), caminho (por exemplo, `apps/web/src/components`)
8
9Objetivo: Criar um componente React e garantir que todas as strings visíveis ao usuário usem chaves i18n armazenadas no Goman.
10
11Etapas:
121) Planejar a estrutura do componente e listar todas as strings visíveis ao usuário
132) Para cada string, propor uma chave sob `${namespace}`; reutilizar se existir
143) Usando Goman MCP, criar/atualizar traduções para os idiomas: en, be, ru (os valores podem ser placeholders)
154) Gerar o componente usando `t('<chave>')` e exportá-lo; adicionar um teste básico
165) Gerar uma tabela Markdown: chave | en | be | ru | ação(criado/atualizado/reutilizado)
17
18Portões de Validação:
19- Nenhum literal codificado no .tsx produzido
20- Confirmar que as ações do Goman foram bem-sucedidas (relatar respostas da ferramenta)
21- Testes e verificação de tipo passam

Exemplo de código do componente:

1import { t } from '@/i18n';
2import React from 'react';
3
4type Props = { onClick?: () => void };
5
6export function PrimaryButton({ onClick }: Props) {
7  return (
8    <button aria-label={t('ui.button.primary.aria')} onClick={onClick}>
9      {t('ui.button.primary.label')}
10    </button>
11  );
12}

3.8.5. Prompt — Exclusão de chaves não utilizadas ao excluir componentes

/.github/prompts/i18n-prune.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Encontrar e remover chaves de localização não utilizadas no Goman após exclusões de código'
6---
7Entradas: caminhoOuDiff (por exemplo, um caminho de componente excluído ou um número de PR)
8
9Objetivo: Detectar chaves que não são mais referenciadas na base de código e removê-las do Goman após confirmação.
10
11Etapas:
121) Computar o conjunto de elementos de UI removidos/renomeados (escanear diff git ou caminhos fornecidos)
132) Inferir chaves candidatas por namespace (por exemplo, `ui.<componente>.*`) e verificar referências de código
143) Para chaves com **zero** referências, solicitar confirmação e excluí-las via Goman MCP
154) Gerar uma tabela Markdown: chave | status(mantido/excluído) | motivo | notas
16
17Portões de Validação:
18- Nunca excluir chaves que ainda tenham referências
19- Exigir confirmação explícita antes da exclusão
20- Fornecer uma lista de reversão das chaves excluídas

3.8.6. Prompt — Sincronização e Verificação de Traduções Ausentes (Opcional)

/.github/prompts/i18n-sync.prompt.md

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Sincronizar chaves i18n novas/alteradas e verificar traduções ausentes'
6---
7Objetivo: Comparar referências de código vs Goman e preencher lacunas.
8
9Etapas:
101) Escanear código em busca de chaves `t('...')` sob os namespaces fornecidos
112) Para chaves ausentes no Goman — criá-las (placeholder ok)
123) Para idiomas ausentes — criar placeholders e reportar cobertura
134) Gerar tabela de cobertura: chave | en | be | de | ausente

4) Como Usar (IDE e CLI)

4.1. No VS Code / Outra IDE

• Abra o Copilot Chat — selecione Agent/Edit/Ask na lista suspensa.
• Para arquivos de prompt, simplesmente digite /nome-do-arquivo sem extensão (por exemplo, /revisao-seguranca).
• Adicione contexto via menções com @ de arquivos e diretórios.
• Troque o modo de chat (Planejar/Frontend/DBA) ao mudar o tipo de tarefa.

4.2. No Copilot CLI (terminal)

• Exemplo de instalação: npm install -g @github/copilot → execute copilot.
• Interativamente: «Execute /implement-from-spec em @docs/feature.spec.md».
• Programaticamente / em CI: copilot -p "Implementar recurso de @docs/feature.spec.md" --deny-tool shell("rm*").
• Adicione / restrinja ferramentas via flags: --allow-all-tools, --allow-tool, --deny-tool (globalmente ou por padrão, por exemplo shell(npm run test:*)).

4.3. Receitas de Comandos para CLI (Modos de Chat e Prompts)

Abaixo estão receitas prontas. Todos os comandos devem ser executados a partir da raiz do repositório e respeitar suas listas deny/allow.

A. Execução de Arquivo de Prompt em Sessão Interativa

1copilot
2# dentro da sessão (digite a linha como está)
3/revisao-seguranca numeroPr=123

B. Execução de Arquivo de Prompt em Modo Não Interativo (heredoc)

1copilot <<'EOF'
2/revisao-seguranca numeroPr=123
3EOF

C. Passando Parâmetros para Arquivo de Prompt

1copilot <<'EOF'
2/implement-from-spec caminho=@docs/feature.spec.md alvo=apps/web
3EOF

Dentro do prompt, os valores podem ser lidos como ${input:alvo} e ${input:caminho}.

D. Execução de Prompt com Permissões Seguras para Ferramentas

1copilot --allow-tool "shell(npm run test:*)" \
2        --deny-tool  "shell(rm*)" \
3        <<'EOF'
4/revisao-seguranca numeroPr=123
5EOF

E. Uso de Modo de Chat (Modo Especializado) na CLI

1copilot
2# dentro da sessão — peça para trocar para o modo desejado e executar o prompt
3Use o modo de chat i18n.
4/i18n-component-scaffold nomeDoComponente=PrimaryButton namespace=ui.button caminho=apps/web/src/components

Se seu cliente suportar a seleção de modo via menu — selecione i18n antes de executar o prompt. Se não — especifique as restrições no frontmatter do prompt (tools e regras no corpo do prompt).

F. Passando Links de Arquivos/Diff como Contexto

1copilot <<'EOF'
2Por favor, revise estas alterações:
3@apps/web/src/components/PrimaryButton.tsx
4@docs/feature.spec.md
5/revisao-seguranca numeroPr=123
6EOF

G. Alterando o Modelo para uma Execução Específica

Recomendamos especificar o modelo no frontmatter do prompt. Se suportado, você também pode passar o flag do modelo durante a execução:

1copilot --model GPT-4o <<'EOF'
2/implement-from-spec
3EOF

H. Ciclo i18n com Goman MCP (CHAT)

Execute em sequência no mesmo branch de chat:

1/i18n-component-scaffold nomeDoComponente=PrimaryButton namespace=ui.button caminho=apps/web/src/components
2/i18n-prune caminhoOuDiff=@ultimo-diff
3/i18n-sync namespace=ui.button

O que você obtém:

• tabelas/relatórios finais no painel de chat;
• alterações de código em sua árvore de trabalho (a IDE mostra diff);
• não é necessário executar comandos CLI para Goman MCP aqui.

5) Engenharia de Contexto: como não "inundar" com contexto desnecessário

1. Separe as sessões por fases: Planejamento → Implementação → Revisão/Testes. Cada fase tem seu Modo de Chat.
2. Anexe apenas as instruções necessárias: use *.instructions.md específicas de caminho em vez de carregar tudo.
3. Memória do Projeto: anote ADRs curtos em project.memory.md — isso reduz o "esquecimento" do agente entre tarefas.
4. Auxiliares de Contexto: referências frequentes (API/segurança/UI) armazene em *.context.md e referencie-as em arquivos de prompt.
5. Foco na Tarefa: em arquivos de prompt, sempre especifique o objetivo, etapas e formato de saída (tabela, diff, checklist).

6) Segurança e Gerenciamento de Ferramentas

• Exija confirmação explícita antes de executar comandos/ferramentas. Em CI, use --deny-tool por padrão e adicione listas de allow locais.
• Padrões de Permissões: permita apenas o necessário (shell(npm run test:*), playwright:*), negue padrões perigosos (shell(rm*)).
• Segredos: não coloque chaves em prompts e instruções; use Ambientes do GitHub ou gerenciadores de segredos locais e .env com .gitignore.
• Qualquer MCP — apenas de fontes confiáveis; verifique o código/configuração antes de conectar.
• Verificação de Patches: exija unified-diff e explicações em arquivos de prompt — isso simplifica a revisão.

7) Receita de CI/CD (exemplo opcional)

Certifique-se de que "tudo compila": execute o Copilot CLI em modo seguro para gerar um comentário no PR.

1# .github/workflows/ai-review.yml
2name: AI Review (Copilot CLI)
3on:
4  pull_request:
5    types: [opened, synchronize, reopened]
6
7jobs:
8  ai_review:
9    runs-on: ubuntu-latest
10    permissions:
11      contents: read
12      pull-requests: write
13    steps:
14      - uses: actions/checkout@v4
15      - uses: actions/setup-node@v4
16        with:
17          node-version: 22
18      - name: Instalar Copilot CLI
19        run: npm install -g @github/copilot
20      - name: Executar prompt de revisão de segurança (sem ferramentas perigosas)
21        env:
22          PR: ${{ github.event.pull_request.number }}
23        run: |
24          copilot -p "Executar /revisao-seguranca com numeroPr=${PR}" \
25            --deny-tool shell("rm*") --deny-tool shell("curl*") \
26            --allow-tool shell("npm run test:*") \
27            --allow-tool "github:*" \
28            > ai-review.txt || true
29      - name: Comentar PR com resultados
30        if: always()
31        run: |
32          gh pr comment ${{ github.event.pull_request.number }} --body-file ai-review.txt

Dica: mantenha listas deny/allow rigorosas; não dê "liberdade total" ao agente em CI.

8) Pequenos Cenários e Dicas Úteis

• Da ideia ao PR: /plan — discutir plano — /implement-from-spec → testes locais — PR — /security-review.
• Manutenção: /refactor-slice para melhorias locais sem alterar o comportamento.
• Testes: /test-gen para novos módulos + adições manuais para casos extremos.
• Introdução gradual: comece com 1–2 arquivos de prompt e um modo de chat; expanda depois.

9) Verificações de Qualidade (Portões de Validação)

Em cada arquivo de prompt, registre "o que é considerado pronto":

• Formato de Saída: tabela de riscos, unified-diff, checklist.
• Verificações Automáticas: build, testes unitários/de integração, lint/typecheck.
• Verificação Manual: "OK para mesclar?" com justificativa e riscos residuais.

10) Antipadrões e Hacks

• Antipadrão: um único instructions.md enorme. Prefira vários *.instructions.md com applyTo.
• Antipadrão: palavras genéricas em vez de regras. Prefira comandos/etapas concretas.
• Antipadrão: executar comandos shell perigosos sem verificação. Use deny/allow e confirmação manual.
• Antipadrão: especificações/memória esquecidas. Mantenha feature.spec.md e project.memory.md.
• Antipadrão: misturar tarefas em uma única sessão. Crie um Modo de Chat para cada fase.

11) Checklist de Implementação

1. Adicione .github/copilot-instructions.md (pelo menos 5–8 pontos sobre build/tests/style).
2. Crie 1–2 *.instructions.md com applyTo (frontend/backend ou workflows).
3. Adicione plan.chatmode.md e um prompt (por exemplo, implement-from-spec.prompt.md).
4. Crie docs/feature.spec.md e docs/project.memory.md.
5. Conecte o MCP (pelo menos GitHub MCP) via .vscode/mcp.json.
6. Execute o fluxo de trabalho no VS Code: /implement-from-spec — verifique — PR.
7. (Opcional) Adicione uma revisão simples de IA em CI via Copilot CLI com listas deny/allow rigorosas.

12) Perguntas e Respostas (FAQ)

P: Como garantir que o Copilot "veja" minhas instruções? R: Verifique o sumário/Referências na resposta; também mantenha as regras curtas e específicas.

P: É possível passar parâmetros dinamicamente para arquivos de prompt? R: Sim, geralmente através de variáveis de substituição (como ${prNumber}) ou simplesmente por uma solicitação de texto ao executar /prompt no chat.

P: Onde armazenar segredos para MCP? R: Em Ambientes do GitHub ou gerenciadores de segredos locais; não em .prompt.md/.instructions.md.

P: O que escolher: Modo de Chat ou Arquivo de Prompt? R: O Modo de Chat define a "moldura" (modelo/ferramentas/papel). O Arquivo de Prompt é o "cenário" dentro dessa moldura.

13) Próximos Passos

• Adicione um segundo prompt para seu processo manual mais frequente.
• Torne project.memory.md obrigatório após todas as decisões arquiteturais.
• Mova gradualmente o conhecimento coletivo para *.context.md e referencie-os em arquivos de prompt.

Apêndice A — Modelos de Início Rápido

Todas as chaves, caminhos e flags correspondem à documentação (28 de outubro de 2025).

/.github/copilot-instructions.md — regras para todo o repositório

1# Padrões de codificação do repositório
2- Compilar: `npm ci && npm run build`
3- Testes: `npm run test` (cobertura ≥ 80%)
4- Lint/Verificação de Tipo: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; mantenha os PRs pequenos e focados
6- Docs: atualize `CHANGELOG.md` em cada PR de release

/.github/instructions/frontend.instructions.md — instruções para caminhos específicos

1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: componentes de função e hooks
5- Estado: Zustand; busca de dados com TanStack Query
6- Estilo: Tailwind CSS; evite estilos inline, exceto em casos dinâmicos
7- Testes: Vitest + Testing Library; evite snapshots instáveis

/.github/instructions/backend.instructions.md — instruções para caminhos específicos

1---
2applyTo: "services/api/**/*.{ts,js},packages/server/**/*.{ts,js}"
3---
4- HTTP: Fastify; APIs versionadas sob `/v{N}`
5- Acesso a DB: Prisma; migrações via `prisma migrate`
6- Segurança: validação de schema (Zod), limites de taxa, logs de auditoria
7- Testes: testes de integração via `vitest --config vitest.integration.ts`

/.github/instructions/actions.instructions.md — GitHub Actions

1---
2applyTo: ".github/workflows/**/*.yml"
3---
4- Mantenha os jobs pequenos; reutilize via ações compostas
5- Cache: `actions/setup-node` + cache embutido para npm/pnpm
6- Segredos: apenas via Ambientes do GitHub; nunca codificados

/.github/chatmodes/plan.chatmode.md — modo de chat personalizado

1---
2description: "Planejar - analisar código/especificações e propor um plano; ferramentas somente leitura"
3model: GPT-4o
4tools:
5  - "search/codebase"
6---
7Neste modo:
8- Produza um plano estruturado com riscos e desconhecidos
9- Não edite arquivos; em vez disso, gere uma lista concisa de tarefas

/.github/prompts/security-review.prompt.md — arquivo de prompt

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Realizar uma revisão de segurança de um pull request'
6---
7Objetivo: Revisar o PR ${input:prNumber} para problemas comuns de segurança.
8
9Checklist:
10- Cobertura de autenticação/autorização
11- Validação de entrada e codificação de saída (XSS/SQLi)
12- Gerenciamento e configuração de segredos
13- Versões de dependências e CVEs conhecidas
14
15Saída:
16- Uma tabela Markdown: issue | file | line | severity | fix
17- Se trivial, inclua uma sugestão de diff unificado

/.github/prompts/implement-from-spec.prompt.md — arquivo de prompt

1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implementar um recurso a partir de uma especificação'
6---
7Sua tarefa é implementar o recurso descrito em @docs/feature.spec.md.
8
9Etapas:
101) Ler @docs/feature.spec.md e resumir o plano
112) Listar arquivos a adicionar ou modificar
123) Propor alterações de código; perguntar antes de instalar novas dependências
134) Gerar testes mínimos e executá-los
14
15Portões de Validação:
16- Build, testes, lint/typecheck devem passar
17- Forneça uma lista TODO para qualquer coisa adiada

/.github/prompts/refactor-slice.prompt.md — arquivo de prompt

1---
2mode: 'agent'
3model: GPT-4o
4description: 'Refatorar uma fatia de código específica sem alterar o comportamento'
5---
6Objetivo: Melhorar a legibilidade e reduzir efeitos colaterais em @src/feature/* mantendo o comportamento inalterado. Critérios: menos efeitos colaterais, estrutura mais clara, todos os testes passam.

/.github/prompts/test-gen.prompt.md — arquivo de prompt

1---
2mode: 'agent'
3model: GPT-4o-mini
4description: 'Gerar testes para um determinado arquivo/módulo'
5---
6Peça ao usuário para @-mencionar o arquivo alvo; gerar testes unitários/de integração e casos extremos.

/docs/feature.spec.md — modelo de especificação

1# Recurso: Exportar relatório para CSV
2Objetivo: Os usuários podem exportar a tabela filtrada para CSV.
3Critérios de Aceitação:
4- Botão "Exportar CSV" em /relatórios
5- Servidor gera arquivo ≤ 5s para 10.000 linhas
6- Ordem/cabeçalhos das colunas correspondem à UI; valores independentes de localidade
7Casos Extremos: valores vazios, números grandes, caracteres especiais
8Não-Objetivos: XLSX, filtros simultâneos de múltiplas colunas

/.vscode/mcp.json — configuração mínima de MCP

1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Apêndice B — Complementos Operacionais (Exemplos CLI & CI)

Estes exemplos complementam o Apêndice A; eles descrevem o uso em execução / automação e não duplicam os modelos acima.

Copilot CLI — Permissões Seguras para Ferramentas (Interativo / CI)

1# Iniciar uma sessão interativa em seu repositório
2copilot
3
4# Permitir/negar ferramentas específicas (flags exatos conforme documentação do GitHub)
5copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)"
6
7# Executar um arquivo de prompt em modo não interativo (exemplo)
8copilot <<'EOF'
9/revisao-seguranca numeroPr=123
10EOF

GitHub Actions — Comentando Resultados da Revisão em PR

1name: AI Security Review (Copilot CLI)
2on:
3  pull_request:
4    types: [opened, synchronize, reopened]
5
6jobs:
7  review:
8    runs-on: ubuntu-latest
9    permissions:
10      contents: read
11      pull-requests: write
12    steps:
13      - uses: actions/checkout@v4
14      - uses: actions/setup-node@v4
15        with:
16          node-version: 22
17      - name: Instalar Copilot CLI
18        run: npm install -g @github/copilot
19      - name: Executar prompt de revisão de segurança
20        env:
21          PR: ${{ github.event.pull_request.number }}
22        run: |
23          copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)" <<'EOF'
24          /revisao-seguranca numeroPr=${PR}
25          EOF
26      - name: Postar resultados
27        run: |
28          gh pr comment ${{ github.event.pull_request.number }} --body "Revisão Copilot concluída. Verifique os artefatos/logs para detalhes."

14) Configurando Contexto em um Projeto Existente

Esta seção resolve uma tarefa específica: você pega um projeto já em funcionamento e, em uma única abordagem, cria contexto e instruções completas para o GitHub Copilot. Nada é inventado — tudo é retirado do que já existe no código.

Cada etapa é um prompt executado no VS Code no modo Agente. Cada etapa subsequente depende do resultado da anterior, portanto, a ordem é importante.

14.1. Etapa 1 — Auditoria do Projeto

Objetivo: Obter um mapa objetivo do projeto. Sem isso, todo o resto é adivinhação.

O que fazer: abrir o Copilot Chat, selecionar o modo Agente, anexar a pasta raiz via @, e executar:

1@/
2
3Analise a estrutura deste projeto. Defina:
4
5- stack: linguagem, frameworks, gerenciador de pacotes
6- comandos de build, teste, lint (exatos, de package.json / pom.xml / Makefile, etc.)
7- fluxos de trabalho de CI existentes (.github/workflows) — o que é executado lá
8- pastas principais e seu propósito
9- configurações existentes: lint, prettier, typescript, e similares
10
11Retorne o resultado como uma lista estruturada.
12Não adivinhe — apenas o que é realmente visível nos arquivos.

Resultado: salve a resposta — ela será necessária na Etapa 2. Este é o "mapa inicial", a qualidade de tudo o mais depende dele.

14.2. Etapa 2 — Gerando Instruções Globais

Objetivo: Criar .github/copilot-instructions.md — uma fonte única de regras para todo o repositório.

O que fazer: pegar o resultado da Etapa 1 e executar:

1Com base nesta auditoria do projeto:
2
3[cole o resultado da Etapa 1 aqui]
4
5Crie o arquivo .github/copilot-instructions.md
6
7Requisitos:
8- apenas fatos da auditoria, nada inventado
9- comandos de build, teste, lint — exatos, copiados das configurações
10- estilo de código — apenas se houver um config prettier/eslint, e apenas o que está registrado lá
11- política de commit — apenas se houver commitlint ou similar
12- no máximo 8–12 itens
13- cada item — uma única linha específica

Resultado: o arquivo .github/copilot-instructions.md é criado e registrado na árvore de trabalho.

14.3. Etapa 3 — Gerando Instruções Específicas de Caminho

Objetivo: Criar regras separadas para diferentes áreas do código, que são anexadas automaticamente por padrão de caminho.

Quando necessário: se o projeto tiver pelo menos duas áreas logicamente separadas — frontend e backend, apps e packages, vários serviços. Se o projeto for homogêneo — pule esta etapa.

O que fazer: para cada área, anexe a pasta correspondente e execute um prompt separado. Exemplo para frontend:

1@src/components/
2@src/pages/
3
4Analise esta parte do projeto e defina:
5
6- qual framework e como os componentes são escritos
7- padrões de gerenciamento de estado (se visíveis)
8- como os testes são organizados (se houver)
9- estilo de importações e nomes de arquivos
10
11Crie o arquivo .github/instructions/frontend.instructions.md
12
13Requisitos:
14- applyTo — um glob exato que cobre apenas estas pastas
15- regras — apenas com base no que você vê no código
16- não duplica o que já está em copilot-instructions.md
17- não mais que 6–8 itens

Um prompt semelhante para backend, se existir, com as pastas correspondentes em @.

Resultado: arquivos em .github/instructions/ para cada área.

14.4. Etapa 4 — Gerando Referência do Projeto

Objetivo: Criar docs/project.context.md — uma referência estável que reduz o "ruído" nos chats e não requer atualização a cada alteração.

O que fazer:

1@/
2@README.md
3@package.json
4
5Crie o arquivo docs/project.context.md —
6esta é uma referência do projeto para o assistente de IA.
7
8Inclua:
9- breve descrição: o que o projeto faz, para quem
10- padrões arquiteturais chave, se visíveis na estrutura de pastas e importações
11- dependências externas e seus papéis (por que essas em particular, se o contexto for claro)
12- o que NÃO fazer: pastas deprecated, padrões confusos, limitações conhecidas
13
14Restrições:
15- no máximo 30–40 linhas
16- apenas o que é objetivamente visível no projeto
17- sem suposições ou recomendações

Resultado: o arquivo docs/project.context.md.

14.5. Etapa 5 — Gerando Memória do Projeto

Objetivo: Registrar as decisões que já foram tomadas, para que o agente não volte a elas.

O que fazer:

1@/
2
3Analise o projeto e encontre decisões que já foram registradas no código:
4
5- escolha de bibliotecas — se alternativas óbvias são visíveis em arquivos de lock ou comentários
6- estrutura de pastas — se for não padrão para este stack
7- quaisquer TODO ou FIXME que tenham contexto sobre o porquê
8- configurações que tenham comentários com justificativa
9
10Crie o arquivo docs/project.memory.md no formato:
11
12## [data ou "desconhecido"] | Decisão | Por quê
13
14Cada entrada — no máximo 2 linhas.
15Não mais que 10–12 entradas.
16Apenas o que é realmente visível.

Resultado: o arquivo docs/project.memory.md.

14.6. Etapa 6 — Primeiro Arquivo de Prompt

Objetivo: Criar um prompt de trabalho para a tarefa mais frequente. Não é necessário criar todos os cinco dos modelos imediatamente — comece com um e adicione conforme necessário.

Quando qual prompt: se a equipe implementa novas features com mais frequência — use implement-from-spec. Se revisa PRs com mais frequência — use security-review. Escolha o que é usado diariamente.

O que fazer (exemplo para implement-from-spec):

1@.github/copilot-instructions.md
2
3Crie o arquivo .github/prompts/implement-from-spec.prompt.md
4para este projeto.
5
6Requisitos:
7- mode: agent
8- tools: apenas search/codebase
9- as etapas devem usar os comandos de build e teste
10  de copilot-instructions.md
11- validation gates: build, testes, lint devem passar
12- description — uma linha

Resultado: o arquivo .github/prompts/implement-from-spec.prompt.md, adaptado ao stack específico do projeto.

14.7. Resultado e Próximos Passos

Após estas seis etapas, o repositório terá:

1.github/
2  copilot-instructions.md          ← regras globais (passo 2)
3  instructions/
4    frontend.instructions.md       ← regras para frontend (passo 3)
5    backend.instructions.md        ← regras para backend (passo 3)
6  prompts/
7    implement-from-spec.prompt.md  ← primeiro prompt (passo 6)
8docs/
9  project.context.md               ← referência do projeto (passo 4)
10  project.memory.md                ← memória de decisões (passo 5)

Este é um conjunto mínimo funcional. Em seguida — iterativamente:

• adicione arquivos de prompt à medida que novas tarefas típicas surgirem
• atualize project.memory.md após cada decisão arquitetural
• adicione modos de chat quando começar a notar que diferentes fases de trabalho se atrapalham
• conecte MCP apenas depois que o contexto base estiver funcionando

Tudo o que foi descrito acima se encaixa em uma única sessão de trabalho. Cada prompt pode ser executado em sequência, sem trocar de arquivos manualmente — o agente criará os arquivos na árvore de trabalho.

Fontes

Modos de Chat Personalizados no VS Code

Uso de Servidores MCP no VS Code

Adicionando Instruções Personalizadas de Repositório para GitHub Copilot

Como Criar Fluxos de Trabalho de IA Confiáveis com Primitivas de Agente e Engenharia de Contexto

🙌 PS:

Obrigado por ler até o final! Se o material foi útil, ficaremos felizes se você:

As tecnologias se tornam mais acessíveis quando são compreendidas. E você já deu o primeiro passo importante 💪