Como preparar repositórios para trabalho com IA

Um repositório para agentes de código não fica pronto quando ganha um arquivo enorme de instruções para inteligência artificial. Ele fica pronto quando comandos, convenções e limites podem ser encontrados, executados e verificados sem depender da memória de alguém.

Se um agente abre o projeto e só descobre as regras depois de errar no pull request, o problema não é a IA. É a falta de encontrabilidade operacional no próprio repositório.

O que um agente precisa encontrar antes de alterar código

Um agente de código, neste artigo, é um recurso capaz de receber uma tarefa, navegar por arquivos, sugerir ou alterar código e devolver uma proposta de mudança. Ele não substitui o julgamento da equipe. A documentação do GitHub, por exemplo, descreve recursos de agentes com ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas.

Por isso, preparar o repositório não é tentar transformar a IA em alguém que conhece a história inteira do produto. É reduzir ambiguidade no ponto em que a alteração acontece.

Antes de mexer em código, uma pessoa nova ou um agente deveria localizar três tipos de informação:

Comandos executáveis: como instalar dependências, configurar o ambiente, rodar testes, verificar estilo, gerar build e reproduzir uma falha comum.
Convenções de escrita: como o projeto organiza pastas, nomes, erros, logs, testes, mensagens de commit e pull requests.
Limites de decisão: quais áreas exigem revisão especializada, quais mudanças não devem ser feitas sem justificativa e quais comportamentos públicos não podem ser alterados como efeito colateral.

Essas informações já existem em muitas equipes, mas aparecem em lugares frágeis: uma conversa antiga, um comentário em pull request, um script com nome parecido, uma mensagem fixada no chat, uma prática conhecida por duas pessoas.

Essa fragilidade fica mais cara quando uma mudança assistida por IA parece plausível, mas viola o modo real de trabalho da equipe. O repositório preparado diminui esse espaço de improviso.

A pergunta, então, é menor e mais operacional do que a discussão ampla sobre estratégia de inteligência artificial: quando alguém abre o repositório, o que precisa estar encontrável para uma mudança assistida por IA não começar no escuro?

Comandos mínimos: instalar, testar, validar e reproduzir

O primeiro sinal de prontidão é simples: existe um caminho curto para fazer o projeto rodar e validar uma alteração?

Não precisa ser sofisticado. Precisa ser canônico. Se há cinco formas de rodar testes e nenhuma é reconhecida como principal, o agente tende a escolher pelo padrão aparente, não pelo padrão correto. O mesmo vale para um desenvolvedor novo.

Um bom ponto de entrada operacional deve responder, dentro do repositório:

Quais pré requisitos precisam existir antes de instalar dependências.
Qual comando instala ou prepara o ambiente local.
Qual comando roda os testes mais relevantes para uma alteração comum.
Qual comando valida estilo, formatação ou análise estática.
Qual comando gera build ou checa empacotamento, quando isso fizer sentido.
Qual rotina mínima reproduz um diagnóstico local antes de abrir pull request.

A diferença entre “documentar comandos” e “preparar comandos” é que o segundo exige remover concorrência. Se `test`, `test:local`, `test:new`, `check-tests` e `ci-test` fazem coisas parecidas, a equipe deve decidir qual é a porta de entrada e explicar quando usar as variações.

Também vale aproximar os comandos da integração contínua. O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados. A mesma fonte afirma que corrigir uma construção quebrada deve ter prioridade sobre novas mudanças.

Para trabalho assistido por IA, isso tem uma implicação prática: o agente não deveria ser orientado apenas a “fazer a alteração”. Ele deveria ser orientado a executar a verificação mínima que a equipe considera aceitável antes da revisão humana. Quando a verificação não existe, a tarefa ainda depende de leitura humana tardia demais.

Convenções que devem virar regra, não lembrança

Em muitas equipes, parte da revisão de código acaba corrigindo preferências que poderiam estar visíveis antes da mudança: nome de arquivo, padrão de erro, formato de teste, camada em que uma regra deve ficar, forma de registrar logs, estilo de mensagem de commit.

Quando isso acontece com pessoas, a equipe chama de alinhamento. Quando acontece com agentes, costuma chamar de alucinação ou baixa qualidade. Às vezes é mesmo. Mas, em muitos casos, o repositório não forneceu uma regra encontrável.

Há três formas melhores de tornar convenções úteis:

Automatizar quando for possível: formatação, lint, checagens simples e padrões repetitivos não deveriam depender de leitura subjetiva.
Colocar perto do uso: uma convenção de testes deve estar no template, na pasta de testes ou em um guia curto dentro do repositório, não perdida em uma apresentação antiga.
Converter reprovações recorrentes em regra: se o mesmo comentário aparece em várias revisões, ele provavelmente merece virar configuração, exemplo ou checklist.

Isso não significa transformar o repositório em enciclopédia. O objetivo é orientar alteração de código, não preservar todo o conhecimento da organização. Documentação ampla tem outro papel. Aqui, o foco é o que muda a decisão do agente ou do desenvolvedor durante a execução.

Um critério útil é perguntar: se esta convenção não for lida, a alteração pode parecer correta e ainda assim ser rejeitada? Se a resposta for sim, ela precisa estar mais próxima do código ou virar checagem.

A Anthropic define engenharia de contexto como seleção e manutenção das informações disponíveis ao modelo durante a inferência, incluindo instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada. Aplicado ao repositório, isso reforça uma escolha sobre a organização das informações: não adianta despejar tudo no contexto. É preciso tornar as informações certas fáceis de localizar.

Limites explícitos para alterações assistidas por IA

O repositório também precisa dizer onde uma alteração assistida por IA deve desacelerar.

Limite não é uma placa genérica dizendo “cuidado”. É uma instrução operacional. Ela deve apontar áreas sensíveis, tipos de mudança que exigem revisão e situações em que o agente não deve continuar sem uma decisão humana.

Alguns limites comuns em software incluem:

Autenticação, autorização e permissões.
Migrações de dados.
Cobrança, assinatura, preço, planos ou regras comerciais.
Integrações externas com comportamento público.
Arquivos de configuração de infraestrutura.
Contratos de API, eventos ou mensagens consumidas por outros sistemas.
Tratamento de dados pessoais ou informações sensíveis.

A formulação precisa ser concreta. “Não mexer em cobrança” pode bloquear mudanças legítimas. “Mudanças em cálculo de renovação, cancelamento ou elegibilidade de plano exigem justificativa no pull request e revisão de uma pessoa responsável pelo domínio” orienta melhor.

Outro ponto: limites não devem ser escondidos em um documento corporativo distante. Se o agente altera o repositório, o limite precisa estar no repositório. Pode estar em um arquivo curto de orientações, em templates de pull request, em arquivos de donos de código quando a equipe usa esse tipo de mecanismo ou em comentários próximos a pontos críticos, desde que não virem ruído.

O bom limite não tenta prever todos os erros. Ele torna visível onde a equipe não aceita avanço automático.

Essa distinção é relevante para organizações que estão avaliando adoção de IA: o repositório precisa mostrar onde a equipe autoriza, revisa, mede e interrompe uma mudança assistida.

Exemplo fictício: preparando um serviço de assinaturas

Imagine um serviço de assinaturas de uma plataforma digital. O exemplo é fictício e serve apenas para demonstrar os critérios.

O repositório tem scripts antigos, testes lentos, uma pasta de billing com regras conhecidas por poucas pessoas e comentários de revisão que se repetem: “use o helper correto”, “não altere esta regra sem revisar renovação”, “rode o teste de cancelamento antes de abrir PR”.

A equipe quer usar agentes de código para mudanças pequenas, como corrigir mensagens de erro, adicionar testes, ajustar validações e refatorar trechos localizados. Antes disso, reorganiza o repositório em cinco movimentos.

Primeiro, cria um README operacional curto. Ele não explica o produto inteiro. Explica como instalar dependências, configurar variáveis locais, rodar a aplicação em modo de desenvolvimento, executar a suíte rápida de testes e rodar a verificação usada antes do pull request.

Segundo, padroniza comandos. Em vez de deixar scripts concorrentes, define nomes previsíveis para teste local, verificação completa e lint. Scripts antigos que ainda existem recebem descrição clara ou são removidos quando deixarem de ser necessários.

Terceiro, aproxima convenções do código. A pasta de testes ganha exemplos mínimos para novas validações. O template de pull request passa a perguntar qual comportamento foi alterado, quais testes foram executados e se houve impacto em cobrança, permissões ou dados de assinantes.

Quarto, cria um arquivo curto de limites. Ele indica que mudanças em renovação, cancelamento, elegibilidade de plano e cálculo de cobrança não devem avançar sem justificativa e revisão específica. Também diferencia alterações permitidas sem revisão extra, como melhoria de nome em teste, de alterações arriscadas, como mudança em regra de transição de plano.

Quinto, deixa a próxima mudança legível dentro do repositório. Em vez de pedir ao agente “melhore o módulo de assinaturas”, a equipe pede “adicione teste para o comportamento de cancelamento quando a assinatura já está expirada, sem alterar a lógica de cobrança”.

Nada disso prova que a IA produzirá código melhor. Esse não é o ponto. A hipótese a medir seria outra: com comandos, convenções e limites encontráveis, a equipe reduz ambiguidades antes da revisão e consegue avaliar propostas menores com menos dependência de conhecimento informal.

O DORA recomenda unidades de trabalho pequenas, independentes e testáveis para obter retorno sobre mudanças e revisar hipóteses mais cedo. A mesma orientação alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA. Para o exemplo fictício, isso favorece pedidos menores e verificáveis, não grandes reformas entregues de uma vez.

Checklist de encontrabilidade para repositórios assistidos por IA

Este checklist não mede qualidade do código nem autonomia do agente. Ele mede quanto a equipe depende de conhecimento informal para orientar uma alteração. Para cada item, responda “sim”, “não” ou “parcial” e defina a ação mínima antes de ampliar o trabalho assistido por IA.

Existe um ponto de entrada operacional no repositório?

Critério: uma pessoa ou agente encontra, em até dois arquivos previsíveis, como instalar dependências, configurar ambiente local, executar testes e validar a alteração.

Se a resposta for “não” ou “parcial”, crie ou atualize um README operacional com comandos canônicos e pré requisitos. Evite transformar esse arquivo em manual extenso. Ele deve funcionar como porta de entrada.

Os comandos principais são executáveis sem interpretação?

Critério: comandos de teste, build, lint e verificação local podem ser copiados e executados sem depender de passos omitidos ou conhecimento verbal.

Se não forem, padronize scripts e remova variações concorrentes que façam a mesma coisa. Quando a variação for necessária, explique o uso com uma frase curta.

As convenções de código estão próximas do código?

Critério: regras de estrutura, estilo, testes e nomenclatura aparecem em configuração automatizada, templates ou documentação curta dentro do repositório.

Se estiverem apenas na cabeça da equipe, converta preferências recorrentes de revisão em regra documentada, exemplo ou checagem automatizada.

Há limites explícitos para áreas sensíveis?

Critério: o repositório identifica módulos, arquivos ou tipos de alteração que exigem revisão específica, justificativa ou aprovação técnica antes de avançar.

Se não houver, crie uma seção de limites com exemplos de alterações permitidas, arriscadas e proibidas sem revisão. Prefira exemplos concretos a avisos genéricos.

A definição de tarefa pequena está clara?

Critério: a equipe consegue separar uma mudança em unidade independente, testável e revisável antes de pedir ajuda a um agente de código.

Se a tarefa parece grande demais, registre primeiro qual parte do repositório deve orientar a mudança: hipótese, arquivo, comportamento ou teste verificável. O objetivo não é fragmentar tudo, mas evitar propostas que misturam refatoração, regra de negócio e ajuste visual sem um ponto claro de validação.

A revisão humana tem gatilhos objetivos?

Critério: o repositório ou template de pull request indica quando uma alteração gerada ou assistida por IA precisa de revisão adicional.

Se não indicar, adicione gatilhos como mudança em autenticação, cobrança, dados pessoais, permissões, migrações, integrações externas ou comportamento público.

A integração contínua confirma o básico?

Critério: a alteração passa por construção e testes automatizados antes de ser considerada pronta para revisão final.

Se a verificação mínima não existe, priorize uma primeira camada de integração contínua antes de ampliar alterações assistidas. Sem isso, a revisão humana vira o primeiro detector de problemas que poderiam ter sido encontrados antes.

Quando não entregar a tarefa ao agente ainda

Há situações em que a melhor decisão é preparar o repositório antes de pedir a alteração.

Se os comandos não rodam, o agente pode gastar energia contornando o ambiente em vez de resolver a tarefa. Se os testes não identificam regressões relevantes, uma mudança plausível pode passar localmente e ainda quebrar comportamento relevante. Se a área exige decisão de produto ou arquitetura não registrada, o problema não é execução de código. É decisão ausente.

Também é cedo demais quando a revisão humana não está definida. A documentação do GitHub sobre agentes ressalta supervisão humana e revisão das saídas. Isso não deve aparecer apenas no discurso de governança. Precisa aparecer no fluxo real: quem revisa, em quais gatilhos e com qual informação no pull request.

O repositório preparado para agentes de código é, no fundo, um repositório mais honesto sobre como a equipe trabalha. Ele mostra onde há automação, onde há convenção e onde há julgamento humano obrigatório.

Para a próxima adoção assistida, escolha um repositório e verifique se comandos, convenções e limites estão encontráveis antes de acionar o agente. Se não estiverem, a primeira mudança não é no produto. É no próprio repositório.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.