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

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.

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.

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.

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.

Caminho de adoção

Comece com uma tarefa e feche o ciclo#

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.

Checklist do repositório

Antes de conceder mais autonomia#

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