Como colocar agentes de programação para trabalhar com segurança

Por que isso importa

O agente concluiu a tarefa e danificou o repositório#

Um agente de codificação faz a mudança pedida, depois “limpa” um arquivo gerado, executa um comando amplo com permissões excessivas e declara sucesso após um teste estreito. A alteração parece plausível, mas viola convenções do repositório e deixa para a próxima pessoa uma falha que o fluxo não consegue explicar nem reverter.

A adoção segura começa por tornar o repositório capaz de conter essa falha. Instruções, permissões delimitadas, verificações determinísticas, revisão independente e ramificações recuperáveis importam antes de autonomia ou velocidade; são elas que inserem um modelo capaz em um processo de engenharia responsável.

Conter essa falha começa por instruções do repositório que mudam de forma observável o comportamento do agente.

Camada 1 · Contrato

Escreva o que muda o comportamento do agente#

Um AGENTS.md deve dizer como construir, testar, revisar e terminar trabalho neste repositório. Ele complementa o README humano; não deve repetir a história do produto nem toda convenção que o código já mostra.

Mantenha prioridades mutáveis em outro lugar. Um contrato curto, orientado a comandos, é mais fácil de auditar e entra menos em conflito com o estado atual. Inclua limites e quando não usar um perfil.

# Repository contract

## Allowed
- Read the repository and run documented checks.
- Edit only files required by the assigned task.
- Use the existing generator for derived pages.

## Stop conditions
- A command would expose secrets or private content.
- A required product decision is missing.
- The release gate returns HOLD or ROLLBACK.

## Definition of done
- Generated files are fresh.
- Tests and security checks pass.
- An independent reviewer verifies the diff.

Instruções repetidas podem então virar capacidades delimitadas, em vez de serem redescobertas a cada tarefa.

Camada 2 · Capacidades

Transforme trabalho repetido em capacidades reutilizáveis#

Uma capacidade reutilizável (skill) deve possuir um fluxo de trabalho: revisar migração, validar citações, executar a verificação pré-lançamento ou auditar acessibilidade. A descrição deve tornar o roteamento claro e a saída precisa de contrato verificável.

Não crie uma capacidade para cada prompt. Promova um fluxo só depois de repeti-lo e saber qual evidência separa concluído de apenas plausível.

Uma capacidade reutilizável melhora a execução, mas uma pessoa revisora com contexto novo ainda precisa inspecionar a mudança real.

Camada 3 · Revisão independente

Revise as mudanças a partir de um contexto novo#

O agente autor tem contexto e compromisso com as próprias escolhas. A pessoa revisora deve receber tarefa, regras e mudanças, e então buscar evidência de que a alteração viola o contrato.

Separe revisão de reparo. Os achados precisam de severidade, local e consequência; o autor corrige e pede nova validação somente dos gates afetados.

A revisão encontra erros de contexto; proteções executáveis impedem antes as violações que não podem ser negociadas.

Camada 4 · Proteções

Use código nos controles que o modelo não negocia#

Permissões limitam ferramentas e caminhos disponíveis. Gatilhos automatizados (hooks) executam verificações determinísticas antes de operações arriscadas ou antes de o agente declarar conclusão. A integração contínua continua sendo o controle compartilhado depois da sessão.

Instruções são política; verificações executáveis aplicam essa política. Nenhuma basta sozinha: um gatilho sem contexto bloqueia cegamente, enquanto prosa sem aplicação automática pode ser ignorada ou mal interpretada.

Com instruções, capacidades, revisão e controles, a equipe pode executar um piloto delimitado.

Caminho de adoção

Comece com uma tarefa e feche o ciclo#

Aplique a sequência a uma tarefa repetida em um repositório que a equipe já conhece. Mantenha a ramificação recuperável.

1. 01

   Reconhecer

   Escolha uma tarefa repetida em repositório conhecido pelo time.

2. 02

   Contratar

   Adicione comandos, limites e critérios de conclusão.

3. 03

   Executar

   Deixe o agente inspecionar, mudar e testar numa ramificação isolada (branch).

4. 04

   Revisar

   Use revisão independente das mudanças e corrija os achados.

5. 05

   Aprender

   Converta a falha confirmada em regra, teste ou capacidade reutilizável.

O piloto produz as evidências necessárias para responder ao checklist antes de conceder mais autonomia.

Checklist do repositório

Antes de conceder mais autonomia#

Cada resposta negativa identifica a próxima capacidade a construir no repositório. Não esconda a lacuna com um prompt mais amplo.

• ✓Comandos de compilação e teste funcionam localmente.
• ✓Segredos e caminhos sensíveis estão fora do escopo.
• ✓A tarefa tem critérios de conclusão pequenos e revisáveis.
• ✓AGENTS.md está conciso e atual.
• ✓Ferramentas perigosas pedem permissão ou são negadas.
• ✓Verificações determinísticas rodam antes da conclusão.
• ✓Uma pessoa revisora sem o contexto de autoria inspeciona as mudanças.
• ✓A ramificação e o caminho de reversão são recuperáveis.
• ✓Falhas viram testes ou instruções duráveis.
• ✓O time sabe explicar quando fazer manualmente.

A autonomia só pode aumentar quando o repositório consegue detectar, explicar e reverter a mesma classe de falha apresentada no início.

Conclusão

Amplie a autonomia somente quando o repositório puder conter a falha#

A pergunta útil não é quanto código um agente consegue gerar. É se o repositório consegue dizer o que importa, limitar o que pode ser alterado, detectar um resultado quebrado, obter revisão independente e se recuperar sem perder trabalho nem expor segredos.

Teste uma tarefa repetida e limitada em uma ramificação recuperável. Escreva o contrato, restrinja permissões, execute verificações determinísticas, revise com contexto novo e transforme a primeira falha confirmada em teste ou instrução durável. Conceda mais autonomia somente quando esse ciclo ficar mais fácil de explicar — não apenas mais rápido de executar.