Práticas recomendadas para a modernização do GitHub Copilot

Siga estas diretrizes para obter os melhores resultados de GitHub Copilot modernização ao atualizar e migrar projetos .NET.

Antes de começar

Prepare seus projetos antes de iniciar uma atualização para obter os melhores resultados.

Verifique se os builds e testes da solução são aprovados

O agente valida as alterações feitas executando builds e testes. Se sua solução já estiver quebrada antes de você começar, o agente não poderá distinguir as falhas pré-existentes dos problemas que introduziu.

Documente quaisquer falhas de teste conhecidas para scenario-instructions.md que o agente saiba ignorá-las.

Confirmar ou esconder trabalho não confirmado

Comece com um diretório de trabalho vazio para evitar misturar as alterações não realizadas com as modificações do agente. Uma linha de base limpa facilita a revisão ou a reversão de alterações.

git stash
git status

Fazer backup de repositórios não Git

O agente também funciona com pastas que não estão sob controle do código-fonte. Se o projeto não estiver em um repositório Git, o agente ignorará as operações de branch e commit. Nesse caso, faça backup da pasta do projeto antes de começar para que você possa restaurá-la, se necessário.

Considere inicializar um repositório Git local antes de iniciar a atualização, mesmo se você não enviar por push para um provedor de nuvem. Um repositório Git local permite que você:

Reverter alterações individuais com git revert.
Acompanhe o progresso da atualização passo a passo no histórico de confirmação.
Controlar quais alterações manter ou descartar.
Mantenha seu código original seguro no ramo principal enquanto o agente trabalha em um ramo separado.

cd your-project-folder
git init
git add .
git commit -m "Baseline before upgrade"

Examinar a cobertura do teste

O agente depende de testes para validar que suas alterações não interrompem o comportamento. Projetos com boa cobertura de teste recebem atualizações de confiança mais alta.

Dica

Você não precisa de 100% cobertura. Concentre-se no código que a atualização provavelmente mudará, como limites de API, serialização, acesso ao banco de dados e autenticação.

Comece pequeno

Se esta for a primeira vez que você usa o agente, escolha um projeto pequeno e de baixo risco como piloto. Uma biblioteca de classes ou projeto utilitário é ideal. Começar pequeno permite que você entenda o fluxo de trabalho, crie confiança e descubra quaisquer problemas específicos do repositório antes de lidar com seu aplicativo principal.

Durante a atualização

Siga estas diretrizes enquanto o agente trabalha com sua atualização.

Usar o modo guiado para sua primeira atualização

O agente dá suporte a modos guiados e automáticos. No modo guiado, o agente faz uma pausa nos principais pontos de decisão para sua revisão e aprovação. Comece com o modo guiado para entender o que o agente faz e por quê. Alterne para o modo automático quando estiver confortável com o fluxo de trabalho.

Examine a avaliação cuidadosamente

A avaliação é a melhor oportunidade para detectar problemas antes que o agente comece a fazer alterações. Procurar por:

Projetos que o agente pode ter perdido ou identificado incorretamente.
As dependências que você conhece são problemáticas.
Qualquer coisa incomum em sua solução que o agente deve saber.

Se você detectar algo, informe o agente no chat ou adicione as informações a scenario-instructions.md. Você também pode editar assessment.md diretamente para adicionar contexto, corrigir projetos mal identificados ou sinalizar preocupações antes que o agente continue a planejar.

Reserve um tempo com o estágio de planejamento

O agente gera um plano com base em sua avaliação. Examine o plano antes de prosseguir:

A ordem faz sentido para sua base de código?
Há dependências que o agente talvez não saiba?
Algum projeto deve ser excluído ou tratado de forma diferente?

Peça ao agente para reordenar tarefas, ignorar projetos ou alterar sua abordagem. Você conhece melhor sua base de código do que o agente, portanto, use esse conhecimento. Edite o plan.md arquivo diretamente para ajustar a ordem de tarefa, adicionar tarefas ou remover tarefas.

Cuidado

Tenha cuidado ao editar plan.md diretamente. O agente pode não interpretar totalmente suas alterações se elas criarem instruções contraditórias. Por exemplo, remover um projeto de dependência mantendo os projetos que dependem dele.

Faça comentários imediatamente

O agente aprende com suas correções durante a sessão. Se o agente fizer uma escolha com a qual você discorda:

Diga imediatamente: "Não use esse padrão, use X em vez disso."
Adicione diretrizes persistentes para scenario-instructions.md para que o agente se lembre de tarefas e sessões.

Mantenha-se envolvido durante o processo de execução

A execução não é sem intervenção direta. Antes de dizer ao agente para iniciar, examine tasks.md:

A ordem de tarefa faz sentido para sua base de código?
Há tarefas que você deseja ignorar ou reorganizar?
Há alguma tarefa ausente?

Peça ao agente para ajustar a lista de tarefas ou editar tasks.md diretamente antes do início da execução. Depois que a execução for iniciada, se o agente fizer uma escolha errada no meio da tarefa, informe-o imediatamente para que a correção seja aplicada daqui para frente.

Você conhece melhor sua base de código do que o agente, portanto, use esse conhecimento em todos os estágios.

Armadilhas comuns

Observe esses problemas comuns que podem diminuir a velocidade ou complicar uma atualização.

Soluções grandes com mais de 50 projetos

O agente funciona projeto a projeto, de modo que soluções grandes levam tempo. Seja paciente e monitore o progresso. Considere começar com um projeto representativo de ponta a ponta antes de se comprometer com a solução completa. Um piloto de projeto único apresenta problemas sistêmicos mais cedo.

Feeds privados do NuGet

Para feeds privados do NuGet, autentique-se antes de iniciar a atualização (por exemplo, por meio do provedor de credenciais ou da configuração de feed da sua organização). Sem autenticação, falhas de restauração de pacote bloqueiam o progresso.

Destinos e importações personalizadas do MSBuild

Personalizações complexas de build, como arquivos personalizados .targets , importações condicionais ou lógica de build não padrão, podem confundir a avaliação e causar falhas inesperadas de build. Se sua solução tiver essas personalizações, mencione-as no chat ou em scenario-instructions.md para que o agente possa levá-las em consideração.

Tempos limite de sessão

Atualizações de execução longa podem abranger várias sessões. O agente acompanha seu progresso em arquivos de fluxo de trabalho (em .github/upgrades/), para que ele possa retomar de onde parou. Ao iniciar uma nova sessão, mencione onde você estava: "Continue a atualização do .NET 10. Eu estava no meio do projeto Data.Access."

Colaborar efetivamente

A qualidade da interação afeta diretamente a qualidade dos resultados.

Seja específico sobre o escopo

Quanto mais específico você for, melhor será o desempenho do agente:

Em vez de	Experimentar
"Atualizar tudo"	"Atualizar o projeto Data.Access para .NET 10"
"Corrigir a compilação"	"Corrigir o erro de build no CustomerService.cs relacionado à API removida"
"Migrar os componentes do banco de dados"	"Migrar o Entity Framework 6 para o EF Core no projeto do repositório"

Informe o agente sobre as restrições do mundo real antecipadamente:

"Não podemos interromper a compatibilidade com versões anteriores para a API pública."
"Temos um prazo de lançamento em duas semanas, portanto, priorize os projetos Web."
"O módulo de relatório herdado deve ser excluído dessa atualização."

Explique sua arquitetura

O agente analisa a estrutura de código, mas não sabe o modelo mental da sua equipe. Ajude o agente a entender:

"Project A é nossa biblioteca compartilhada. B, C e D dependem disso."
"O projeto WebApi é nossa API voltada para o público; Internal.Api é somente para serviços internos."
"O projeto Modelos é gerado automaticamente com base em nossa especificação OpenAPI. Não modifique-o diretamente."

Pergunte por que

O agente pode explicar seu raciocínio. Se uma decisão não parecer correta, pergunte:

"Por que você escolheu a ordem de baixo para cima?"
"Por que você está atualizando esse pacote para a versão X em vez de Y?"
"Por que você dividiu isso em subtarefas?"

Entender o raciocínio ajuda você a fornecer melhores comentários.

Salvar preferências antecipadamente

Se você tiver preferências fortes sobre estilo de codificação, padrões ou abordagens, adicione-as na primeira sessão em scenario-instructions.md. Esse arquivo persiste entre sessões e está sempre no contexto do agente, tornando-o a maneira mais confiável de influenciar o comportamento.

Recuperar-se de problemas

Use essas estratégias quando a atualização não for conforme o esperado.

Falhas de compilação após uma tarefa

Diga ao agente: "O build está falhando após a última tarefa." O agente analisa o erro e tenta corrigi-lo. Se o agente não puder resolver o problema:

Forneça uma correção manual e informe ao agente o que você fez. O agente aprende com sua correção.
Reverta a confirmação (git revert ou redefina para a confirmação anterior) e peça ao agente para tentar uma abordagem diferente.
Ignore a tarefa problemática e volte para ela mais tarde.

Estratégia errada escolhida

Se a abordagem geral do agente não funcionar para sua base de código, reinicie o estágio de planejamento:

"Vamos refazer o plano. Quero atualizar os projetos Web primeiro em vez de de baixo para cima."
"Altere a estratégia para atualizar todas as bibliotecas compartilhadas em um lote."

Agente preso em um loop

Se o agente repetir a mesma correção sem progresso, diga "Parar" e descreva o que você está observando ou interrompa a sessão manualmente. O agente pode redefinir sua abordagem e tentar algo diferente.

Desfazer todas as alterações

Se você usou um ramo do Git para a atualização, desfaça tudo retornando ao ramo original:

git checkout your-original-branch
git branch -D upgrade-branch

Seu código original está intocado. Se você estiver trabalhando sem controle do código-fonte, restaure do backup feito antes de iniciar.

Segurança e privacidade

Code snippets: GitHub Copilot processa-os de acordo com GitHub política de privacidade Copilot e não os retém além da sessão imediata.
Os arquivos de fluxo de trabalho (scenario-instructions.md, tarefas personalizadas, preferências) permanecem no repositório sob .github/upgrades/. GitHub não transmite esses arquivos para serviços externos.
A .github/upgrades/ pasta faz parte do repositório. Confirme a pasta porque ela contém o progresso e o estado da atualização. O agente precisa da pasta para retomar o trabalho entre sessões. Você pode removê-lo após a conclusão da atualização.
Telemetria: desabilite por meio das configurações de telemetria do IDE.

Dicas de desempenho

Feche arquivos e guias desnecessários: o agente analisa o espaço de trabalho ativo, e menos arquivos abertos significa menos ruído.
Atualizar em estágios para soluções muito grandes: em vez de atualizar todos os projetos de uma só vez, agrupe-os em lotes. Por exemplo, atualize todas as bibliotecas primeiro, depois todos os projetos Web e, em seguida, os testes.
Utilize cache de build: o agente executa muitas compilações incrementais durante a validação. Caches de build quentes tornam a validação significativamente mais rápida. Evite limpar a saída de build entre tarefas.

Comentários

Esta página foi útil?

Last updated on 2026-04-14